@adartem/adlib-devtools

DevTools modulaire pour AdLib — inspection, debug et outils de documentation.

@adartem/adlib-devtools fournit un kit d'outils extensible pour inspecter et debugger les modules AdLib sur n'importe quelle page.

Architecture

Le package suit une architecture kernel + features :

• Kernel : registre de features, gestion CSS, scanner DOM, event bus, config, lifecycle
• Features : modules autonomes qui s'enregistrent dans le kernel (x-ray, copy, etc.)

Chaque feature recoit un FeatureContext avec les services partages (CSS, scanner, bus, config, cleanup).

Features incluses

| Feature | Fichier | Role | | --------- | ------------------ | ----------------------------------------------- | | X-Ray | dist/x-ray.js | Inspection visuelle des attributs ad-* | | Copy | dist/copy.js | Boutons de copie pour les snippets de code |

Le bundle combine dist/devtools.js inclut toutes les features.

Installation

Via CDN (bundle combine)

<script src="https://cdn.jsdelivr.net/npm/@adartem/adlib-devtools@latest/dist/devtools.js"
  adlib-doc-xray="true"
  adlib-doc-copy="true"
></script>

Options du bundle combine

| Attribut | Description | Valeurs | | ---------------- | -------------------------------- | -------------------------------- | | adlib-doc-xray | Active l'inspection visuelle | true, false, 1, 0, "" | | adlib-doc-copy | Active les boutons de copie | true, false, 1, 0, "" |

Si une option n'est pas precisee, le comportement par defaut (desactive) est applique.

<!-- Exemple : uniquement x-ray, sans copy -->
<script src="https://cdn.jsdelivr.net/npm/@adartem/adlib-devtools@latest/dist/devtools.js"
  adlib-doc-xray="true"
></script>

Via CDN (features individuelles)

<script src="https://cdn.jsdelivr.net/npm/@adartem/adlib-devtools@latest/dist/x-ray.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@adartem/adlib-devtools@latest/dist/copy.js"></script>

Via npm

pnpm add @adartem/adlib-devtools

API programmatique

window.AdLibDevTools

Quand charge via CDN, l'instance DevTools est exposee sur window.AdLibDevTools :

// Statut des features
window.AdLibDevTools.status();
// { 'x-ray': 'active', 'copy': 'active' }

// Desactiver / reactiver une feature
window.AdLibDevTools.disable('x-ray');
window.AdLibDevTools.enable('x-ray');

// Detruire tout (SPA navigation)
window.AdLibDevTools.destroy();

// Configurer une feature a runtime
window.AdLibDevTools.configure('x-ray', { 'background-color': '#ff0000' });

Import ESM

import { createDevTools, xrayFeature, copyFeature } from '@adartem/adlib-devtools';

const devtools = createDevTools({
  features: [xrayFeature, copyFeature],
});

await devtools.init();

// Plus tard :
devtools.destroy();

Creer une feature custom

import type { FeatureDefinition } from '@adartem/adlib-devtools';

const myFeature: FeatureDefinition = {
  id: 'my-tool',
  label: 'Mon Outil',
  defaults: { color: 'red' },

  init(ctx) {
    // Injecter du CSS scope
    const removeStyle = ctx.css.inject('my-tool', '.highlight { outline: 2px solid red; }');
    ctx.cleanup.add(removeStyle);

    // Scanner les elements ad-*
    const { elements } = ctx.scanner.scan();

    // Reagir aux mutations DOM
    const unsub = ctx.scanner.onMutation((added, removed) => {
      // ...
    });
    ctx.cleanup.add(unsub);

    // Communiquer avec d'autres features
    ctx.bus.emit('my-tool:ready');
  },

  destroy() {
    // Nettoyage supplementaire si necessaire
  },

  disable() {
    // Masquer sans detruire
  },

  enable(ctx) {
    // Reactiver
  },
};

// Enregistrer via l'API window
window.AdLibDevTools.register(myFeature);
window.AdLibDevTools.init('my-tool');

X-Ray

Inspection visuelle des elements porteurs d'attributs ad-*.

Fonctionnement

1. Au chargement, scanne le DOM pour les elements avec attributs ad-*.
2. Ajoute une classe CSS (x-ray par defaut) qui affiche un outline colore.
3. Au survol, affiche un tooltip listant les attributs ad-* de l'element.
4. Surveille le DOM via MutationObserver pour detecter les changements dynamiques.

Configuration

Via attributs sur le <script> (bundles standalone) :

<script
  src=".../dist/x-ray.js"
  text-color="#003238"
  background-color="#00e4ff"
  animation="fade"
  easing="ease-in-out"
  duration="150"
  key="?"
  target-class="x-ray"
></script>

| Attribut | Defaut | Description | | ------------------ | ------------- | --------------------------------------------- | | text-color | #003238 | Couleur du texte du tooltip | | background-color | #00e4ff | Couleur de fond du tooltip et de l'outline | | animation | fade | Type d'animation | | easing | ease-in-out | Fonction d'easing | | duration | 150 | Duree de l'animation en ms | | key | ? | Touche clavier pour le toggle | | target-class | x-ray | Classe CSS appliquee aux elements detectes |

Toggle clavier

Appuyer sur ? (configurable) active/desactive le mode x-ray.

Ignore

<div ad-accordion x-ray="ignore">Cet element ne sera pas surligne</div>

Copy

Copie dans le presse-papiers via des attributs declaratifs.

Pattern trigger / target

<pre ad-docs-copy="target">console.log('Hello AdLib');</pre>
<button ad-docs-copy="trigger">Copier</button>

Instance scoping

<pre ad-docs-copy="target" ad-docs-instance="alpha">Code A</pre>
<button ad-docs-copy="trigger" ad-docs-instance="alpha">Copier A</button>

Copie directe

<button ad-docs-copy="text-content">npm install @adartem/adlib-attributes</button>

Compatibilite

• ES2020 / ESM
• Backward compatible : dist/x-ray.js et dist/copy.js fonctionnent sans changement
• Fonctionne sur DOM statique et dynamique (MutationObserver)
• Lifecycle complet : init() / disable() / enable() / destroy()

Developpement

# Build (production)
pnpm --filter @adartem/adlib-devtools build

# Dev (watch + serveur port 3001)
pnpm --filter @adartem/adlib-devtools dev

# Qualite
pnpm --filter @adartem/adlib-devtools lint
pnpm --filter @adartem/adlib-devtools typecheck
pnpm --filter @adartem/adlib-devtools test

Tests

• tests/core/ — 6 suites pour le kernel (registry, config, css-manager, dom-scanner, event-bus, devtools)
• tests/features/ — tests unitaires pour chaque feature
• tests/integration/ — tests lifecycle complet multi-features

Documentation de reference

Ce package heberge egalement la documentation normative d'AdLib :

• Specifications — Runtime, Loader, Module Contract
• Standards — API Stability, Compatibility, Definition of Done
• Getting Started
• Conventions de documentation

Licence

MIT (c) ADARTEM