@adartem/adlib-attributes

@adartem/adlib-attributes est le package central de la plateforme AdLib.
Il regroupe le core unifié, le runtime global et le loader officiel attributes.js.

👉 C’est le seul point d’entrée requis pour utiliser AdLib côté navigateur.

🎯 Rôle

• Loader ESM universel (dist/attributes.js)
• Runtime global unique
• Core d’événements et de délégation
• Chargement dynamique des modules ad-*
• Auto-scan optionnel du DOM
• API globale exposée via window.AdLibAttributes

📦 Contenu du package

Loader

• Fichier distribué : dist/attributes.js
• Conçu pour être chargé via CDN ou bundler
• Initialise automatiquement le runtime dans le navigateur

Runtime

• Orchestration des modules ad-*
• Gestion des états (idle, loading, ready, error)
• Import dynamique ESM
• API globale stable

Core

• Délégation d’événements
• Émission d’événements personnalisés
• Enregistrement et cycle de vie des modules
• Support DOM statique et dynamique

🌍 API globale

Une fois le loader chargé, le runtime est exposé globalement :

window.AdLibAttributes

Interface principale

interface AdLibRuntime {
  version: string;
  config: RuntimeConfig;
  core: Core;
  debug: boolean;

  modules: Record<string, RuntimeModuleState>;

  load(key: ModuleKey): Promise<RuntimeModuleState>;
  reload(key: ModuleKey): Promise<RuntimeModuleState>;
  push(
    key: ModuleKey,
    cb: (state: RuntimeModuleState) => void
  ): void;

  /**
   * Détruit le runtime et les modules chargés.
   * ⚠️ Ne détruit PAS le Core singleton partagé.
   */
  destroy(options?: { keepGlobal?: boolean }): void;
}

🧭 États des modules

Chaque module ad-* expose un état :

• idle — non chargé
• loading — import en cours
• ready — initialisé
• error — échec d’import ou d’initialisation

Accessible via :

window.AdLibAttributes.modules['ad-click']

⏳ File d’attente globale (queue)

Avant le chargement effectif du runtime, il est possible de déclarer des callbacks dans une file globale :

window.AdLibAttributesQueue = [
  ['ad-click', (state) => {
    if (state.status === 'ready') {
      console.log('ad-click prêt');
    }
  }]
];

👉 Le runtime consomme automatiquement cette queue à l’initialisation.

🔍 Scan du DOM & conventions

Attributs reconnus

• ad-*
• data-ad-*

Exemples équivalents :

<button ad-click></button>
<button data-ad-click></button>

Auto-scan

Lorsque l’option auto est activée :

• Scan initial du DOM
• Observation des ajouts dynamiques (MutationObserver)
• Chargement automatique des modules requis

🔗 Résolution dynamique des modules

Chaque module ad-* est résolu via une map interne au runtime.

Logique de résolution (simplifiée) :

{registry|base}/@adartem/ad-click@{version}/dist/index.js

Les paramètres de résolution sont configurables via les attributs data-adlib-* du loader.

🚀 Snippets recommandés

Intégration standard (head ou footer)

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@adartem/adlib-attributes@latest/dist/attributes.js"
  data-adlib-auto="true"
  ad-click
></script>

Paramètres disponibles

| Attribut | Description | |--------|-------------| | ad-* | Modules à charger | | data-adlib-auto | Active l’auto-scan | | data-adlib-registry | Registry CDN | | data-adlib-base | Base URL personnalisée | | data-adlib-version | Version des modules | | data-adlib-debug | Logs debug |

👉 Tous les paramètres sont optionnels.

🧩 Utilisation avec bundler

Le package peut aussi être importé directement (side-effect import) :

import '@adartem/adlib-attributes/attributes.js';

👉 Le loader s’exécute automatiquement en environnement navigateur.

📦 Exports & distribution

• Bundle ESM
• Compatible CDN (jsDelivr, unpkg, etc.)
• Fichiers générés dans dist/
• Sourcemaps incluses

🧪 Développement

pnpm -r --filter @adartem/adlib-attributes build
pnpm -r test

🪪 Licence

MIT © ADARTEM