@situaction/traquiste-docs-kit 1.0.0 → 1.1.0
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/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,10 @@
|
|
|
1
|
+
# [1.1.0](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/compare/v1.0.0...v1.1.0) (2026-10-21)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Features
|
|
5
|
+
|
|
6
|
+
* statut 'updated' (badge Mis à jour) ([f44dbd3](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/f44dbd354b7d34f3125d57e21c57dbbbcd548b7d))
|
|
7
|
+
|
|
1
8
|
# 1.0.0 (2026-10-20)
|
|
2
9
|
|
|
3
10
|
|
package/README.md
CHANGED
|
@@ -1,61 +1,139 @@
|
|
|
1
1
|
# @situaction/traquiste-docs-kit
|
|
2
2
|
|
|
3
|
-
Moteur de documentation partagé par les libs UI Traquiste :
|
|
3
|
+
Moteur de site de documentation pour bibliothèques de composants React, partagé par les libs UI Traquiste :
|
|
4
4
|
- [`traq-ui-ste`](https://bitbucket.org/winoc/traq-ui-ste) (web) ;
|
|
5
5
|
- [`traq-ui-ste-mobile`](https://bitbucket.org/winoc/traq-ui-ste-mobile) (React Native, rendu via react-native-web).
|
|
6
6
|
|
|
7
7
|
Chaque lib garde sa propre doc (pages, config, déploiement). Le kit fournit l'outil :
|
|
8
|
-
- la mise en page : sidebar, barre du haut, recherche ⌘K, bascule light/dark, table des matières ;
|
|
9
|
-
-
|
|
10
|
-
- les tableaux de props générés depuis le code TypeScript des composants (plugin Vite `docgen`) ;
|
|
11
|
-
- les pages de guide (Prise en main, Theming…) : `DocPage`, `DocSection`, `CodeBlock`, `Callout` ;
|
|
12
|
-
- les pages d'écrans complets (flux de connexion, back-office…) dans un téléphone ou une fenêtre de navigateur
|
|
13
|
-
- l'
|
|
14
|
-
- les routes, la sidebar et la recherche, générées depuis la liste
|
|
15
|
-
- la navigation : titre d'onglet par page, retour en haut
|
|
8
|
+
- la mise en page : sidebar, barre du haut, recherche ⌘K, bascule light / dark, table des matières ;
|
|
9
|
+
- les **pages composant** : titre, statut, lien Figma, ligne d'import, démos live par section, tableau des props ;
|
|
10
|
+
- les **tableaux de props générés** depuis le code TypeScript des composants (plugin Vite `docgen`) ;
|
|
11
|
+
- les **pages de guide** (Prise en main, Theming…) : `DocPage`, `DocSection`, `CodeBlock`, `Callout`, `Link` ;
|
|
12
|
+
- les **pages d'écrans complets** (flux de connexion, back-office…) dans un téléphone ou une fenêtre de navigateur ;
|
|
13
|
+
- l'**éditeur live** (Monaco + Babel) avec copier / reset, redimensionnement et cadre téléphone ;
|
|
14
|
+
- les routes, la sidebar et la recherche, générées depuis la liste des pages ;
|
|
15
|
+
- la navigation : titre d'onglet par page, retour en haut, liens directs vers une ancre, page 404 ;
|
|
16
16
|
- le mode sombre : il suit la préférence système et mémorise le choix du visiteur.
|
|
17
17
|
|
|
18
|
-
##
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
Dans le dossier de la doc de la lib (en général `docs/`, un projet Vite à part) :
|
|
19
21
|
|
|
20
22
|
```bash
|
|
21
23
|
npm install -D @situaction/traquiste-docs-kit
|
|
24
|
+
npm install react react-dom
|
|
25
|
+
npm install -D vite @vitejs/plugin-react typescript
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
| Peer dependency | Version | |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| `react`, `react-dom` | `^18 \|\| ^19` | obligatoires |
|
|
31
|
+
| `vite` | `6`, `7` ou `8` | le kit est publié en ESM et importe son CSS : la doc doit être construite avec Vite |
|
|
32
|
+
| `typescript` | `>= 5` | nécessaire au plugin `docgen` |
|
|
33
|
+
|
|
34
|
+
`react-router-dom` est fourni par le kit : ne pas l'installer en plus (voir `Link` dans Pages de guide).
|
|
35
|
+
|
|
36
|
+
## Mise en place
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
docs/
|
|
40
|
+
index.html
|
|
41
|
+
vite.config.ts
|
|
42
|
+
tsconfig.json
|
|
43
|
+
src/
|
|
44
|
+
main.tsx
|
|
45
|
+
docs.config.tsx
|
|
46
|
+
pages/
|
|
47
|
+
components/button.ts
|
|
48
|
+
guides/GettingStarted.tsx
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`index.html` — le site se monte dans `#root`. Le kit ne charge aucune police : c'est à la doc de le faire.
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<!doctype html>
|
|
55
|
+
<html lang="fr">
|
|
56
|
+
<head>
|
|
57
|
+
<meta charset="UTF-8" />
|
|
58
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
59
|
+
<title>traquiste-mobile</title>
|
|
60
|
+
<link href="https://fonts.googleapis.com/css2?family=Urbanist:wght@400;500;600;700&display=swap" rel="stylesheet" />
|
|
61
|
+
</head>
|
|
62
|
+
<body>
|
|
63
|
+
<div id="root"></div>
|
|
64
|
+
<script type="module" src="/src/main.tsx"></script>
|
|
65
|
+
</body>
|
|
66
|
+
</html>
|
|
22
67
|
```
|
|
23
68
|
|
|
24
|
-
`
|
|
69
|
+
`vite.config.ts` :
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { defineConfig } from 'vite'
|
|
73
|
+
import react from '@vitejs/plugin-react'
|
|
74
|
+
import { docgen } from '@situaction/traquiste-docs-kit/vite'
|
|
75
|
+
|
|
76
|
+
export default defineConfig({
|
|
77
|
+
plugins: [
|
|
78
|
+
react(),
|
|
79
|
+
// Chemins relatifs au dossier docs/
|
|
80
|
+
docgen({ include: ['../src/components/**/*.tsx'], tsconfig: '../tsconfig.json' }),
|
|
81
|
+
],
|
|
82
|
+
})
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Les alias propres à une lib restent dans ce fichier : `react-native` → `react-native-web` et stubs côté mobile,
|
|
86
|
+
`sass` côté web…
|
|
87
|
+
|
|
88
|
+
`tsconfig.json` — pour typer le module généré par `docgen` :
|
|
89
|
+
|
|
90
|
+
```json
|
|
91
|
+
{ "compilerOptions": { "types": ["vite/client", "@situaction/traquiste-docs-kit/client"] } }
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`src/docs.config.tsx` :
|
|
25
95
|
|
|
26
96
|
```tsx
|
|
27
97
|
import { defineDocsConfig } from '@situaction/traquiste-docs-kit'
|
|
28
98
|
import { ThemeProvider } from '@situaction/traquiste-mobile'
|
|
29
|
-
import ButtonPage from './src/pages/components/button'
|
|
30
|
-
import pkg from '../package.json'
|
|
31
99
|
import componentProps from 'virtual:traquiste-docs/props'
|
|
100
|
+
import pkg from '../../package.json'
|
|
101
|
+
import GettingStarted from './pages/guides/GettingStarted'
|
|
102
|
+
import ButtonPage from './pages/components/button'
|
|
32
103
|
|
|
33
104
|
export default defineDocsConfig({
|
|
34
|
-
brand: { name: 'traquiste-mobile', subtitle: 'by Situaction', version: pkg.version },
|
|
105
|
+
brand: { name: 'traquiste-mobile', subtitle: 'by Situaction', logo: '/logo-situaction.svg', version: pkg.version },
|
|
35
106
|
links: [
|
|
36
|
-
{ label: '
|
|
107
|
+
{ label: 'npm', href: 'https://www.npmjs.com/package/@situaction/traquiste-mobile' },
|
|
37
108
|
{ label: 'Figma', href: 'https://www.figma.com/…' },
|
|
38
109
|
],
|
|
39
110
|
packageName: '@situaction/traquiste-mobile',
|
|
40
111
|
componentProps,
|
|
41
|
-
// Enveloppe chaque démo live
|
|
112
|
+
// Enveloppe chaque démo live : le thème de la lib suit la bascule light / dark de la doc
|
|
42
113
|
wrapper: ({ mode, children }) => <ThemeProvider colorScheme={mode}>{children}</ThemeProvider>,
|
|
43
114
|
pages: [
|
|
115
|
+
{ group: 'Général', label: 'Prise en main', path: '/guides/getting-started', component: GettingStarted },
|
|
44
116
|
{ group: 'Composants', label: 'Button', path: '/components/button', component: ButtonPage },
|
|
45
117
|
],
|
|
46
118
|
})
|
|
47
119
|
```
|
|
48
120
|
|
|
49
|
-
`
|
|
121
|
+
`pages` donne à la fois les routes, la sidebar (groupes dans l'ordre de première apparition) et la recherche.
|
|
122
|
+
Ajouter une page = un import + une ligne.
|
|
123
|
+
|
|
124
|
+
`src/main.tsx` :
|
|
50
125
|
|
|
51
126
|
```tsx
|
|
52
127
|
import { createDocsApp } from '@situaction/traquiste-docs-kit'
|
|
53
|
-
import config from '
|
|
128
|
+
import config from './docs.config'
|
|
54
129
|
|
|
55
130
|
createDocsApp(config, document.getElementById('root')!)
|
|
56
131
|
```
|
|
57
132
|
|
|
58
|
-
|
|
133
|
+
Puis `npx vite` pour le serveur de dev, `npx vite build` pour le site statique (à servir avec une redirection de
|
|
134
|
+
toutes les routes vers `index.html` : le site utilise l'historique du navigateur).
|
|
135
|
+
|
|
136
|
+
## Pages composant
|
|
59
137
|
|
|
60
138
|
```ts
|
|
61
139
|
import { createComponentPage } from '@situaction/traquiste-docs-kit'
|
|
@@ -64,14 +142,75 @@ import { Button } from '@situaction/traquiste-mobile'
|
|
|
64
142
|
export default createComponentPage({
|
|
65
143
|
title: 'Button',
|
|
66
144
|
description: "Bouton d'action.",
|
|
145
|
+
status: 'stable',
|
|
146
|
+
figma: 'https://www.figma.com/design/…',
|
|
67
147
|
scope: { Button },
|
|
68
|
-
demos: [
|
|
148
|
+
demos: [
|
|
149
|
+
{ section: 'Variantes', title: 'Primary', code: `<Button label="Valider" />` },
|
|
150
|
+
{ section: 'Variantes', title: 'Ghost', code: `<Button label="Annuler" variant="ghost" />` },
|
|
151
|
+
{ section: 'États', title: 'Désactivé', code: `<Button label="Valider" disabled />` },
|
|
152
|
+
],
|
|
69
153
|
// Lu dans l'interface TypeScript du composant et ses JSDoc (plugin docgen)
|
|
70
154
|
props: 'auto',
|
|
71
155
|
})
|
|
72
156
|
```
|
|
73
157
|
|
|
74
|
-
|
|
158
|
+
| Option | Description |
|
|
159
|
+
|---|---|
|
|
160
|
+
| `title` | Titre de la page. **C'est aussi le nom du composant** dans la ligne d'import (`import { Button } from '…'`) et pour `props: 'auto'` |
|
|
161
|
+
| `description` | Paragraphe sous le titre |
|
|
162
|
+
| `status` | Badge : `'stable'`, `'beta'`, `'new'` (Nouveau), `'updated'` (Mis à jour), `'deprecated'` (Déprécié) |
|
|
163
|
+
| `figma` | Lien vers le composant Figma (bouton à droite de la description) |
|
|
164
|
+
| `scope` | Ce que le code des démos peut utiliser : composants, hooks, icônes… `React` est injecté d'office |
|
|
165
|
+
| `demos` | Les démos, dans l'ordre (voir ci-dessous) |
|
|
166
|
+
| `props` | `'auto'` (plugin `docgen`) ou tableau écrit à la main : `[{ name, type, required, default?, description }]` |
|
|
167
|
+
| `propsOf` | Composant à lire avec `props: 'auto'` quand il diffère de `title` |
|
|
168
|
+
|
|
169
|
+
Chaque démo :
|
|
170
|
+
|
|
171
|
+
| Champ | Description |
|
|
172
|
+
|---|---|
|
|
173
|
+
| `section` | Titre H2 (ancre et entrée du sommaire), affiché quand il change d'une démo à l'autre |
|
|
174
|
+
| `sectionDescription` | Paragraphe sous ce titre |
|
|
175
|
+
| `title` | En-tête de la carte |
|
|
176
|
+
| `code` | **Une expression JSX**, éditable en direct (voir ci-dessous) |
|
|
177
|
+
| `phoneFrame` | Affiche l'aperçu dans un téléphone, pour les composants pleine largeur |
|
|
178
|
+
|
|
179
|
+
Le code d'une démo est une expression, sans `import` ni instruction au premier niveau. Plusieurs éléments → un
|
|
180
|
+
fragment `<>…</>`. Pour de l'état, créer un composant à la volée :
|
|
181
|
+
|
|
182
|
+
```jsx
|
|
183
|
+
React.createElement(() => {
|
|
184
|
+
const [on, setOn] = React.useState(false)
|
|
185
|
+
return <Switch value={on} onValueChange={setOn} />
|
|
186
|
+
})
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Le JSX est compilé dans le navigateur (preset `react` de Babel) : pas de syntaxe TypeScript dans les démos.
|
|
190
|
+
Une démo qui plante affiche son erreur dans sa carte, sans casser le reste de la page.
|
|
191
|
+
|
|
192
|
+
## Props générées (plugin `docgen`)
|
|
193
|
+
|
|
194
|
+
Le plugin lit les composants à la compilation et expose `virtual:traquiste-docs/props`
|
|
195
|
+
(`{ [nomDuComposant]: PropDef[] }`), à passer en `componentProps` à `defineDocsConfig`.
|
|
196
|
+
|
|
197
|
+
| Option de `docgen()` | Description |
|
|
198
|
+
|---|---|
|
|
199
|
+
| `include` | Globs des fichiers de composants, relatifs à la racine Vite (ex. `['../src/components/**/*.tsx']`) |
|
|
200
|
+
| `exclude` | Globs à ignorer. Les `*.stories.*`, `*.test.*`, `*.spec.*` et `node_modules` le sont toujours |
|
|
201
|
+
| `tsconfig` | tsconfig de la lib, relatif à la racine Vite. Par défaut : options JSX standard |
|
|
202
|
+
|
|
203
|
+
- Ce qui est lu : nom, type (unions de littéraux développées : `'primary' | 'ghost'`), obligatoire ou non, valeur
|
|
204
|
+
par défaut (déstructuration `variant = 'primary'`), description JSDoc `/** … */`.
|
|
205
|
+
- Les props héritées des types React / React Native (`ButtonHTMLAttributes`, `ViewProps`, `PressableProps`…) sont
|
|
206
|
+
masquées : seule l'API propre au composant apparaît. Pour montrer une prop héritée (par ex. `onPress`), la
|
|
207
|
+
redéclarer dans l'interface du composant avec son JSDoc.
|
|
208
|
+
- Seuls les composants (nom en PascalCase) sont retenus : les constantes et helpers exportés sont ignorés.
|
|
209
|
+
- En dev, modifier un composant met son tableau à jour (rechargement de la page).
|
|
210
|
+
- Si les props d'un composant sont introuvables, la page l'indique avec les points à vérifier au lieu d'afficher
|
|
211
|
+
un tableau vide.
|
|
212
|
+
|
|
213
|
+
## Pages de guide
|
|
75
214
|
|
|
76
215
|
Pour les pages de texte (Prise en main, Theming, Changelog…), avec le même rendu que les pages composant :
|
|
77
216
|
|
|
@@ -94,18 +233,25 @@ export default function GettingStarted() {
|
|
|
94
233
|
}
|
|
95
234
|
```
|
|
96
235
|
|
|
97
|
-
- `DocPage` : titre, description et **table des matières générée** à partir des `DocSection` (même imbriquées dans
|
|
236
|
+
- `DocPage` : titre, description et **table des matières générée** à partir des `DocSection` (même imbriquées dans
|
|
237
|
+
d'autres composants).
|
|
98
238
|
- `DocSection` : titre H2 et ancre (`États` → `#etats`), avec `id` pour la choisir et `description` pour un chapeau.
|
|
99
|
-
- Le texte écrit en JSX simple (`p`, `h3`, `ul
|
|
100
|
-
|
|
101
|
-
- `
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
239
|
+
- Le texte écrit en JSX simple (`p`, `h3`, `ul` / `ol`, `a`, `strong`, `code`) est mis en forme automatiquement.
|
|
240
|
+
Les démos insérées dans un guide (`LiveEditor`) gardent leur propre rendu.
|
|
241
|
+
- `CodeBlock` : code statique avec un bouton copier, sans coloration syntaxique. L'indentation commune est
|
|
242
|
+
retirée : on peut écrire le code dans un template literal indenté. `language` ou `title` (par ex. un nom de
|
|
243
|
+
fichier) s'affiche dans l'en-tête.
|
|
244
|
+
- `Callout` : encadré `info` (défaut), `tip`, `warning` ou `danger`, avec `title` facultatif. Ses couleurs suivent
|
|
245
|
+
le thème clair / sombre.
|
|
246
|
+
- `Link` : lien interne sans rechargement. C'est le `Link` de react-router, réexporté pour utiliser le même
|
|
247
|
+
routeur que la doc.
|
|
248
|
+
- `LiveEditor` : une démo live dans une page libre (Exemples, guide) —
|
|
249
|
+
`<LiveEditor title="Formulaire" initialCode={code} scope={{ Button, Input }} />`.
|
|
250
|
+
|
|
251
|
+
## Écrans complets
|
|
252
|
+
|
|
253
|
+
Pour montrer des écrans entiers construits avec la lib (flux de connexion, liste, formulaire…), un onglet par
|
|
254
|
+
écran :
|
|
109
255
|
|
|
110
256
|
```tsx
|
|
111
257
|
import { createScreenPage } from '@situaction/traquiste-docs-kit'
|
|
@@ -127,127 +273,85 @@ export default createScreenPage({
|
|
|
127
273
|
})
|
|
128
274
|
```
|
|
129
275
|
|
|
130
|
-
- `device` : `'phone'` (390 × 760 par défaut) ou `'browser'` (1024 × 640, avec `url` affichée dans la barre
|
|
131
|
-
|
|
276
|
+
- `device` : `'phone'` (390 × 760 par défaut) ou `'browser'` (1024 × 640, avec `url` affichée dans la barre
|
|
277
|
+
d'adresse, aussi réglable écran par écran). `width` et `height` changent la taille.
|
|
278
|
+
- Chaque écran est rendu dans le `wrapper` de la config : il suit le thème de la lib et le mode clair / sombre.
|
|
279
|
+
Un écran dont la racine a `flex: 1` remplit toute la hauteur de l'appareil ; au-delà, il défile à l'intérieur.
|
|
132
280
|
- L'écran affiché est dans l'URL (`?screen=mot-de-passe`) : on peut donner un lien direct vers un écran.
|
|
133
|
-
- Onglets, flèches du clavier, boutons Précédent / Suivant, et panneau « Écran 2 / 4 » avec description, notes et
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
### Props générées (plugin `docgen`)
|
|
139
|
-
|
|
140
|
-
`docs/vite.config.ts` :
|
|
141
|
-
|
|
142
|
-
```ts
|
|
143
|
-
import { docgen } from '@situaction/traquiste-docs-kit/vite'
|
|
144
|
-
|
|
145
|
-
export default defineConfig({
|
|
146
|
-
plugins: [
|
|
147
|
-
react(),
|
|
148
|
-
// Chemins relatifs au dossier docs/
|
|
149
|
-
docgen({ include: ['../src/components/**/*.tsx'], tsconfig: '../tsconfig.json' }),
|
|
150
|
-
],
|
|
151
|
-
})
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Pour typer le module généré, dans le `tsconfig` de la doc : `"types": ["@situaction/traquiste-docs-kit/client"]`.
|
|
155
|
-
|
|
156
|
-
- `props: 'auto'` lit les props du composant qui porte le nom de la page (`title`). Si le nom diffère, ajouter `propsOf: 'NomDuComposant'`.
|
|
157
|
-
- Les écrire à la main reste possible : `props: [{ name, type, required, default?, description }]`.
|
|
158
|
-
- Ce qui est lu : nom, type (unions de littéraux développées : `'primary' | 'ghost'`), obligatoire ou non, valeur par défaut (déstructuration `variant = 'primary'`), description JSDoc `/** … */`.
|
|
159
|
-
- Les props héritées des types React / React Native (`ButtonHTMLAttributes`, `ViewProps`, `PressableProps`…) sont masquées : seule l'API propre au composant apparaît. Pour montrer une prop héritée (par ex. `onPress`), la redéclarer dans l'interface du composant avec son JSDoc.
|
|
160
|
-
- Les stories et les tests sont ignorés ; les exports qui ne sont pas des composants (`MARKER_HEIGHT`, `getBearingSector`) aussi.
|
|
161
|
-
- En dev, modifier un composant met son tableau à jour (rechargement de la page).
|
|
162
|
-
- Si les props d'un composant sont introuvables, la page l'indique avec les points à vérifier au lieu d'afficher un tableau vide.
|
|
281
|
+
- Onglets, flèches du clavier, boutons Précédent / Suivant, et panneau « Écran 2 / 4 » avec description, notes et
|
|
282
|
+
composants utilisés. Un composant qui a une page dans la doc (même `label`) devient un lien vers elle.
|
|
283
|
+
- `DeviceFrame` est exporté pour les pages libres :
|
|
284
|
+
`<DeviceFrame device="browser" url="app.fr" height={600}>…</DeviceFrame>`.
|
|
163
285
|
|
|
164
|
-
|
|
286
|
+
## Thème
|
|
165
287
|
|
|
166
|
-
|
|
288
|
+
- **Thème de la lib** : `wrapper` enveloppe chaque démo et chaque écran, `appWrapper` tout le site (pour les pages
|
|
289
|
+
qui utilisent le thème de la lib hors démos). Les deux reçoivent `mode: 'light' | 'dark'`.
|
|
290
|
+
- Les couleurs d'une démo doivent venir du thème de la lib (par ex. `useTheme()` côté mobile, à mettre dans
|
|
291
|
+
`scope`), jamais d'une valeur fixe : sinon elles ne suivent pas la bascule light / dark.
|
|
292
|
+
- `useColorMode()` donne `{ mode, setMode, toggle }` pour les pages qui ont besoin du mode courant.
|
|
293
|
+
- **Police de la doc** : variable CSS `--docs-font-family` (défaut `'Urbanist'`, puis police système), à charger
|
|
294
|
+
dans l'`index.html`.
|
|
295
|
+
- Le CSS de la doc résiste aux styles globaux qu'une lib peut injecter (`:root, body { width: 100vw }`, règles
|
|
296
|
+
`h1`–`h6`).
|
|
167
297
|
|
|
168
|
-
|
|
298
|
+
## Référence de `defineDocsConfig`
|
|
169
299
|
|
|
170
300
|
| Option | Requis | Description |
|
|
171
301
|
|---|---|---|
|
|
172
|
-
| `brand` | oui | `{ name, showName?, subtitle?, logo?, version? }`. En-tête de la sidebar : `logo` (URL d'image, par ex. `/logo-situaction.svg` dans le `public/` de la doc), `name` et `subtitle
|
|
302
|
+
| `brand` | oui | `{ name, showName?, subtitle?, logo?, version? }`. En-tête de la sidebar : `logo` (URL d'image, par ex. `/logo-situaction.svg` dans le `public/` de la doc), `name` et `subtitle`. `name` sert aussi au titre des onglets et de texte alternatif au logo. `showName: false` le masque quand le logo contient déjà le nom (sans logo, le nom est toujours affiché). `version` s'affiche en bas de la sidebar |
|
|
173
303
|
| `links` | non | `{ label, href }[]` dans la barre du haut. Les URL `https://…` s'ouvrent dans un nouvel onglet, les chemins (`/examples`) restent dans le site |
|
|
174
|
-
| `packageName` | oui | Package utilisé dans la ligne `import { X } from '…'` des pages
|
|
175
|
-
| `wrapper` | non | Enveloppe chaque démo live, en général le `ThemeProvider` de la lib. Reçoit `mode
|
|
176
|
-
| `appWrapper` | non | Enveloppe tout le site
|
|
177
|
-
| `componentProps` | non |
|
|
304
|
+
| `packageName` | oui | Package utilisé dans la ligne `import { X } from '…'` des pages composant |
|
|
305
|
+
| `wrapper` | non | Enveloppe chaque démo live et chaque écran, en général le `ThemeProvider` de la lib. Reçoit `mode` |
|
|
306
|
+
| `appWrapper` | non | Enveloppe tout le site. Reçoit `mode` |
|
|
307
|
+
| `componentProps` | non | `import componentProps from 'virtual:traquiste-docs/props'` (plugin `docgen`), pour `props: 'auto'` |
|
|
178
308
|
| `home` | non | Page affichée sur `/`. Par défaut : redirection vers la première page |
|
|
179
309
|
| `pages` | oui | `{ group, label, path, component }[]`, dans l'ordre de la sidebar |
|
|
180
310
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
-
|
|
184
|
-
- `
|
|
185
|
-
-
|
|
186
|
-
- `
|
|
187
|
-
- `DocPage`, `DocSection`, `CodeBlock`, `Callout`, `Link`
|
|
188
|
-
- `createScreenPage` (types `ScreenPageConfig`, `ScreenConfig`) et `DeviceFrame` (types `DeviceFrameProps`, `DeviceType`)
|
|
311
|
+
## API exportée
|
|
312
|
+
|
|
313
|
+
`@situaction/traquiste-docs-kit` :
|
|
314
|
+
- `createDocsApp(config, container)` et `DocsApp` (le site sans routeur, pour un montage manuel)
|
|
315
|
+
- `defineDocsConfig`, `useDocsConfig` — types `DocsConfig`, `DocsPage`, `DocsLink`, `DocsWrapper`, `ColorMode`, `NavGroup`, `NavItem`
|
|
316
|
+
- `createComponentPage` — types `ComponentPageConfig`, `Demo`, `PropDef`, `ComponentProps`, `ComponentStatus`
|
|
317
|
+
- `DocPage`, `DocSection`, `CodeBlock`, `Callout`, `Link` — types `DocPageProps`, `DocSectionProps`, `CodeBlockProps`, `CalloutProps`, `CalloutType`
|
|
318
|
+
- `createScreenPage` (types `ScreenPageConfig`, `ScreenConfig`) et `DeviceFrame` (types `DeviceFrameProps`, `DeviceType`)
|
|
319
|
+
- `LiveEditor`
|
|
189
320
|
- `useColorMode` → `{ mode, setMode, toggle }`
|
|
190
321
|
|
|
322
|
+
`@situaction/traquiste-docs-kit/vite` : `docgen(options)` (plugin Vite) et `findComponentFiles`.
|
|
323
|
+
|
|
324
|
+
`@situaction/traquiste-docs-kit/client` : types du module `virtual:traquiste-docs/props`.
|
|
325
|
+
|
|
191
326
|
## Compatibilité
|
|
192
|
-
- `react` / `react-dom` : `^18 || ^19`, en `peerDependencies`. La lib web est en 18, la doc mobile en 19.
|
|
193
|
-
- `typescript` (≥ 5) et `vite` (6 à 8) : `peerDependencies` facultatives, utilisées seulement par le plugin `docgen` — ce sont celles de la doc qui l'utilise.
|
|
194
|
-
- Le playground tourne en React 19, mais le kit est typé avec `@types/react` 18 : TypeScript refuse donc les API réservées à React 19. La CI lance aussi les tests en React 18.
|
|
195
|
-
- Les consommateurs doivent utiliser Vite : le kit est publié en ESM et importe son CSS.
|
|
196
327
|
|
|
197
|
-
|
|
328
|
+
- React 18 et 19 (testé sur les deux en CI). La lib web est en 18, la doc mobile en 19.
|
|
329
|
+
- Vite 6 à 8, TypeScript 5 et plus.
|
|
330
|
+
- Composants React DOM et React Native (via `react-native-web`, alias configuré par la doc de la lib).
|
|
331
|
+
- L'éditeur de code des démos (Monaco) est chargé depuis le CDN jsDelivr à son ouverture.
|
|
332
|
+
- Mise en page prévue pour un écran d'ordinateur.
|
|
198
333
|
|
|
199
|
-
|
|
334
|
+
## Versions
|
|
200
335
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
index.ts API publique : tout ce qui est importable passe par ici
|
|
204
|
-
app/ montage du site : createDocsApp, config (DocsConfig), mode clair / sombre
|
|
205
|
-
pages/ modèles de pages : createComponentPage, createScreenPage, DocPage
|
|
206
|
-
components/ briques des pages : LiveEditor, PropsTable, DeviceFrame, CodeBlock, Callout
|
|
207
|
-
layout/ cadre du site : Layout, Sidebar, recherche, table des matières, 404
|
|
208
|
-
hooks/ hooks partagés (useCopy)
|
|
209
|
-
styles/ docs.css (variables --docs-*) et styles des pages
|
|
210
|
-
vite/ plugin docgen (code Node, non chargé dans le navigateur)
|
|
211
|
-
tests/ tests vitest, même arborescence que src/
|
|
212
|
-
helpers/ config et rendu de test (renderDocs)
|
|
213
|
-
fixtures/ composants d'exemple pour le plugin docgen
|
|
214
|
-
playground/ mini doc pour développer le kit (non publiée)
|
|
215
|
-
native/ composants React Native de démo
|
|
216
|
-
pages/ pages d'exemple : composants, guides, écrans
|
|
217
|
-
```
|
|
336
|
+
Le [CHANGELOG](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/src/master/CHANGELOG.md), aussi publié dans le package, liste les changements de chaque version. Un changement
|
|
337
|
+
incompatible arrive avec une version majeure. Pour monter de version dans une lib :
|
|
218
338
|
|
|
219
339
|
```bash
|
|
220
|
-
npm install
|
|
221
|
-
npm run dev # playground sur http://localhost:5173 et http://<ip-de-la-machine>:5173
|
|
222
|
-
npm run typecheck
|
|
223
|
-
npm run lint
|
|
224
|
-
npm test # vitest : monte le site avec une config de test (tests/helpers/renderDocs.tsx)
|
|
225
|
-
npm run build # dist/ (JS + .d.ts + CSS)
|
|
226
|
-
npm run preview # playground buildé (après npm run build:playground), aussi accessible par l'IP
|
|
340
|
+
npm install -D @situaction/traquiste-docs-kit@latest
|
|
227
341
|
```
|
|
228
342
|
|
|
229
|
-
|
|
230
|
-
- `playground/native/DemoChip.tsx` : composant RN (`Pressable`, `StyleSheet`, props d'accessibilité) dont le thème vient d'un contexte (`useDemoTheme`), comme le `useTheme` de la lib mobile ;
|
|
231
|
-
- page **Chip** : démos RN (dont une avec état et une dans un téléphone), props lues par `docgen` depuis les types RN ;
|
|
232
|
-
- page **Réglages (React Native)** : écrans complets en `View` / `Text` / `ScrollView`, dont une liste qui défile dans le téléphone.
|
|
233
|
-
|
|
234
|
-
`react-native` est installé en dépendance de dev pour ses types (le plugin `docgen` en a besoin). Ses types sont forcés sur les types React 18 du kit (`overrides` dans `package.json`).
|
|
235
|
-
|
|
236
|
-
Le serveur écoute sur toutes les interfaces réseau : Vite affiche l'adresse `Network` à ouvrir depuis un autre appareil (téléphone, autre poste) sur le même réseau. Le port se change avec la variable `PORT` (`PORT=5180 npm run dev`).
|
|
237
|
-
|
|
238
|
-
Le dossier `playground/` est un mini site de doc qui sert à développer le kit sans dépendre d'une lib. Il n'est pas publié.
|
|
343
|
+
puis vérifier toutes les pages de la doc.
|
|
239
344
|
|
|
240
|
-
|
|
241
|
-
- un alias `'@situaction/traquiste-docs-kit'` → `'../../traq-ui-ste-docs-kit/src/index.ts'` ;
|
|
242
|
-
- ou `npm link`.
|
|
345
|
+
## Contribuer
|
|
243
346
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
-
|
|
247
|
-
- `develop` → prerelease `next`.
|
|
347
|
+
Le code, le playground et la documentation interne du kit (architecture, tests, publication, problèmes connus)
|
|
348
|
+
sont sur [Bitbucket](https://bitbucket.org/winoc/traq-ui-ste-docs-kit), dans le dossier
|
|
349
|
+
[`docs/`](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/src/master/docs/README.md).
|
|
248
350
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
351
|
+
```bash
|
|
352
|
+
npm install
|
|
353
|
+
npm run dev # playground sur http://localhost:5173
|
|
354
|
+
npm run typecheck && npm run lint && npm test && npm run build
|
|
355
|
+
```
|
|
252
356
|
|
|
253
|
-
|
|
357
|
+
Licence MIT.
|
|
@@ -12,7 +12,8 @@ export interface Demo {
|
|
|
12
12
|
/** Wrap preview in a phone frame (for full-width mobile components) */
|
|
13
13
|
phoneFrame?: boolean;
|
|
14
14
|
}
|
|
15
|
-
|
|
15
|
+
/** 'updated': an existing component changed in a recent release */
|
|
16
|
+
export type ComponentStatus = 'stable' | 'beta' | 'new' | 'updated' | 'deprecated';
|
|
16
17
|
export interface ComponentPageConfig {
|
|
17
18
|
title: string;
|
|
18
19
|
description: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"createComponentPage.d.ts","sourceRoot":"","sources":["../../src/pages/createComponentPage.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAGvD,YAAY,EAAE,OAAO,EAAE,CAAA;AAEvB,MAAM,WAAW,IAAI;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"createComponentPage.d.ts","sourceRoot":"","sources":["../../src/pages/createComponentPage.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAGvD,YAAY,EAAE,OAAO,EAAE,CAAA;AAEvB,MAAM,WAAW,IAAI;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,CAAA;AAElF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,gHAAgH;IAChH,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAA;IACzB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AA6JD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,qCAiE9D"}
|
|
@@ -20,6 +20,7 @@ const STATUS_CONFIG = {
|
|
|
20
20
|
stable: { label: 'Stable', color: '#16a34a', bg: '#f0fdf4', border: '#bbf7d0' },
|
|
21
21
|
beta: { label: 'Beta', color: '#d97706', bg: '#fffbeb', border: '#fde68a' },
|
|
22
22
|
new: { label: 'Nouveau', color: '#2563eb', bg: '#eff6ff', border: '#bfdbfe' },
|
|
23
|
+
updated: { label: 'Mis à jour', color: '#7c3aed', bg: '#f5f3ff', border: '#ddd6fe' },
|
|
23
24
|
deprecated: { label: 'Déprécié', color: '#dc2626', bg: '#fef2f2', border: '#fecaca' },
|
|
24
25
|
};
|
|
25
26
|
function StatusBadge({ status }) {
|