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 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. |

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)
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.