ArengiBook

Bibliothèque de composants React d'Arengi, publiée sur npm sous le nom arengibook et consommée par les applications Arengi (aujourd'hui arengibox, dépôt arengi_arengibox_sf).

Storybook sert à la fois d'atelier de développement et de documentation vivante : chaque composant y est présenté avec ses variantes, ses props et le snippet d'intégration Symfony généré automatiquement.

Ce README est publié sur npm (il est inclus dans le tarball du paquet) : c'est la page que voient les consommateurs de la bibliothèque.

Sommaire de la documentation

| Document | Pour qui | Contenu | |---|---|---| | CONTRIBUTING.md | devs de la bibliothèque | Boucle de dev, anatomie d'un composant, obligations (tokens/presets/stories/doc), test local sans publier | | RELEASE.md | devs + intégrateurs | Runbook de publication npm et d'épinglage côté application. À lire avant toute publication. | | docs/architecture.md | devs de la bibliothèque | Build rollup, API publique, design tokens, cœur i18n, outillage Storybook | | docs/integration-symfony.md | intégrateurs (arengibox) | Montage des composants depuis Twig, helpers arengibookEnhance/arengibookRemount, pièges connus | | CHANGELOG.md | tous | Ce que contient chaque version publiée | | TODO_DESIGN.md | devs de la bibliothèque | Backlog des améliorations de composants | | Table.symfony.mdx (Storybook) | intégrateurs | Documentation complète du composant Table (le plus utilisé) |

Démarrage

Prérequis : Node 18 ou plus récent (validé en 18 et en 22).

nvm use 18                  # ou toute version ≥ 18
git clone [email protected]:ArengiServices/ArengiBook.git
cd ArengiBook
npm install
npm run storybook           # → http://localhost:6006

⚠️ Ne pas basculer le terminal de l'application consommatrice sur cette version de Node. arengibox tourne en Node 8.17 / npm 6 : y lancer un npm install avec un Node moderne réécrit le package-lock.json dans un format que npm 6 et le déployeur ne savent pas relire. La bonne pratique est d'exporter le PATH par commande, jamais un nvm use global — voir RELEASE.md.

| Commande | Rôle | |---|---| | npm run storybook | Atelier de dev + documentation (port 6006) | | npm run build | Construit le paquet publiable (rollup → dist/index.js) | | npm run build-storybook | Storybook statique (déploiement de la doc) | | npm run dev | Bac à sable Vite, marginal — préférer Storybook | | npm run deploy:storybook | Publie le Storybook de la branche courante sur GitHub Pages | | npm run deploy:storybook:list | Liste les Storybooks actuellement publiés | | npm run lint | ⚠️ inopérant : ESLint 9 attend un eslint.config.js qui n'existe pas dans le dépôt (la clé eslintConfig de package.json est à l'ancien format, ignorée). À réparer — voir CONTRIBUTING.md. |

Publier le Storybook (GitHub Pages)

Chaque branche peut avoir son propre Storybook en ligne, à sa propre URL — de quoi faire relire un composant en cours sans le merger, et sans écraser la doc de référence.

| Quoi | URL | Publication | |---|---|---| | main | https://arengiservices.github.io/ArengiBook/ | automatique à chaque push | | une branche | https://arengiservices.github.io/ArengiBook/branches/<branche>/ | à la demande, en local | | index de tout ce qui est en ligne | https://arengiservices.github.io/ArengiBook/branches/ | regénéré à chaque publication |

Publier sa branche

git merge origin/main          # indispensable : voir « Prérequis » ci-dessous
nvm use 20                     # Node >= 18
npm run deploy:storybook       # publie la branche git courante

Le script affiche l'URL finale en fin d'exécution. Compter deux à trois minutes (build + push + build GitHub Pages).

| Commande | Effet | |---|---| | npm run deploy:storybook | publie la branche git courante | | npm run deploy:storybook -- <nom> | publie sous un nom explicite plutôt que celui de la branche | | npm run deploy:storybook:list | liste les Storybooks actuellement en ligne | | npm run deploy:storybook -- --delete <nom> | dépublie une branche |

Prérequis : la branche doit contenir le code de main

Le script et la configuration Storybook qu'il utilise sont versionnés. Une branche créée avant leur arrivée ne les a tout simplement pas sur le disque, et npm run deploy:storybook répond « commande inconnue ». D'où le git merge origin/main préalable.

⚠️ git merge origin/main, pas git merge main. main désigne ta copie locale, qui peut avoir des jours de retard ; origin/main désigne l'état de GitHub tel que ton dernier fetch l'a vu. Fusionner un main périmé donne l'impression que le merge a marché alors que rien n'est arrivé.

Reconnaître le Storybook qu'on regarde

Hors main, le nom de la branche apparaît à trois endroits : le titre de l'onglet du navigateur, le logo de la sidebar (ARENGIBOOK — <branche>) et une pastille en bas à gauche, qui renvoie à l'index des branches. Le Storybook de main n'affiche rien de tout ça : pas de pastille = doc de référence.

Comment ça marche

Tout est servi depuis la branche gh-pages, dont l'arborescence est le site lui-même :

gh-pages
├── index.html, assets/, sb-manager/…   ← Storybook de main (racine)
└── branches/
    ├── index.html                      ← l'index listant tout
    ├── treeSelect/
    └── component-AutoCompleteGroup/

Deux producteurs écrivent dans cette branche, sans jamais se marcher dessus :

• le workflow storybook.yml, à chaque push sur main : il ne réécrit que la racine et laisse branches/ intact ;
• le script scripts/deploy-storybook.sh, lancé à la main : il n'écrit que dans branches/<slug>/.

Le script construit le Storybook avec le bon base d'URL (STORYBOOK_BASE_PATH), le copie dans un worktree git temporaire de gh-pages (.gh-pages/, ignoré par git), commite et pousse. Le nom de la branche est injecté au build via STORYBOOK_BRANCH, ce qui produit la pastille. Le push se fait en --no-verify : le hook pre-push lance Chromatic, sans objet pour de la doc statique.

Les slashs des noms de branche deviennent des tirets : component/AutoCompleteGroup est publié sous branches/component-AutoCompleteGroup/.

Côté GitHub, Settings → Pages → Source est réglé sur Deploy from a branch → gh-pages / (root). Ne pas revenir à la source « GitHub Actions » : elle ne permet qu'un seul déploiement, donc aucun sous-dossier par branche.

En cas de pépin

| Symptôme | Cause | |---|---| | npm run deploy:storybook : commande inconnue | la branche n'a pas le code de main → git merge origin/main | | build qui échoue sur un import de node_modules | dépendances désynchronisées → npm install en Node 20 | | erreur de syntaxe au build, Node introuvable | node -v renvoie une version < 18 → nvm use 20 | | 404 sur l'URL juste après un déploiement | build GitHub Pages en cours, attendre une minute puis Ctrl+Shift+R | | la pastille de branche n'apparaît pas | build fait sans STORYBOOK_BRANCH, donc hors du script — repasser par npm run deploy:storybook |

Savoir quelle version un Storybook documente

Tout Storybook déployé affiche le numéro de version lu dans le package.json au moment du build : pastille en bas de la sidebar (cliquable vers le CHANGELOG), titre de l'onglet du navigateur, et en-tête de la page Sommaire. Il n'y a rien à saisir à la main : le numéro est injecté par .storybook/main.js sous STORYBOOK_VERSION et lu par .storybook/theme.js.

Conséquence pratique : un bump de version n'apparaît en ligne qu'après un nouveau build — push sur main pour la doc de référence, npm run deploy:storybook pour une branche.

Utiliser la bibliothèque dans une application

npm install [email protected] --save-exact

⚠️ Toujours épingler une version exacte. Les numéros publiés ne suivent pas une ligne semver unique : des lignes parallèles (-datepicker jusqu'à 3.3.6, -treeselect, une 5.0.0 orpheline) portent des numéros supérieurs à la ligne officielle -main. Une plage du type ^3.2.0 résoudrait sur une version expérimentale. Voir RELEASE.md.

Les composants s'importent depuis la racine du paquet :

import { Table, TablePresets, configureI18n } from 'arengibook';

Dans arengibox, le montage se fait depuis Twig sans import explicite — voir docs/integration-symfony.md.

Carte du dépôt

src/
├── index.js                     ← API PUBLIQUE : ce qui n'est pas exporté ici n'existe pas
│                                  pour les consommateurs
├── i18n/                        ← cœur i18n (configureI18n, catalogues fr/en/es/de)
├── components/react/
│   ├── _tokens.scss             ← design system : source de vérité unique (couleurs + mixins)
│   └── <Composant>/
│       ├── <Composant>.jsx          ← le composant
│       ├── <Composant>.presets.js   ← jeux de props prêts à l'emploi + données de démo
│       ├── <Composant>.scss         ← styles (importe ../tokens)
│       ├── <Composant>.stories.jsx  ← stories Storybook = doc vivante
│       └── <Composant>.symfony.mdx  ← (optionnel) doc d'intégration Symfony
└── stories/
    ├── Configure.mdx            ← page « Sommaire » de la sidebar
    ├── Installation.mdx         ← pointeur vers RELEASE.md
    └── utils/                   ← générateurs de snippets Twig / React pour les stories
.storybook/                      ← configuration Storybook (ordre sidebar, sélecteur de locale)
scripts/
└── deploy-storybook.sh          ← publie le Storybook d'une branche sur GitHub Pages
dist/                            ← produit par `npm run build`, seul contenu publié sur npm

Composants disponibles

| Catégorie Storybook | Composants | |---|---| | Formulaire | DatePicker, Select Simple (Dropdown), Select Multiple (MultiSelect), Select Simple/Multiple Async (…MetaAsync), TreeSelect, AutoComplete, AutoCompletion, Password, ExpressionEditor | | Données | Table | | Panneau | Panel, Accordeon | | Navigation | TabView, Popup | | Superposition | Infobulle (Tooltip) | | Feedback | Toast | | Bouton | Button |

Les noms d'export exacts sont dans src/index.js. Attention : TreeSelect est un alias de TreeSelectMaquette (voir docs/architecture.md).

Les cinq règles à ne pas enfreindre

1. Node ≥ 18 pour construire la bibliothèque ; l'application consommatrice (arengibox) tourne sur Node 8.17 / npm 6 — c'est le dist transpilé qui fait le pont. Les deux environnements ne doivent jamais se mélanger dans le même shell (voir docs/architecture.md).
2. Rien n'arrive dans une application tant que la version n'est pas publiée sur npm et épinglée dans son package.json. Un commit poussé sur main ne suffit pas.
3. On publie depuis main (après merge), avec un numéro suffixé -main. Les tags jetables (-<chantier>) servent aux itérations de recette. Voir RELEASE.md.
4. Toute modification d'un composant met à jour ses stories et sa doc dans le même commit (argTypes, story de la nouveauté, .symfony.mdx s'il existe). Voir CONTRIBUTING.md.
5. Pas de code expérimental sur main : les branches de test se mergent après validation, jamais « pour voir ». Un composant de maquette parvenu sur main a déjà cassé l'intégration d'une application en recette.