{"_id":"@adartem/adlib-docs","name":"@adartem/adlib-docs","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.2":{"name":"@adartem/adlib-docs","version":"0.0.2","description":"Scripts et helpers dédiés à la documentation d'AdLib (x-ray, copy snippets, etc.).","private":false,"publishConfig":{"access":"public"},"license":"MIT","type":"module","main":"src/index.ts","module":"src/index.ts","homepage":"https://adartem.fr","repository":{"type":"git","url":"git+https://github.com/adartem/adlib.git","directory":"packages/adlib-docs"},"bugs":{"url":"https://github.com/adartem/adlib/support"},"keywords":["adlib","adartem","docs","tooling"],"dependencies":{"@floating-ui/dom":"^1.7.5","just-debounce":"^1.1.0","@adartem/adlib-utils":"0.1.0"},"devDependencies":{"cross-env":"^10.1.0","esbuild":"^0.27.2"},"scripts":{"build":"cross-env NODE_ENV=production node ./bin/build.js","dev":"cross-env NODE_ENV=development node ./bin/build.js","typecheck":"tsc --noEmit","lint":"eslint ./src && prettier --check ./src","lint:fix":"eslint ./src --fix && prettier --write ./src","test":"vitest run -c ../../vitest.config.ts","docs:check":"tsx scripts/check-doc-links.ts"},"_id":"@adartem/adlib-docs@0.0.2","_integrity":"sha512-tdtX1n5aJEQ6dCMY2FpyJgQc8897AckqW3mLC1nGSqYg0ueglFM2DvcXsvO7sUHA/PPKhapRc1W1IfWwXzYatg==","_resolved":"/tmp/931c5014a8deb67237f614a484342f72/adartem-adlib-docs-0.0.2.tgz","_from":"file:adartem-adlib-docs-0.0.2.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-tdtX1n5aJEQ6dCMY2FpyJgQc8897AckqW3mLC1nGSqYg0ueglFM2DvcXsvO7sUHA/PPKhapRc1W1IfWwXzYatg==","shasum":"930492cbadfede90a60672ea7900c7a1df3feeba","tarball":"https://registry.npmjs.org/@adartem/adlib-docs/-/adlib-docs-0.0.2.tgz","fileCount":5,"unpackedSize":92165,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAbAIs5Id2/0NXC63d0ZO+l3GFQwJusRRgccOD2D++i1AiAVwvz3dy7tOl30L3zhq+zfo5uzWZT2P2P/1Y52HFfAvw=="}]},"_npmUser":{"name":"joshua-divialle","email":"divialle.joshua2@gmail.com"},"directories":{},"maintainers":[{"name":"joshua-divialle","email":"divialle.joshua2@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/adlib-docs_0.0.2_1769954047568_0.826410235778517"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-01T13:54:07.510Z","0.0.2":"2026-02-01T13:54:07.717Z","modified":"2026-02-01T13:54:07.888Z"},"maintainers":[{"name":"joshua-divialle","email":"divialle.joshua2@gmail.com"}],"description":"Scripts et helpers dédiés à la documentation d'AdLib (x-ray, copy snippets, etc.).","homepage":"https://adartem.fr","keywords":["adlib","adartem","docs","tooling"],"repository":{"type":"git","url":"git+https://github.com/adartem/adlib.git","directory":"packages/adlib-docs"},"bugs":{"url":"https://github.com/adartem/adlib/support"},"license":"MIT","readme":"# @adartem/adlib-doc\n\nHelpers dédiés à la **documentation AdLib**.\n\n`@adartem/adlib-doc` fournit des outils légers, autonomes et entièrement optionnels\ndestinés aux pages de **documentation**, de **démonstration** et de **playground**.\n\nCe package :\n\n- ❌ ne fait pas partie du runtime AdLib\n- ❌ n’est jamais requis pour utiliser les attributs `ad-*` en production\n- ✅ est conçu uniquement pour améliorer l’expérience de lecture et de compréhension\n\n---\n\n## 🎯 Objectif du package\n\n`@adartem/adlib-doc` a pour but de :\n\n- améliorer la lisibilité des exemples,\n- rendre les pages de documentation visuelles et interactives,\n- faciliter la compréhension des attributs `ad-*`,\n- proposer des outils activables à la demande,\n- rester sans impact sur le runtime et les performances applicatives.\n\n### Cas d’usage typiques\n\n- pages GitHub Pages\n- sites de documentation\n- démos locales\n- playgrounds HTML statiques\n- pages pédagogiques ou ateliers\n\n---\n\n## ✨ Outils inclus\n\n### 🔍 xray\n\nInspection visuelle des éléments porteurs d’attributs AdLib :\n\n- `ad-*`\n- `data-ad-*`\n\n**Fonctionnement :**\n\n- surligne dynamiquement les éléments concernés,\n- ajoute un marqueur visuel discret,\n- permet d’identifier immédiatement **où** les comportements sont déclarés dans le DOM.\n\n👉 Idéal pour expliquer la nature déclarative d’AdLib sans lire le code source.\n\n---\n\n### 📋 copy-snippet\n\nAjoute des boutons de copie (clipboard) sur les blocs de code :\n\n- `
`\n- snippets HTML\n- exemples JavaScript\n- démonstrations copiables en un clic\n\n**Fonctionnement :**\n\n- détection automatique des blocs de code,\n- bouton discret, non intrusif,\n- copie fiable du contenu affiché.\n\n👉 Améliore fortement l’UX des pages de documentation.\n\n---\n\n### 🧩 doc\n\nBootstrap global combinant **xray + copy-snippet**.\n\n**Caractéristiques :**\n\n- configuration via attributs `data-*`,\n- aucun JavaScript impératif requis,\n- initialisation automatique,\n- cleanup possible,\n- usage simple via CDN.\n\n👉 Recommandé pour la majorité des pages de documentation AdLib.\n\n---\n\n## 📦 Installation\n\n```bash\npnpm add @adartem/adlib-doc\n# ou\nnpm i @adartem/adlib-doc\n```\n\n---\n\n## 🚀 Utilisation — doc.js (recommandé)\n\n`doc.js` est un bootstrap prêt à l’emploi.\n\nIl s’auto-configure via des attributs `data-adlib-doc-*`\ndirectement sur la balise `\n```\n\n### Options disponibles\n\n| Attribut | Description | Valeurs |\n|--------|------------|---------|\n| `data-adlib-doc-xray` | Active l’inspection visuelle | `true`, `false`, `1`, `0`, `\"\"` |\n| `data-adlib-doc-copy` | Active les boutons de copie | `true`, `false`, `1`, `0`, `\"\"` |\n\n👉 Si une option n’est pas précisée, le comportement par défaut (**activé**) est appliqué.\n\n---\n\n## 🧩 Utilisation — API JavaScript\n\nPour un contrôle plus fin ou une intégration personnalisée.\n\n```ts\nimport { bootstrapDoc } from '@adartem/adlib-doc/doc';\n\nconst cleanup = bootstrapDoc({\n  xray: true,\n  copy: true,\n});\n\n// plus tard (nettoyage)\ncleanup();\n```\n\n- `bootstrapDoc()` retourne toujours une fonction de cleanup\n- aucune pollution globale\n- aucun état persistant caché\n\n---\n\n## 🧱 Outils individuels\n\n### 🔍 X-Ray\n\nSurligne dynamiquement les éléments porteurs d’attributs AdLib.\n\n```ts\nimport { attachXRay } from '@adartem/adlib-doc';\n\nconst cleanup = attachXRay(document, {\n  selector: '*',\n  className: 'adlib-xray',\n  markerAttr: 'data-adlib-xray',\n});\n\n// désactivation\ncleanup();\n```\n\n**Options :**\n\n- `selector` : éléments à inspecter\n- `className` : classe CSS appliquée\n- `markerAttr` : attribut ajouté aux éléments détectés\n\n---\n\n### 📋 Copy Snippet\n\nAjoute des boutons de copie sur les blocs de code.\n\n```ts\nimport { attachCopyButtons } from '@adartem/adlib-doc';\n\nconst cleanup = attachCopyButtons();\n\n// désactivation\ncleanup();\n```\n\n**Fonctionnement :**\n\n- scan automatique des `
`,\n- bouton injecté dynamiquement,\n- Clipboard API standard.\n\n---\n\n## 📄 Exemple complet (reproductible)\n\nExemple minimal d’une page de documentation utilisant `doc.js`.\n\n```html\n\n\n  \n    \n    AdLib – Doc helpers\n    \n\n    \n  \n\n  \n    
AdLib — adlib-doc
\n\n    
\n      
Blocs de code (copy)
\n      
<script type=\"module\" src=\".../attributes.js\" ad-click></script>
\n      
console.log(\"Hello AdLib\");
\n    
\n\n    
\n      
Éléments porteurs d’attributs (xray)
\n\n      \n\n      \n        Bloc (ad-click)\n      
\n    \n\n    \n    \n  \n\n```\n\n---\n\n## 🔧 Compatibilité\n\n- ES2020\n- ESM uniquement\n- Sourcemaps inclus\n- SSR-safe (aucune exécution hors DOM)\n- Aucun effet de bord global\n- Aucun lien avec le runtime AdLib\n\n---\n\n## 🪪 Licence\n\nMIT © ADARTEM","readmeFilename":"README.md","_rev":"1-5da2c8ef5dbb95c67f13e87a2b4d7cd6"}