arengibook 3.2.2-main → 3.2.4-main
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -9
- package/dist/index.js +1004 -555
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,20 +1,135 @@
|
|
|
1
1
|
# ArengiBook
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Bibliothèque de composants React d'Arengi, publiée sur npm sous le nom **`arengibook`** et
|
|
4
|
+
consommée par les applications Arengi (aujourd'hui **arengibox**, dépôt `arengi_arengibox_sf`).
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Storybook sert à la fois d'atelier de développement et de documentation vivante : chaque
|
|
7
|
+
composant y est présenté avec ses variantes, ses props et le snippet d'intégration Symfony
|
|
8
|
+
généré automatiquement.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
> **Ce README est publié sur npm** (il est inclus dans le tarball du paquet) : c'est la page
|
|
11
|
+
> que voient les consommateurs de la bibliothèque.
|
|
8
12
|
|
|
9
|
-
|
|
10
|
-
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Sommaire de la documentation
|
|
16
|
+
|
|
17
|
+
| Document | Pour qui | Contenu |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | devs de la bibliothèque | Boucle de dev, anatomie d'un composant, obligations (tokens/presets/stories/doc), test local sans publier |
|
|
20
|
+
| [`RELEASE.md`](RELEASE.md) | devs + intégrateurs | Runbook de publication npm et d'épinglage côté application. **À lire avant toute publication.** |
|
|
21
|
+
| [`docs/architecture.md`](docs/architecture.md) | devs de la bibliothèque | Build rollup, API publique, design tokens, cœur i18n, outillage Storybook |
|
|
22
|
+
| [`docs/integration-symfony.md`](docs/integration-symfony.md) | intégrateurs (arengibox) | Montage des composants depuis Twig, helpers `arengibookEnhance`/`arengibookRemount`, pièges connus |
|
|
23
|
+
| [`CHANGELOG.md`](CHANGELOG.md) | tous | Ce que contient chaque version publiée |
|
|
24
|
+
| [`TODO_DESIGN.md`](TODO_DESIGN.md) | devs de la bibliothèque | Backlog des améliorations de composants |
|
|
25
|
+
| `Table.symfony.mdx` (Storybook) | intégrateurs | Documentation complète du composant `Table` (le plus utilisé) |
|
|
11
26
|
|
|
12
|
-
|
|
27
|
+
---
|
|
13
28
|
|
|
29
|
+
## Démarrage
|
|
30
|
+
|
|
31
|
+
Prérequis : **Node 18 ou plus récent** (validé en 18 et en 22).
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
nvm use 18 # ou toute version ≥ 18
|
|
35
|
+
git clone git@github.com:ArengiServices/ArengiBook.git
|
|
36
|
+
cd ArengiBook
|
|
14
37
|
npm install
|
|
38
|
+
npm run storybook # → http://localhost:6006
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
> ⚠️ **Ne pas basculer le terminal de l'application consommatrice sur cette version de Node.**
|
|
42
|
+
> arengibox tourne en **Node 8.17 / npm 6** : y lancer un `npm install` avec un Node moderne
|
|
43
|
+
> réécrit le `package-lock.json` dans un format que npm 6 et le déployeur ne savent pas relire.
|
|
44
|
+
> La bonne pratique est d'exporter le `PATH` par commande, jamais un `nvm use` global — voir
|
|
45
|
+
> [`RELEASE.md`](RELEASE.md#0-cohabitation-des-versions-de-node).
|
|
46
|
+
|
|
47
|
+
| Commande | Rôle |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `npm run storybook` | Atelier de dev + documentation (port 6006) |
|
|
50
|
+
| `npm run build` | Construit le paquet publiable (`rollup` → `dist/index.js`) |
|
|
51
|
+
| `npm run build-storybook` | Storybook statique (déploiement de la doc) |
|
|
52
|
+
| `npm run dev` | Bac à sable Vite, marginal — préférer Storybook |
|
|
53
|
+
| `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`. |
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Utiliser la bibliothèque dans une application
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm install arengibook@3.2.2-main --save-exact
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
⚠️ **Toujours épingler une version exacte.** Les numéros publiés ne suivent pas une ligne
|
|
64
|
+
semver unique : des lignes parallèles (`-datepicker` jusqu'à `3.3.6`, `-treeselect`, une `5.0.0`
|
|
65
|
+
orpheline) portent des numéros *supérieurs* à la ligne officielle `-main`. Une plage du type
|
|
66
|
+
`^3.2.0` résoudrait sur une version expérimentale. Voir [`RELEASE.md`](RELEASE.md).
|
|
67
|
+
|
|
68
|
+
Les composants s'importent depuis la racine du paquet :
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
import { Table, TablePresets, configureI18n } from 'arengibook';
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Dans arengibox, le montage se fait depuis Twig sans import explicite — voir
|
|
75
|
+
[`docs/integration-symfony.md`](docs/integration-symfony.md).
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Carte du dépôt
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
src/
|
|
83
|
+
├── index.js ← API PUBLIQUE : ce qui n'est pas exporté ici n'existe pas
|
|
84
|
+
│ pour les consommateurs
|
|
85
|
+
├── i18n/ ← cœur i18n (configureI18n, catalogues fr/en/es/de)
|
|
86
|
+
├── components/react/
|
|
87
|
+
│ ├── _tokens.scss ← design system : source de vérité unique (couleurs + mixins)
|
|
88
|
+
│ └── <Composant>/
|
|
89
|
+
│ ├── <Composant>.jsx ← le composant
|
|
90
|
+
│ ├── <Composant>.presets.js ← jeux de props prêts à l'emploi + données de démo
|
|
91
|
+
│ ├── <Composant>.scss ← styles (importe ../tokens)
|
|
92
|
+
│ ├── <Composant>.stories.jsx ← stories Storybook = doc vivante
|
|
93
|
+
│ └── <Composant>.symfony.mdx ← (optionnel) doc d'intégration Symfony
|
|
94
|
+
└── stories/
|
|
95
|
+
├── Configure.mdx ← page « Sommaire » de la sidebar
|
|
96
|
+
├── Installation.mdx ← pointeur vers RELEASE.md
|
|
97
|
+
└── utils/ ← générateurs de snippets Twig / React pour les stories
|
|
98
|
+
.storybook/ ← configuration Storybook (ordre sidebar, sélecteur de locale)
|
|
99
|
+
dist/ ← produit par `npm run build`, seul contenu publié sur npm
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Composants disponibles
|
|
105
|
+
|
|
106
|
+
| Catégorie Storybook | Composants |
|
|
107
|
+
|---|---|
|
|
108
|
+
| Formulaire | DatePicker, Select Simple (`Dropdown`), Select Multiple (`MultiSelect`), Select Simple/Multiple Async (`…MetaAsync`), TreeSelect, AutoComplete, AutoCompletion, Password, ExpressionEditor |
|
|
109
|
+
| Données | Table |
|
|
110
|
+
| Panneau | Panel, Accordeon |
|
|
111
|
+
| Navigation | TabView, Popup |
|
|
112
|
+
| Superposition | Infobulle (`Tooltip`) |
|
|
113
|
+
| Feedback | Toast |
|
|
114
|
+
| Bouton | Button |
|
|
115
|
+
|
|
116
|
+
Les noms d'export exacts sont dans [`src/index.js`](src/index.js). Attention : `TreeSelect` est
|
|
117
|
+
un **alias** de `TreeSelectMaquette` (voir [`docs/architecture.md`](docs/architecture.md)).
|
|
15
118
|
|
|
16
|
-
|
|
119
|
+
---
|
|
17
120
|
|
|
18
|
-
|
|
121
|
+
## Les cinq règles à ne pas enfreindre
|
|
19
122
|
|
|
20
|
-
|
|
123
|
+
1. **Node ≥ 18 pour construire** la bibliothèque ; l'application consommatrice (arengibox) tourne
|
|
124
|
+
sur **Node 8.17 / npm 6** — c'est le `dist` transpilé qui fait le pont. Les deux
|
|
125
|
+
environnements ne doivent jamais se mélanger dans le même shell (voir
|
|
126
|
+
[`docs/architecture.md`](docs/architecture.md)).
|
|
127
|
+
2. **Rien n'arrive dans une application tant que la version n'est pas publiée sur npm *et*
|
|
128
|
+
épinglée** dans son `package.json`. Un commit poussé sur `main` ne suffit pas.
|
|
129
|
+
3. **On publie depuis `main`** (après merge), avec un numéro suffixé `-main`. Les tags jetables
|
|
130
|
+
(`-<chantier>`) servent aux itérations de recette. Voir [`RELEASE.md`](RELEASE.md).
|
|
131
|
+
4. **Toute modification d'un composant met à jour ses stories et sa doc** dans le même commit
|
|
132
|
+
(argTypes, story de la nouveauté, `.symfony.mdx` s'il existe). Voir [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
133
|
+
5. **Pas de code expérimental sur `main`** : les branches de test se mergent après validation,
|
|
134
|
+
jamais « pour voir ». Un composant de maquette parvenu sur `main` a déjà cassé l'intégration
|
|
135
|
+
d'une application en recette.
|