@adartem/adlib-docs

v0.0.2

Published

2 months ago

Scripts et helpers dédiés à la documentation d'AdLib (x-ray, copy snippets, etc.).

Downloads

0High
0Medium
0Low

joshua-divialle

adlib adartem docs tooling

@adartem/adlib-doc

Helpers dédiés à la documentation AdLib.

@adartem/adlib-doc fournit des outils légers, autonomes et entièrement optionnels destinés aux pages de documentation, de démonstration et de playground.

Ce package :

❌ ne fait pas partie du runtime AdLib
❌ n’est jamais requis pour utiliser les attributs ad-* en production
✅ est conçu uniquement pour améliorer l’expérience de lecture et de compréhension

🎯 Objectif du package

@adartem/adlib-doc a pour but de :

améliorer la lisibilité des exemples,
rendre les pages de documentation visuelles et interactives,
faciliter la compréhension des attributs ad-*,
proposer des outils activables à la demande,
rester sans impact sur le runtime et les performances applicatives.

Cas d’usage typiques

pages GitHub Pages
sites de documentation
démos locales
playgrounds HTML statiques
pages pédagogiques ou ateliers

✨ Outils inclus

🔍 xray

Inspection visuelle des éléments porteurs d’attributs AdLib :

ad-*
data-ad-*

Fonctionnement :

surligne dynamiquement les éléments concernés,
ajoute un marqueur visuel discret,
permet d’identifier immédiatement où les comportements sont déclarés dans le DOM.

👉 Idéal pour expliquer la nature déclarative d’AdLib sans lire le code source.

📋 copy-snippet

Ajoute des boutons de copie (clipboard) sur les blocs de code :

<pre><code>
snippets HTML
exemples JavaScript
démonstrations copiables en un clic

Fonctionnement :

détection automatique des blocs de code,
bouton discret, non intrusif,
copie fiable du contenu affiché.

👉 Améliore fortement l’UX des pages de documentation.

🧩 doc

Bootstrap global combinant xray + copy-snippet.

Caractéristiques :

configuration via attributs data-*,
aucun JavaScript impératif requis,
initialisation automatique,
cleanup possible,
usage simple via CDN.

👉 Recommandé pour la majorité des pages de documentation AdLib.

📦 Installation

pnpm add @adartem/adlib-doc
# ou
npm i @adartem/adlib-doc

🚀 Utilisation — doc.js (recommandé)

doc.js est un bootstrap prêt à l’emploi.

Il s’auto-configure via des attributs data-adlib-doc-* directement sur la balise <script>.

Snippet CDN

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@adartem/adlib-doc/doc.js"
  data-adlib-doc-xray="true"
  data-adlib-doc-copy="true"
></script>

Options disponibles

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

👉 Si une option n’est pas précisée, le comportement par défaut (activé) est appliqué.

🧩 Utilisation — API JavaScript

Pour un contrôle plus fin ou une intégration personnalisée.

import { bootstrapDoc } from '@adartem/adlib-doc/doc';

const cleanup = bootstrapDoc({
  xray: true,
  copy: true,
});

// plus tard (nettoyage)
cleanup();

bootstrapDoc() retourne toujours une fonction de cleanup
aucune pollution globale
aucun état persistant caché

🧱 Outils individuels

🔍 X-Ray

Surligne dynamiquement les éléments porteurs d’attributs AdLib.

import { attachXRay } from '@adartem/adlib-doc';

const cleanup = attachXRay(document, {
  selector: '*',
  className: 'adlib-xray',
  markerAttr: 'data-adlib-xray',
});

// désactivation
cleanup();

Options :

selector : éléments à inspecter
className : classe CSS appliquée
markerAttr : attribut ajouté aux éléments détectés

📋 Copy Snippet

Ajoute des boutons de copie sur les blocs de code.

import { attachCopyButtons } from '@adartem/adlib-doc';

const cleanup = attachCopyButtons();

// désactivation
cleanup();

Fonctionnement :

scan automatique des <pre><code>,
bouton injecté dynamiquement,
Clipboard API standard.

📄 Exemple complet (reproductible)

Exemple minimal d’une page de documentation utilisant doc.js.

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <title>AdLib – Doc helpers</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />

    <style>
      body {
        font-family: system-ui, sans-serif;
        padding: 2rem;
        line-height: 1.5;
      }
      pre {
        padding: 1rem;
        border: 1px solid #ddd;
        border-radius: 8px;
        overflow: auto;
      }
      code {
        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
      }
      .card {
        margin-top: 2rem;
        padding: 1rem;
        border: 1px solid #eee;
        border-radius: 12px;
      }
    </style>
  </head>

  <body>
    <h1>AdLib — adlib-doc</h1>

    <div class="card">
      <h2>Blocs de code (copy)</h2>
      <pre><code>&lt;script type="module" src=".../attributes.js" ad-click&gt;&lt;/script&gt;</code></pre>
      <pre><code>console.log("Hello AdLib");</code></pre>
    </div>

    <div class="card">
      <h2>Éléments porteurs d’attributs (xray)</h2>

      <button data-ad-click data-ad-click-toggle="is-active">
        Bouton (data-ad-click)
      </button>

      <div
        ad-click
        style="margin-top: 1rem; padding: .75rem; border: 1px dashed #bbb;"
      >
        Bloc (ad-click)
      </div>
    </div>

    <!-- Bootstrap doc helpers -->
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/@adartem/adlib-doc/doc.js"
      data-adlib-doc-xray="true"
      data-adlib-doc-copy="true"
    ></script>
  </body>
</html>

🔧 Compatibilité

ES2020
ESM uniquement
Sourcemaps inclus
SSR-safe (aucune exécution hors DOM)
Aucun effet de bord global
Aucun lien avec le runtime AdLib

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@adartem/adlib-doc

🎯 Objectif du package

Cas d’usage typiques

✨ Outils inclus

🔍 xray

📋 copy-snippet

🧩 doc

📦 Installation

🚀 Utilisation — doc.js (recommandé)

Snippet CDN

Options disponibles

🧩 Utilisation — API JavaScript

🧱 Outils individuels

🔍 X-Ray

📋 Copy Snippet

📄 Exemple complet (reproductible)

🔧 Compatibilité

🪪 Licence