@situaction/traquiste-docs-kit 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# [1.1.0](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/compare/v1.0.0...v1.1.0) (2026-10-21)
+
+
+### Features
+
+* statut 'updated' (badge Mis à jour) ([f44dbd3](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/f44dbd354b7d34f3125d57e21c57dbbbcd548b7d))
+
+# 1.0.0 (2026-10-20)
+
+
+### Bug Fixes
+
+* empêcher un contenu large de faire déborder la page ([9a2039e](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/9a2039e9deeeddea8e52f26e2bd7f5161c1ebfce))
+* protéger la doc des styles globaux d'une lib ([82c871a](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/82c871a0e29c6670d17c3b85f1e628c2240a8e29))
+
+
+### Features
+
+* extraire le moteur de doc de traquiste-mobile ([f9d2316](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/f9d23168b00cb59574ce2d43240b7637dad3d69e))
+* générer les tableaux de props depuis le code (plugin Vite docgen) ([fe0f21c](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/fe0f21cbd10525a580e89095acfdaf7a0af77dba))
+* logo, version en bas de la sidebar et liens dans la barre du haut ([f9b5337](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/f9b5337d431a1ed76c340602f4fbf6f13dd4eccf))
+* mémoriser le mode sombre et suivre la préférence système ([eda9e09](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/eda9e0998f5e7c85681b1bd8270ea0019cd8b67d))
+* navigation — retour en haut, ancres, page 404 et titre d'onglet ([0572519](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/057251978c08baf4face7156f59dd32b4bb8bf9e)), closes [components/button#props](https://bitbucket.org/components/button/issue/props)
+* pages d'écrans complets — createScreenPage et DeviceFrame ([fdb6eb4](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/fdb6eb4ec5526141d766142d14cede48c1130a15))
+* pages de guide — DocPage, DocSection, CodeBlock, Callout et Link ([6c5174a](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/commits/6c5174abf80c2fe9decfad91e7c34a334f7320f2)), closes [#etats](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/issue/etats)

package/README.md

@@ -1,3 +1,357 @@
-# Temporary Holding Version
+# @situaction/traquiste-docs-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Moteur de site de documentation pour bibliothèques de composants React, partagé par les libs UI Traquiste :
+- [`traq-ui-ste`](https://bitbucket.org/winoc/traq-ui-ste) (web) ;
+- [`traq-ui-ste-mobile`](https://bitbucket.org/winoc/traq-ui-ste-mobile) (React Native, rendu via react-native-web).
+
+Chaque lib garde sa propre doc (pages, config, déploiement). Le kit fournit l'outil :
+- la mise en page : sidebar, barre du haut, recherche ⌘K, bascule light / dark, table des matières ;
+- les **pages composant** : titre, statut, lien Figma, ligne d'import, démos live par section, tableau des props ;
+- les **tableaux de props générés** depuis le code TypeScript des composants (plugin Vite `docgen`) ;
+- les **pages de guide** (Prise en main, Theming…) : `DocPage`, `DocSection`, `CodeBlock`, `Callout`, `Link` ;
+- les **pages d'écrans complets** (flux de connexion, back-office…) dans un téléphone ou une fenêtre de navigateur ;
+- l'**éditeur live** (Monaco + Babel) avec copier / reset, redimensionnement et cadre téléphone ;
+- les routes, la sidebar et la recherche, générées depuis la liste des pages ;
+- la navigation : titre d'onglet par page, retour en haut, liens directs vers une ancre, page 404 ;
+- le mode sombre : il suit la préférence système et mémorise le choix du visiteur.
+
+## Installation
+
+Dans le dossier de la doc de la lib (en général `docs/`, un projet Vite à part) :
+
+```bash
+npm install -D @situaction/traquiste-docs-kit
+npm install react react-dom
+npm install -D vite @vitejs/plugin-react typescript
+```
+
+| Peer dependency | Version | |
+|---|---|---|
+| `react`, `react-dom` | `^18 \|\| ^19` | obligatoires |
+| `vite` | `6`, `7` ou `8` | le kit est publié en ESM et importe son CSS : la doc doit être construite avec Vite |
+| `typescript` | `>= 5` | nécessaire au plugin `docgen` |
+
+`react-router-dom` est fourni par le kit : ne pas l'installer en plus (voir `Link` dans Pages de guide).
+
+## Mise en place
+
+```
+docs/
+  index.html
+  vite.config.ts
+  tsconfig.json
+  src/
+    main.tsx
+    docs.config.tsx
+    pages/
+      components/button.ts
+      guides/GettingStarted.tsx
+```
+
+`index.html` — le site se monte dans `#root`. Le kit ne charge aucune police : c'est à la doc de le faire.
+
+```html
+<!doctype html>
+<html lang="fr">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>traquiste-mobile</title>
+    <link href="https://fonts.googleapis.com/css2?family=Urbanist:wght@400;500;600;700&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+`vite.config.ts` :
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { docgen } from '@situaction/traquiste-docs-kit/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    // Chemins relatifs au dossier docs/
+    docgen({ include: ['../src/components/**/*.tsx'], tsconfig: '../tsconfig.json' }),
+  ],
+})
+```
+
+Les alias propres à une lib restent dans ce fichier : `react-native` → `react-native-web` et stubs côté mobile,
+`sass` côté web…
+
+`tsconfig.json` — pour typer le module généré par `docgen` :
+
+```json
+{ "compilerOptions": { "types": ["vite/client", "@situaction/traquiste-docs-kit/client"] } }
+```
+
+`src/docs.config.tsx` :
+
+```tsx
+import { defineDocsConfig } from '@situaction/traquiste-docs-kit'
+import { ThemeProvider } from '@situaction/traquiste-mobile'
+import componentProps from 'virtual:traquiste-docs/props'
+import pkg from '../../package.json'
+import GettingStarted from './pages/guides/GettingStarted'
+import ButtonPage from './pages/components/button'
+
+export default defineDocsConfig({
+  brand: { name: 'traquiste-mobile', subtitle: 'by Situaction', logo: '/logo-situaction.svg', version: pkg.version },
+  links: [
+    { label: 'npm', href: 'https://www.npmjs.com/package/@situaction/traquiste-mobile' },
+    { label: 'Figma', href: 'https://www.figma.com/…' },
+  ],
+  packageName: '@situaction/traquiste-mobile',
+  componentProps,
+  // Enveloppe chaque démo live : le thème de la lib suit la bascule light / dark de la doc
+  wrapper: ({ mode, children }) => <ThemeProvider colorScheme={mode}>{children}</ThemeProvider>,
+  pages: [
+    { group: 'Général', label: 'Prise en main', path: '/guides/getting-started', component: GettingStarted },
+    { group: 'Composants', label: 'Button', path: '/components/button', component: ButtonPage },
+  ],
+})
+```
+
+`pages` donne à la fois les routes, la sidebar (groupes dans l'ordre de première apparition) et la recherche.
+Ajouter une page = un import + une ligne.
+
+`src/main.tsx` :
+
+```tsx
+import { createDocsApp } from '@situaction/traquiste-docs-kit'
+import config from './docs.config'
+
+createDocsApp(config, document.getElementById('root')!)
+```
+
+Puis `npx vite` pour le serveur de dev, `npx vite build` pour le site statique (à servir avec une redirection de
+toutes les routes vers `index.html` : le site utilise l'historique du navigateur).
+
+## Pages composant
+
+```ts
+import { createComponentPage } from '@situaction/traquiste-docs-kit'
+import { Button } from '@situaction/traquiste-mobile'
+
+export default createComponentPage({
+  title: 'Button',
+  description: "Bouton d'action.",
+  status: 'stable',
+  figma: 'https://www.figma.com/design/…',
+  scope: { Button },
+  demos: [
+    { section: 'Variantes', title: 'Primary', code: `<Button label="Valider" />` },
+    { section: 'Variantes', title: 'Ghost', code: `<Button label="Annuler" variant="ghost" />` },
+    { section: 'États', title: 'Désactivé', code: `<Button label="Valider" disabled />` },
+  ],
+  // Lu dans l'interface TypeScript du composant et ses JSDoc (plugin docgen)
+  props: 'auto',
+})
+```
+
+| Option | Description |
+|---|---|
+| `title` | Titre de la page. **C'est aussi le nom du composant** dans la ligne d'import (`import { Button } from '…'`) et pour `props: 'auto'` |
+| `description` | Paragraphe sous le titre |
+| `status` | Badge : `'stable'`, `'beta'`, `'new'` (Nouveau), `'updated'` (Mis à jour), `'deprecated'` (Déprécié) |
+| `figma` | Lien vers le composant Figma (bouton à droite de la description) |
+| `scope` | Ce que le code des démos peut utiliser : composants, hooks, icônes… `React` est injecté d'office |
+| `demos` | Les démos, dans l'ordre (voir ci-dessous) |
+| `props` | `'auto'` (plugin `docgen`) ou tableau écrit à la main : `[{ name, type, required, default?, description }]` |
+| `propsOf` | Composant à lire avec `props: 'auto'` quand il diffère de `title` |
+
+Chaque démo :
+
+| Champ | Description |
+|---|---|
+| `section` | Titre H2 (ancre et entrée du sommaire), affiché quand il change d'une démo à l'autre |
+| `sectionDescription` | Paragraphe sous ce titre |
+| `title` | En-tête de la carte |
+| `code` | **Une expression JSX**, éditable en direct (voir ci-dessous) |
+| `phoneFrame` | Affiche l'aperçu dans un téléphone, pour les composants pleine largeur |
+
+Le code d'une démo est une expression, sans `import` ni instruction au premier niveau. Plusieurs éléments → un
+fragment `<>…</>`. Pour de l'état, créer un composant à la volée :
+
+```jsx
+React.createElement(() => {
+  const [on, setOn] = React.useState(false)
+  return <Switch value={on} onValueChange={setOn} />
+})
+```
+
+Le JSX est compilé dans le navigateur (preset `react` de Babel) : pas de syntaxe TypeScript dans les démos.
+Une démo qui plante affiche son erreur dans sa carte, sans casser le reste de la page.
+
+## Props générées (plugin `docgen`)
+
+Le plugin lit les composants à la compilation et expose `virtual:traquiste-docs/props`
+(`{ [nomDuComposant]: PropDef[] }`), à passer en `componentProps` à `defineDocsConfig`.
+
+| Option de `docgen()` | Description |
+|---|---|
+| `include` | Globs des fichiers de composants, relatifs à la racine Vite (ex. `['../src/components/**/*.tsx']`) |
+| `exclude` | Globs à ignorer. Les `*.stories.*`, `*.test.*`, `*.spec.*` et `node_modules` le sont toujours |
+| `tsconfig` | tsconfig de la lib, relatif à la racine Vite. Par défaut : options JSX standard |
+
+- 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 `/** … */`.
+- 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.
+- Seuls les composants (nom en PascalCase) sont retenus : les constantes et helpers exportés sont ignorés.
+- En dev, modifier un composant met son tableau à jour (rechargement de la page).
+- Si les props d'un composant sont introuvables, la page l'indique avec les points à vérifier au lieu d'afficher
+  un tableau vide.
+
+## Pages de guide
+
+Pour les pages de texte (Prise en main, Theming, Changelog…), avec le même rendu que les pages composant :
+
+```tsx
+import { Callout, CodeBlock, DocPage, DocSection, Link } from '@situaction/traquiste-docs-kit'
+
+export default function GettingStarted() {
+  return (
+    <DocPage title="Prise en main" description="Installer et configurer la lib.">
+      <DocSection title="Installation">
+        <p>Installe le package :</p>
+        <CodeBlock language="bash">npm install @situaction/traquiste-mobile</CodeBlock>
+        <Callout type="warning">Ajoute aussi les peer dependencies.</Callout>
+      </DocSection>
+      <DocSection title="Theming">
+        <p>Voir aussi la page <Link to="/components/button">Button</Link>.</p>
+      </DocSection>
+    </DocPage>
+  )
+}
+```
+
+- `DocPage` : titre, description et **table des matières générée** à partir des `DocSection` (même imbriquées dans
+  d'autres composants).
+- `DocSection` : titre H2 et ancre (`États` → `#etats`), avec `id` pour la choisir et `description` pour un chapeau.
+- Le texte écrit en JSX simple (`p`, `h3`, `ul` / `ol`, `a`, `strong`, `code`) est mis en forme automatiquement.
+  Les démos insérées dans un guide (`LiveEditor`) gardent leur propre rendu.
+- `CodeBlock` : code statique avec un bouton copier, sans coloration syntaxique. L'indentation commune est
+  retirée : on peut écrire le code dans un template literal indenté. `language` ou `title` (par ex. un nom de
+  fichier) s'affiche dans l'en-tête.
+- `Callout` : encadré `info` (défaut), `tip`, `warning` ou `danger`, avec `title` facultatif. Ses couleurs suivent
+  le thème clair / sombre.
+- `Link` : lien interne sans rechargement. C'est le `Link` de react-router, réexporté pour utiliser le même
+  routeur que la doc.
+- `LiveEditor` : une démo live dans une page libre (Exemples, guide) —
+  `<LiveEditor title="Formulaire" initialCode={code} scope={{ Button, Input }} />`.
+
+## Écrans complets
+
+Pour montrer des écrans entiers construits avec la lib (flux de connexion, liste, formulaire…), un onglet par
+écran :
+
+```tsx
+import { createScreenPage } from '@situaction/traquiste-docs-kit'
+
+export default createScreenPage({
+  title: 'Flux de connexion',
+  description: "Reconstruction du flux d'authentification.",
+  device: 'phone', // 'browser' pour la lib web
+  screens: [
+    {
+      label: 'Email',
+      description: "Saisie de l'identifiant.",
+      components: ['Input', 'Checkbox', 'Button'],
+      notes: 'Toute la ligne « Se rappeler de moi » est pressable.',
+      component: ScreenEmail,
+    },
+    // …
+  ],
+})
+```
+
+- `device` : `'phone'` (390 × 760 par défaut) ou `'browser'` (1024 × 640, avec `url` affichée dans la barre
+  d'adresse, aussi réglable écran par écran). `width` et `height` changent la taille.
+- Chaque écran est rendu dans le `wrapper` de la config : il suit le thème de la lib et le mode clair / sombre.
+  Un écran dont la racine a `flex: 1` remplit toute la hauteur de l'appareil ; au-delà, il défile à l'intérieur.
+- L'écran affiché est dans l'URL (`?screen=mot-de-passe`) : on peut donner un lien direct vers un écran.
+- Onglets, flèches du clavier, boutons Précédent / Suivant, et panneau « Écran 2 / 4 » avec description, notes et
+  composants utilisés. Un composant qui a une page dans la doc (même `label`) devient un lien vers elle.
+- `DeviceFrame` est exporté pour les pages libres :
+  `<DeviceFrame device="browser" url="app.fr" height={600}>…</DeviceFrame>`.
+
+## Thème
+
+- **Thème de la lib** : `wrapper` enveloppe chaque démo et chaque écran, `appWrapper` tout le site (pour les pages
+  qui utilisent le thème de la lib hors démos). Les deux reçoivent `mode: 'light' | 'dark'`.
+- Les couleurs d'une démo doivent venir du thème de la lib (par ex. `useTheme()` côté mobile, à mettre dans
+  `scope`), jamais d'une valeur fixe : sinon elles ne suivent pas la bascule light / dark.
+- `useColorMode()` donne `{ mode, setMode, toggle }` pour les pages qui ont besoin du mode courant.
+- **Police de la doc** : variable CSS `--docs-font-family` (défaut `'Urbanist'`, puis police système), à charger
+  dans l'`index.html`.
+- Le CSS de la doc résiste aux styles globaux qu'une lib peut injecter (`:root, body { width: 100vw }`, règles
+  `h1`–`h6`).
+
+## Référence de `defineDocsConfig`
+
+| Option | Requis | Description |
+|---|---|---|
+| `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 |
+| `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 |
+| `packageName` | oui | Package utilisé dans la ligne `import { X } from '…'` des pages composant |
+| `wrapper` | non | Enveloppe chaque démo live et chaque écran, en général le `ThemeProvider` de la lib. Reçoit `mode` |
+| `appWrapper` | non | Enveloppe tout le site. Reçoit `mode` |
+| `componentProps` | non | `import componentProps from 'virtual:traquiste-docs/props'` (plugin `docgen`), pour `props: 'auto'` |
+| `home` | non | Page affichée sur `/`. Par défaut : redirection vers la première page |
+| `pages` | oui | `{ group, label, path, component }[]`, dans l'ordre de la sidebar |
+
+## API exportée
+
+`@situaction/traquiste-docs-kit` :
+- `createDocsApp(config, container)` et `DocsApp` (le site sans routeur, pour un montage manuel)
+- `defineDocsConfig`, `useDocsConfig` — types `DocsConfig`, `DocsPage`, `DocsLink`, `DocsWrapper`, `ColorMode`, `NavGroup`, `NavItem`
+- `createComponentPage` — types `ComponentPageConfig`, `Demo`, `PropDef`, `ComponentProps`, `ComponentStatus`
+- `DocPage`, `DocSection`, `CodeBlock`, `Callout`, `Link` — types `DocPageProps`, `DocSectionProps`, `CodeBlockProps`, `CalloutProps`, `CalloutType`
+- `createScreenPage` (types `ScreenPageConfig`, `ScreenConfig`) et `DeviceFrame` (types `DeviceFrameProps`, `DeviceType`)
+- `LiveEditor`
+- `useColorMode` → `{ mode, setMode, toggle }`
+
+`@situaction/traquiste-docs-kit/vite` : `docgen(options)` (plugin Vite) et `findComponentFiles`.
+
+`@situaction/traquiste-docs-kit/client` : types du module `virtual:traquiste-docs/props`.
+
+## Compatibilité
+
+- React 18 et 19 (testé sur les deux en CI). La lib web est en 18, la doc mobile en 19.
+- Vite 6 à 8, TypeScript 5 et plus.
+- Composants React DOM et React Native (via `react-native-web`, alias configuré par la doc de la lib).
+- L'éditeur de code des démos (Monaco) est chargé depuis le CDN jsDelivr à son ouverture.
+- Mise en page prévue pour un écran d'ordinateur.
+
+## Versions
+
+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
+incompatible arrive avec une version majeure. Pour monter de version dans une lib :
+
+```bash
+npm install -D @situaction/traquiste-docs-kit@latest
+```
+
+puis vérifier toutes les pages de la doc.
+
+## Contribuer
+
+Le code, le playground et la documentation interne du kit (architecture, tests, publication, problèmes connus)
+sont sur [Bitbucket](https://bitbucket.org/winoc/traq-ui-ste-docs-kit), dans le dossier
+[`docs/`](https://bitbucket.org/winoc/traq-ui-ste-docs-kit/src/master/docs/README.md).
+
+```bash
+npm install
+npm run dev   # playground sur http://localhost:5173
+npm run typecheck && npm run lint && npm test && npm run build
+```
+
+Licence MIT.

package/client.d.ts

@@ -0,0 +1,7 @@
+/** Types for the module generated by the docgen Vite plugin — reference it from the docs' tsconfig or a .d.ts:
+ *  /// <reference types="@situaction/traquiste-docs-kit/client" />
+ */
+declare module 'virtual:traquiste-docs/props' {
+  const componentProps: import('@situaction/traquiste-docs-kit').ComponentProps
+  export default componentProps
+}

package/dist/app/ColorModeContext.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import type { ColorMode } from './config';
+interface ColorModeContextValue {
+    mode: ColorMode;
+    toggle: () => void;
+    setMode: (mode: ColorMode) => void;
+}
+/** Mode shown on first paint: the visitor's last choice, else the system preference */
+export declare function getInitialColorMode(): ColorMode;
+export declare function ColorModeProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useColorMode(): ColorModeContextValue;
+export {};
+//# sourceMappingURL=ColorModeContext.d.ts.map

package/dist/app/ColorModeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColorModeContext.d.ts","sourceRoot":"","sources":["../../src/app/ColorModeContext.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzC,UAAU,qBAAqB;IAC7B,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;CACnC;AAyBD,uFAAuF;AACvF,wBAAgB,mBAAmB,IAAI,SAAS,CAE/C;AAED,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAiCtE;AAED,wBAAgB,YAAY,IAAI,qBAAqB,CAEpD"}

package/dist/app/ColorModeContext.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** Docs-level global color mode state — syncs with data-theme on <html> */
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+const STORAGE_KEY = 'docs-color-mode';
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+const ColorModeContext = createContext({
+    mode: 'light',
+    toggle: () => { },
+    setMode: () => { },
+});
+// Storage can throw (private mode, blocked site data): fall back to the system preference
+function readStoredMode() {
+    try {
+        const value = localStorage.getItem(STORAGE_KEY);
+        return value === 'light' || value === 'dark' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSystemMode() {
+    return typeof window !== 'undefined' && window.matchMedia?.(DARK_QUERY).matches ? 'dark' : 'light';
+}
+/** Mode shown on first paint: the visitor's last choice, else the system preference */
+export function getInitialColorMode() {
+    return readStoredMode() ?? readSystemMode();
+}
+export function ColorModeProvider({ children }) {
+    const [storedMode, setStoredMode] = useState(readStoredMode);
+    const [systemMode, setSystemMode] = useState(readSystemMode);
+    // An explicit choice wins; otherwise follow the OS live
+    const mode = storedMode ?? systemMode;
+    useEffect(() => {
+        const query = window.matchMedia?.(DARK_QUERY);
+        if (!query)
+            return;
+        const onChange = (e) => setSystemMode(e.matches ? 'dark' : 'light');
+        query.addEventListener('change', onChange);
+        return () => query.removeEventListener('change', onChange);
+    }, []);
+    useEffect(() => {
+        document.documentElement.setAttribute('data-theme', mode);
+    }, [mode]);
+    const setMode = useCallback((next) => {
+        setStoredMode(next);
+        try {
+            localStorage.setItem(STORAGE_KEY, next);
+        }
+        catch {
+            // Not persisted — the choice still applies for this visit
+        }
+    }, []);
+    const value = useMemo(() => ({ mode, setMode, toggle: () => setMode(mode === 'light' ? 'dark' : 'light') }), [mode, setMode]);
+    return _jsx(ColorModeContext.Provider, { value: value, children: children });
+}
+export function useColorMode() {
+    return useContext(ColorModeContext);
+}

package/dist/app/config.d.ts

@@ -0,0 +1,69 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ComponentProps } from '../components/PropsTable';
+export type ColorMode = 'light' | 'dark';
+export interface NavItem {
+    label: string;
+    path: string;
+}
+export interface NavGroup {
+    group: string;
+    items: NavItem[];
+}
+/** A docs page: shown in the sidebar under `group`, routed at `path` */
+export interface DocsPage extends NavItem {
+    group: string;
+    component: ComponentType;
+}
+/** External or internal link shown in the top bar */
+export interface DocsLink {
+    label: string;
+    /** Absolute URL (opens in a new tab) or in-site path */
+    href: string;
+}
+/** Wraps content with the documented library's theme for the current color mode */
+export type DocsWrapper = ComponentType<{
+    mode: ColorMode;
+    children: ReactNode;
+}>;
+export interface DocsConfig {
+    /** Sidebar header */
+    brand: {
+        /** Library name, e.g. 'traquiste-mobile' — also used in tab titles and as the logo's alt text */
+        name: string;
+        /** Show the name next to the logo — set false when the logo already contains it (default true) */
+        showName?: boolean;
+        /** Line under the name, e.g. 'by Situaction' */
+        subtitle?: string;
+        /** Image URL shown left of the name, e.g. '/logo-situaction.svg' from the docs' public/ folder */
+        logo?: string;
+        /** Documented version, e.g. the library's package.json version */
+        version?: string;
+    };
+    /** Links in the top bar — the other library's docs, Figma, repository, npm… */
+    links?: DocsLink[];
+    /** Package used in the generated import snippet of each component page */
+    packageName: string;
+    /** Wraps every live demo — typically the library's ThemeProvider */
+    wrapper?: DocsWrapper;
+    /** Wraps the whole site — for pages that use the library's theme outside live demos */
+    appWrapper?: DocsWrapper;
+    /** Generated props tables: `import componentProps from 'virtual:traquiste-docs/props'` (docgen Vite plugin) */
+    componentProps?: ComponentProps;
+    /** Page rendered at `/` — defaults to a redirect to the first page */
+    home?: ComponentType;
+    /** Pages in sidebar order; groups appear in order of first occurrence */
+    pages: DocsPage[];
+}
+/** Resolved config: optional wrappers replaced by a pass-through */
+export type ResolvedDocsConfig = DocsConfig & {
+    wrapper: DocsWrapper;
+    appWrapper: DocsWrapper;
+};
+/** Identity helper — gives type checking and autocompletion in `docs.config.tsx` */
+export declare function defineDocsConfig(config: DocsConfig): DocsConfig;
+export declare function resolveDocsConfig(config: DocsConfig): ResolvedDocsConfig;
+export declare const DocsConfigContext: import("react").Context<ResolvedDocsConfig | null>;
+export declare function useDocsConfig(): ResolvedDocsConfig;
+/** Sidebar / search tree derived from the page list */
+export declare function useNav(): NavGroup[];
+//# sourceMappingURL=config.d.ts.map

package/dist/app/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/app/config.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExC,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,OAAO,EAAE,CAAA;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAS,SAAQ,OAAO;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,aAAa,CAAA;CACzB;AAED,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;CACb;AAED,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,CAAA;AAEjF,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,KAAK,EAAE;QACL,iGAAiG;QACjG,IAAI,EAAE,MAAM,CAAA;QACZ,kGAAkG;QAClG,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,gDAAgD;QAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,kGAAkG;QAClG,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,kEAAkE;QAClE,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,+EAA+E;IAC/E,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;IAClB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,uFAAuF;IACvF,UAAU,CAAC,EAAE,WAAW,CAAA;IACxB,+GAA+G;IAC/G,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,sEAAsE;IACtE,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,yEAAyE;IACzE,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,WAAW,CAAA;CAAE,CAAA;AAI/F,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAE/D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,kBAAkB,CAMxE;AAED,eAAO,MAAM,iBAAiB,oDAAiD,CAAA;AAE/E,wBAAgB,aAAa,IAAI,kBAAkB,CAIlD;AAED,uDAAuD;AACvD,wBAAgB,MAAM,IAAI,QAAQ,EAAE,CAUnC"}

package/dist/app/config.js

@@ -0,0 +1,35 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/** Docs configuration — everything that differs from one library's docs to another */
+import { createContext, useContext, useMemo } from 'react';
+const PassThrough = ({ children }) => _jsx(_Fragment, { children: children });
+/** Identity helper — gives type checking and autocompletion in `docs.config.tsx` */
+export function defineDocsConfig(config) {
+    return config;
+}
+export function resolveDocsConfig(config) {
+    return {
+        ...config,
+        wrapper: config.wrapper ?? PassThrough,
+        appWrapper: config.appWrapper ?? PassThrough,
+    };
+}
+export const DocsConfigContext = createContext(null);
+export function useDocsConfig() {
+    const config = useContext(DocsConfigContext);
+    if (!config)
+        throw new Error('useDocsConfig must be used inside createDocsApp()');
+    return config;
+}
+/** Sidebar / search tree derived from the page list */
+export function useNav() {
+    const { pages } = useDocsConfig();
+    return useMemo(() => {
+        const groups = new Map();
+        for (const { group, label, path } of pages) {
+            if (!groups.has(group))
+                groups.set(group, []);
+            groups.get(group).push({ label, path });
+        }
+        return [...groups].map(([group, items]) => ({ group, items }));
+    }, [pages]);
+}

package/dist/app/createDocsApp.d.ts

@@ -0,0 +1,9 @@
+import type { DocsConfig } from './config';
+import '../styles/docs.css';
+/** Full docs site — use it when you need to mount it yourself (tests, custom router setup) */
+export declare function DocsApp({ config }: {
+    config: DocsConfig;
+}): import("react").JSX.Element;
+/** Mounts the docs site into `container` */
+export declare function createDocsApp(config: DocsConfig, container: HTMLElement): void;
+//# sourceMappingURL=createDocsApp.d.ts.map

package/dist/app/createDocsApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDocsApp.d.ts","sourceRoot":"","sources":["../../src/app/createDocsApp.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,oBAAoB,CAAA;AAsE3B,8FAA8F;AAC9F,wBAAgB,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,+BAczD;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,QAUvE"}

package/dist/app/createDocsApp.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/** Docs app entry: providers, layout and routes generated from the config */
+import { StrictMode, useEffect, useMemo } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom';
+import Layout from '../components/layout/Layout';
+import NotFound from '../components/layout/NotFound';
+import { ColorModeProvider, getInitialColorMode, useColorMode } from './ColorModeContext';
+import { DocsConfigContext, resolveDocsConfig, useDocsConfig } from './config';
+import '../styles/docs.css';
+function AppWrapper({ children }) {
+    const { appWrapper: Wrapper } = useDocsConfig();
+    const { mode } = useColorMode();
+    return _jsx(Wrapper, { mode: mode, children: children });
+}
+/** Sets the browser tab title while the page is shown */
+function Titled({ title, children }) {
+    useEffect(() => {
+        document.title = title;
+    }, [title]);
+    return _jsx(_Fragment, { children: children });
+}
+/** New page → back to the top, or to the anchor of a deep link (/components/button#props) */
+function ScrollRestoration() {
+    const { pathname, hash } = useLocation();
+    useEffect(() => {
+        const target = hash && document.getElementById(decodeURIComponent(hash.slice(1)));
+        // 'instant' bypasses the smooth scroll-behavior set on <html> for in-page anchors:
+        // arriving on a page should jump, not animate
+        if (target)
+            target.scrollIntoView({ behavior: 'instant' });
+        else
+            window.scrollTo({ top: 0, behavior: 'instant' });
+        // Only on page change: in-page anchor clicks are handled natively by the browser
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [pathname]);
+    return null;
+}
+function DocsRoutes() {
+    const { pages, home: Home, brand } = useDocsConfig();
+    return (_jsxs(Routes, { children: [_jsx(Route, { path: "/", element: Home ? (_jsx(Titled, { title: brand.name, children: _jsx(Home, {}) })) : (_jsx(Navigate, { to: pages[0]?.path ?? '/', replace: true })) }), pages.map(({ path, label, component: Page }) => (_jsx(Route, { path: path, element: _jsx(Titled, { title: `${label} — ${brand.name}`, children: _jsx(Page, {}) }) }, path))), _jsx(Route, { path: "*", element: _jsx(Titled, { title: `Page introuvable — ${brand.name}`, children: _jsx(NotFound, {}) }) })] }));
+}
+/** Full docs site — use it when you need to mount it yourself (tests, custom router setup) */
+export function DocsApp({ config }) {
+    const resolved = useMemo(() => resolveDocsConfig(config), [config]);
+    return (_jsx(DocsConfigContext.Provider, { value: resolved, children: _jsx(ColorModeProvider, { children: _jsxs(AppWrapper, { children: [_jsx(ScrollRestoration, {}), _jsx(Layout, { children: _jsx(DocsRoutes, {}) })] }) }) }));
+}
+/** Mounts the docs site into `container` */
+export function createDocsApp(config, container) {
+    // Apply the theme before React renders, so a dark-mode visitor never sees a light flash
+    document.documentElement.setAttribute('data-theme', getInitialColorMode());
+    createRoot(container).render(_jsx(StrictMode, { children: _jsx(BrowserRouter, { children: _jsx(DocsApp, { config: config }) }) }));
+}