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

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 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,253 @@
-# 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 documentation 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 ;
+- `createComponentPage` : titre, statut, lien Figma, ligne d'import, démos 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` ;
+- les pages d'écrans complets (flux de connexion, back-office…) dans un téléphone ou une fenêtre de navigateur : `createScreenPage`, `DeviceFrame` ;
+- 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 de pages ;
+- la navigation : titre d'onglet par page, retour en haut au changement de page, liens directs vers une ancre (`/components/button#props`), page 404 ;
+- le mode sombre : il suit la préférence système et mémorise le choix du visiteur.
+
+## Utilisation dans une lib
+
+```bash
+npm install -D @situaction/traquiste-docs-kit
+```
+
+`docs/docs.config.tsx` :
+
+```tsx
+import { defineDocsConfig } from '@situaction/traquiste-docs-kit'
+import { ThemeProvider } from '@situaction/traquiste-mobile'
+import ButtonPage from './src/pages/components/button'
+import pkg from '../package.json'
+import componentProps from 'virtual:traquiste-docs/props'
+
+export default defineDocsConfig({
+  brand: { name: 'traquiste-mobile', subtitle: 'by Situaction', version: pkg.version },
+  links: [
+    { label: 'Doc web', href: 'https://…' },
+    { label: 'Figma', href: 'https://www.figma.com/…' },
+  ],
+  packageName: '@situaction/traquiste-mobile',
+  componentProps,
+  // Enveloppe chaque démo live
+  wrapper: ({ mode, children }) => <ThemeProvider colorScheme={mode}>{children}</ThemeProvider>,
+  pages: [
+    { group: 'Composants', label: 'Button', path: '/components/button', component: ButtonPage },
+  ],
+})
+```
+
+`docs/src/main.tsx` :
+
+```tsx
+import { createDocsApp } from '@situaction/traquiste-docs-kit'
+import config from '../docs.config'
+
+createDocsApp(config, document.getElementById('root')!)
+```
+
+Une page composant :
+
+```ts
+import { createComponentPage } from '@situaction/traquiste-docs-kit'
+import { Button } from '@situaction/traquiste-mobile'
+
+export default createComponentPage({
+  title: 'Button',
+  description: "Bouton d'action.",
+  scope: { Button },
+  demos: [{ section: 'Variantes', title: 'Primary', code: `<Button label="Valider" />` }],
+  // Lu dans l'interface TypeScript du composant et ses JSDoc (plugin docgen)
+  props: 'auto',
+})
+```
+
+### 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 `LiveEditor` insérées dans un guide gardent leur propre rendu.
+- `CodeBlock` : code statique avec un bouton copier, sans coloration syntaxique. L'indentation commune est retirée, ce qui permet d'é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 de la page. C'est le `Link` de react-router, réexporté pour utiliser le même routeur que la doc.
+
+Le playground contient des exemples : `playground/pages/guides/` (Prise en main, Theming avec une démo live) et `playground/pages/Examples.tsx` (page libre avec plusieurs démos).
+
+### É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, comme sur un vrai appareil.
+- 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 devient un lien vers elle.
+- `DeviceFrame` est exporté pour les pages libres : `<DeviceFrame device="browser" url="app.fr" height={600}>…</DeviceFrame>`. C'est aussi le cadre des démos `phoneFrame: true`.
+
+Exemples dans le playground : `playground/pages/screens/Login.tsx` (téléphone) et `Backoffice.tsx` (navigateur).
+
+### Props générées (plugin `docgen`)
+
+`docs/vite.config.ts` :
+
+```ts
+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' }),
+  ],
+})
+```
+
+Pour typer le module généré, dans le `tsconfig` de la doc : `"types": ["@situaction/traquiste-docs-kit/client"]`.
+
+- `props: 'auto'` lit les props du composant qui porte le nom de la page (`title`). Si le nom diffère, ajouter `propsOf: 'NomDuComposant'`.
+- Les écrire à la main reste possible : `props: [{ name, type, required, default?, description }]`.
+- 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.
+- Les stories et les tests sont ignorés ; les exports qui ne sont pas des composants (`MARKER_HEIGHT`, `getBearingSector`) aussi.
+- 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.
+
+Le CSS de la doc résiste aux styles globaux qu'une lib peut injecter (`:root, body { width: 100vw }`, règles `h1`–`h6`). Le playground en charge un exemple (`playground/lib-globals.css`).
+
+Le `vite.config.ts` reste propre à chaque lib : alias react-native-web et stubs côté mobile, `sass` côté web. Le chargement des polices se fait dans le `index.html` de la lib. La police de la doc peut être changée avec la variable CSS `--docs-font-family`.
+
+### Options 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`, tous deux facultatifs à l'affichage. `name` reste obligatoire dans la config : il sert 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 : en général celle du `package.json` de la lib (import JSON avec `resolveJsonModule`) |
+| `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 composants |
+| `wrapper` | non | Enveloppe chaque démo live, en général le `ThemeProvider` de la lib. Reçoit `mode: 'light' \| 'dark'` |
+| `appWrapper` | non | Enveloppe tout le site, pour les pages qui utilisent le thème de la lib hors démos |
+| `componentProps` | non | Props générées : `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
+- `createDocsApp(config, container)` et `DocsApp`
+- `defineDocsConfig`, `useDocsConfig` (types `DocsConfig`, `DocsPage`, `DocsLink`, `DocsWrapper`)
+- `createComponentPage` (types `ComponentPageConfig`, `Demo`, `PropDef`, `ComponentProps`, `ComponentStatus`)
+- `@situaction/traquiste-docs-kit/vite` : `docgen(options)` (plugin Vite) et `findComponentFiles`
+- `LiveEditor`, pour des pages libres comme une page Exemples
+- `DocPage`, `DocSection`, `CodeBlock`, `Callout`, `Link` pour les pages de guide
+- `createScreenPage` (types `ScreenPageConfig`, `ScreenConfig`) et `DeviceFrame` (types `DeviceFrameProps`, `DeviceType`) pour les écrans complets
+- `useColorMode` → `{ mode, setMode, toggle }`
+
+## Compatibilité
+- `react` / `react-dom` : `^18 || ^19`, en `peerDependencies`. La lib web est en 18, la doc mobile en 19.
+- `typescript` (≥ 5) et `vite` (6 à 8) : `peerDependencies` facultatives, utilisées seulement par le plugin `docgen` — ce sont celles de la doc qui l'utilise.
+- 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.
+- Les consommateurs doivent utiliser Vite : le kit est publié en ESM et importe son CSS.
+
+## Développer le kit
+
+### Arborescence
+
+```
+src/                      code publié (dist/)
+  index.ts                API publique : tout ce qui est importable passe par ici
+  app/                    montage du site : createDocsApp, config (DocsConfig), mode clair / sombre
+  pages/                  modèles de pages : createComponentPage, createScreenPage, DocPage
+  components/             briques des pages : LiveEditor, PropsTable, DeviceFrame, CodeBlock, Callout
+    layout/               cadre du site : Layout, Sidebar, recherche, table des matières, 404
+  hooks/                  hooks partagés (useCopy)
+  styles/                 docs.css (variables --docs-*) et styles des pages
+  vite/                   plugin docgen (code Node, non chargé dans le navigateur)
+tests/                    tests vitest, même arborescence que src/
+  helpers/                config et rendu de test (renderDocs)
+  fixtures/               composants d'exemple pour le plugin docgen
+playground/               mini doc pour développer le kit (non publiée)
+  native/                 composants React Native de démo
+  pages/                  pages d'exemple : composants, guides, écrans
+```
+
+```bash
+npm install
+npm run dev          # playground sur http://localhost:5173 et http://<ip-de-la-machine>:5173
+npm run typecheck
+npm run lint
+npm test             # vitest : monte le site avec une config de test (tests/helpers/renderDocs.tsx)
+npm run build        # dist/ (JS + .d.ts + CSS)
+npm run preview      # playground buildé (après npm run build:playground), aussi accessible par l'IP
+```
+
+Le playground a aussi des **composants React Native**, rendus par `react-native-web` comme dans la doc mobile (alias `react-native` → `react-native-web` dans `vite.config.ts`) :
+- `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 ;
+- page **Chip** : démos RN (dont une avec état et une dans un téléphone), props lues par `docgen` depuis les types RN ;
+- page **Réglages (React Native)** : écrans complets en `View` / `Text` / `ScrollView`, dont une liste qui défile dans le téléphone.
+
+`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`).
+
+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`).
+
+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é.
+
+Pour tester le kit dans la doc d'une lib sans publier, deux possibilités dans le `vite.config.ts` de la lib :
+- un alias `'@situaction/traquiste-docs-kit'` → `'../../traq-ui-ste-docs-kit/src/index.ts'` ;
+- ou `npm link`.
+
+## Publication
+semantic-release, déclenché manuellement dans Bitbucket Pipelines :
+- `master` → version `latest` ;
+- `develop` → prerelease `next`.
+
+Chaque version met à jour `CHANGELOG.md` (publié avec le package) : c'est là que les libs voient ce qui change, en particulier les changements incompatibles.
+
+La CI lance les tests en React 19 puis en React 18.
+
+Variables du repo : `NPM_TOKEN` (publication) et `BITBUCKET_TOKEN` (push du commit de release).

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 }) }) }));
+}

package/dist/components/Callout.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+export type CalloutType = 'info' | 'tip' | 'warning' | 'danger';
+export interface CalloutProps {
+    /** Tone of the note (default 'info') */
+    type?: CalloutType;
+    /** Heading — defaults to the type label (Info, Conseil, Attention, Danger) */
+    title?: string;
+    children: ReactNode;
+}
+export declare function Callout({ type, title, children }: CalloutProps): import("react").JSX.Element;
+//# sourceMappingURL=Callout.d.ts.map

package/dist/components/Callout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Callout.d.ts","sourceRoot":"","sources":["../../src/components/Callout.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE/D,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAA;CACpB;AASD,wBAAgB,OAAO,CAAC,EAAE,IAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,YAAY,+BAgCvE"}

package/dist/components/Callout.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Highlighted note in a guide page: info, tip, warning or danger */
+import { Info, Lightbulb, Warning, WarningOctagon } from '@phosphor-icons/react';
+const TYPES = {
+    info: { label: 'Info', Icon: Info },
+    tip: { label: 'Conseil', Icon: Lightbulb },
+    warning: { label: 'Attention', Icon: Warning },
+    danger: { label: 'Danger', Icon: WarningOctagon },
+};
+export function Callout({ type = 'info', title, children }) {
+    const { label, Icon } = TYPES[type];
+    // Colors come from --docs-callout-<type>-* so they follow the light / dark theme
+    const color = (part) => `var(--docs-callout-${type}-${part})`;
+    const heading = title ?? label;
+    return (_jsxs("div", { role: "note", "aria-label": heading, className: "docs-callout", style: {
+            display: 'flex',
+            gap: 12,
+            padding: '12px 16px',
+            margin: '0 0 20px',
+            backgroundColor: color('bg'),
+            border: `1px solid ${color('border')}`,
+            borderLeft: `4px solid ${color('accent')}`,
+            borderRadius: 8,
+            fontSize: 14,
+            lineHeight: 1.6,
+            color: 'var(--docs-text-primary)',
+        }, children: [_jsx(Icon, { size: 18, weight: "fill", color: color('accent'), style: { flexShrink: 0, marginTop: 2 }, "aria-hidden": true }), _jsxs("div", { style: { minWidth: 0 }, children: [_jsx("strong", { style: { display: 'block', fontWeight: 600, marginBottom: 2 }, children: heading }), _jsx("div", { className: "docs-callout-body", children: children })] })] }));
+}

package/dist/components/CodeBlock.d.ts

@@ -0,0 +1,12 @@
+export interface CodeBlockProps {
+    /** Code to show — indentation common to all lines is removed */
+    children: string;
+    /** Language label shown in the header, e.g. 'bash', 'tsx' */
+    language?: string;
+    /** Header label, e.g. a file name — wins over `language` */
+    title?: string;
+}
+/** Removes surrounding blank lines and the indentation shared by all lines (template literals in JSX) */
+export declare function dedent(code: string): string;
+export declare function CodeBlock({ children, language, title }: CodeBlockProps): import("react").JSX.Element;
+//# sourceMappingURL=CodeBlock.d.ts.map

package/dist/components/CodeBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeBlock.d.ts","sourceRoot":"","sources":["../../src/components/CodeBlock.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AA+CD,yGAAyG;AACzG,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK3C;AAED,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,cAAc,+BAkBtE"}