@adartem/adlib-attributes

@adartem/adlib-attributes est le package central de la plateforme AdLib.

Il fournit un point d’entrée unique côté navigateur, combinant :

• le loader officiel attributes.js (ESM)
• le runtime global singleton (window.AdLibAttributes)
• le core unifié de gestion des modules et du DOM

👉 Aucun autre package n’est requis côté navigateur pour utiliser AdLib.

✅ Loader officiel : 2 URLs équivalentes

AdLib expose deux formes de loader strictement équivalentes :

✅ Loader court (recommandé — Webflow / copy-paste)

<script
  type="module"
  src="<https://cdn.jsdelivr.net/npm/@adartem/adlib-attributes@latest/attributes.js>"
></script>

🔁 Loader long (équivalent — chemin dist)

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

👉 Recommandation : utilise le loader court pour Webflow/live (DX + robustesse).

⚡ Quickstart — API Queue (copy / paste)

Le moyen le plus simple et recommandé pour exécuter du code

lorsqu’un module AdLib est prêt :

<script>
window.AdLibAttributes ||= [];
window.AdLibAttributes.push([
"ad-click",
(state) => {
if (state.status ==="ready") {
console.log("ad-click prêt");
      }
    },
  ]);
</script>

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

Garanties

• si le module est déjà ready ou error, le callback est exécuté immédiatement
• sinon, il est attaché au chargement en cours
• un même callback ne s’exécute jamais deux fois pour un même push

Plusieurs modules

window.AdLibAttributes ||= [];
window.AdLibAttributes.push(
  ["ad-click",(st) =>console.log("click", st.status)],
  ["ad-modal",(st) =>console.log("modal", st.status)]
);

Pattern de compatibilité

window.AdLibAttributesQueue = [
  ["ad-click",(state) =>console.log(state.status)],
];

👉 Les deux patterns sont automatiquement détectés et drainés au bootstrap.

🎯 Objectifs du package

• Loader ESM universel (attributes.js recommandé, dist/attributes.js équivalent)
• Runtime global singleton (window.AdLibAttributes)
• Core d’événements et de délégation DOM
• Chargement dynamique des modules ad-*
• Scan automatique (optionnel) du DOM
• API publique stable, idempotente et observable

🧱 Architecture générale

attributes.js (loader)
        ↓
Runtime global (singleton)
        ↓
Core (events, delegation, lifecycle)
        ↓
Modules ad-* (chargés dynamiquement)

Le runtime est conçu pour être :

• idempotent (re-import ESM, init safe)
• déterministe
• observable (événements + état)
• robuste aux erreurs

📦 Contenu

Loader (attributes.js)

• Fichiers distribués :
  • attributes.js (entrée courte, recommandée)
  • dist/attributes.js (entrée longue, équivalente)
• Chargement via CDN ou bundler
• Initialisation automatique du runtime navigateur
• Lecture de la configuration via data-adlib-*
• Détection des modules demandés via attributs ad-*
• Consommation automatique de la file d’attente globale (queue)

Runtime

• Orchestration complète du cycle de vie des modules ad-*
• États gérés : idle, loading, ready, error
• Import dynamique ESM
• API publique stable
• Dispatch d’événements globaux
• Gestion centralisée des erreurs
• Support de la queue window.AdLibAttributes.push(...)

👉 Le contrat runtime est documenté ici : docs/runtime-contract.md

Core

• Délégation d’événements DOM
• Émission d’événements internes
• Gestion des instances de modules
• Support du DOM statique et dynamique
• Aucune dépendance à un framework

📜 Contrat des modules (référence)

Les modules ad-* doivent respecter un contrat strict :

• default export : { key, init(core) }
• init() retourne une instance : { key, destroy(), restart?() }
• délégation DOM (pas de listeners par élément)
• parsing d’options stable
• guards réutilisables
• accessibilité sur triggers non interactifs
• cleanup complet et idempotent

👉 Spécification complète : src/contracts/module-contract.md

🚀 Installation

Via CDN (recommandé)

✅ Loader court :

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

🔁 Loader long (équivalent) :

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

L’attribut ad-click sur le script loader indique au runtime de charger le module ad-click.

Via bundler

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

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

🌍 API globale

Une fois le loader exécuté, le runtime est accessible globalement :

window.AdLibAttributes;

🧩 Interface publique du runtime

Ce bloc est une représentation de l’API publique (pour lecture rapide).

interfaceAdLibRuntime {
version:string;
config:RuntimeConfig;

core:Core;
debug:boolean;

auto:boolean;
observeAttributes:boolean;

modules:Partial<Record<ModuleKey,RuntimeModuleState>>;
scripts:HTMLScriptElement[];

load(key:ModuleKey):Promise<RuntimeModuleState>;

reload(
key:ModuleKey,
options?: {rescan?:boolean }
  ):Promise<RuntimeModuleState>;

push(
    ...items: (
      | [ModuleKey,(state:RuntimeModuleState) =>void]
      | {key:ModuleKey;cb:(state:RuntimeModuleState) =>void }
    )[]
  ):void;

initFromScripts(source:InitSource):void;

destroy(options?: {keepGlobal?:boolean }):void;
}

👉 Seules ces méthodes constituent l’API publique stable.

🧭 États des modules (runtime)

Chaque module ad-* possède un état runtime explicite :

• idle — module connu mais non chargé
• loading — import ou initialisation en cours
• ready — module initialisé et actif
• error — échec d’import ou d’initialisation

Exemple :

const state =window.AdLibAttributes.modules["ad-click"];

if (state?.status ==="ready") {
// state.instance disponible
}

👉 Les invariants complets sont documentés ici : docs/runtime-contract.md

📣 Événements runtime globaux

Émis sur window :

• ad:module:before
• ad:module:after
• ad:module:error

window.addEventListener("ad:module:after",(e) => {
const { key, state } = e.detail;
console.log(`${key} prêt`, state.status);
});

👉 L’état transmis est un snapshot immuable.

🔍 Scan du DOM & conventions

Attributs reconnus

• ad-*
• data-ad-*

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

Auto-scan (recommandé)

Active le scan initial + observation DOM :

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

Observation des mutations d’attributs (opt-in)

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

Désactivé par défaut pour des raisons de performance.

⚙️ Configuration loader (data-adlib-*)

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

⚠️ Règles importantes (actuelles)

• ❌ Un seul loader par page

• ❌ Ne pas charger attributes.js plusieurs fois

  (une évolution “multi-loader idempotent” est prévue)

🧪 Développement

pnpm -r --filter @adartem/adlib-attributes lint
pnpm -r --filter @adartem/adlib-attributes typecheck
pnpm -r --filter @adartem/adlib-attributes test

🪪 Licence

MIT © ADARTEM