@etic-insa/ui 0.5.0 → 0.7.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.
Files changed (100) hide show
  1. package/README.md +323 -62
  2. package/dist/charts/index.d.ts +1 -0
  3. package/dist/charts/index.js +1 -0
  4. package/dist/components/etic/app-shell.d.ts +10 -0
  5. package/dist/components/etic/app-shell.js +144 -117
  6. package/dist/components/etic/app-shell.js.map +1 -1
  7. package/dist/components/etic/code-block.d.ts +15 -0
  8. package/dist/components/etic/code-block.js +21 -0
  9. package/dist/components/etic/code-block.js.map +1 -0
  10. package/dist/components/etic/data-table-toolbar.d.ts +12 -1
  11. package/dist/components/etic/data-table-toolbar.js +50 -39
  12. package/dist/components/etic/data-table-toolbar.js.map +1 -1
  13. package/dist/components/etic/data-table-view-options.d.ts +2 -1
  14. package/dist/components/etic/data-table-view-options.js +1 -1
  15. package/dist/components/etic/data-table-view-options.js.map +1 -1
  16. package/dist/components/etic/detail-meta.d.ts +28 -0
  17. package/dist/components/etic/detail-meta.js +51 -0
  18. package/dist/components/etic/detail-meta.js.map +1 -0
  19. package/dist/components/etic/detail-sheet.d.ts +36 -0
  20. package/dist/components/etic/detail-sheet.js +37 -0
  21. package/dist/components/etic/detail-sheet.js.map +1 -0
  22. package/dist/components/etic/empty-state.d.ts +15 -0
  23. package/dist/components/etic/empty-state.js +24 -12
  24. package/dist/components/etic/empty-state.js.map +1 -1
  25. package/dist/components/etic/error-banner.js +8 -5
  26. package/dist/components/etic/error-banner.js.map +1 -1
  27. package/dist/components/etic/external-link.d.ts +40 -0
  28. package/dist/components/etic/external-link.js +47 -0
  29. package/dist/components/etic/external-link.js.map +1 -0
  30. package/dist/components/etic/file-upload.d.ts +19 -0
  31. package/dist/components/etic/file-upload.js +24 -1
  32. package/dist/components/etic/file-upload.js.map +1 -1
  33. package/dist/components/etic/form-field.d.ts +10 -1
  34. package/dist/components/etic/form-field.js +32 -28
  35. package/dist/components/etic/form-field.js.map +1 -1
  36. package/dist/components/etic/nav-tabs.d.ts +27 -0
  37. package/dist/components/etic/nav-tabs.js +22 -0
  38. package/dist/components/etic/nav-tabs.js.map +1 -0
  39. package/dist/components/etic/phone-input.d.ts +4 -3
  40. package/dist/components/etic/phone-input.js +51 -37
  41. package/dist/components/etic/phone-input.js.map +1 -1
  42. package/dist/components/etic/progress-ring.d.ts +23 -0
  43. package/dist/components/etic/progress-ring.js +46 -0
  44. package/dist/components/etic/progress-ring.js.map +1 -0
  45. package/dist/components/etic/reset-button.d.ts +37 -0
  46. package/dist/components/etic/reset-button.js +41 -0
  47. package/dist/components/etic/reset-button.js.map +1 -0
  48. package/dist/components/etic/save-bar.d.ts +20 -4
  49. package/dist/components/etic/save-bar.js +39 -24
  50. package/dist/components/etic/save-bar.js.map +1 -1
  51. package/dist/components/etic/select-field.d.ts +38 -0
  52. package/dist/components/etic/select-field.js +42 -0
  53. package/dist/components/etic/select-field.js.map +1 -0
  54. package/dist/components/etic/sub-section.d.ts +15 -0
  55. package/dist/components/etic/sub-section.js +23 -0
  56. package/dist/components/etic/sub-section.js.map +1 -0
  57. package/dist/components/etic/use-detail-sheet.d.ts +58 -0
  58. package/dist/components/etic/use-detail-sheet.js +35 -0
  59. package/dist/components/etic/use-detail-sheet.js.map +1 -0
  60. package/dist/components/etic/use-server-pagination.d.ts +55 -0
  61. package/dist/components/etic/use-server-pagination.js +31 -0
  62. package/dist/components/etic/use-server-pagination.js.map +1 -0
  63. package/dist/components/etic/use-server-sorting.d.ts +29 -0
  64. package/dist/components/etic/use-server-sorting.js +19 -0
  65. package/dist/components/etic/use-server-sorting.js.map +1 -0
  66. package/dist/components/etic/verdict-panel.d.ts +25 -0
  67. package/dist/components/etic/verdict-panel.js +42 -0
  68. package/dist/components/etic/verdict-panel.js.map +1 -0
  69. package/dist/components/ui/chart.d.ts +44 -0
  70. package/dist/components/ui/chart.js +131 -0
  71. package/dist/components/ui/chart.js.map +1 -0
  72. package/dist/components/ui/sheet.d.ts +20 -2
  73. package/dist/components/ui/sheet.js +21 -8
  74. package/dist/components/ui/sheet.js.map +1 -1
  75. package/dist/hooks/use-column-prefs.d.ts +25 -7
  76. package/dist/hooks/use-column-prefs.js +44 -35
  77. package/dist/hooks/use-column-prefs.js.map +1 -1
  78. package/dist/hooks/use-debounced-search.d.ts +29 -0
  79. package/dist/hooks/use-debounced-search.js +29 -0
  80. package/dist/hooks/use-debounced-search.js.map +1 -0
  81. package/dist/hooks/use-fresh-dialog.d.ts +33 -0
  82. package/dist/hooks/use-fresh-dialog.js +17 -0
  83. package/dist/hooks/use-fresh-dialog.js.map +1 -0
  84. package/dist/hooks/use-load-on-open.d.ts +23 -0
  85. package/dist/hooks/use-load-on-open.js +21 -0
  86. package/dist/hooks/use-load-on-open.js.map +1 -0
  87. package/dist/hooks/use-save-by-key.d.ts +45 -0
  88. package/dist/hooks/use-save-by-key.js +49 -0
  89. package/dist/hooks/use-save-by-key.js.map +1 -0
  90. package/dist/index.d.ts +21 -4
  91. package/dist/index.js +117 -100
  92. package/dist/lib/format.d.ts +31 -0
  93. package/dist/lib/format.js +53 -18
  94. package/dist/lib/format.js.map +1 -1
  95. package/dist/lib/ton.d.ts +7 -0
  96. package/dist/lib/ton.js +15 -0
  97. package/dist/lib/ton.js.map +1 -1
  98. package/package.json +10 -1
  99. package/vite-plugin.d.ts +3 -3
  100. package/vite-plugin.js +8 -2
package/README.md CHANGED
@@ -12,7 +12,8 @@ npm i @etic-insa/ui
12
12
 
13
13
  Prérequis (dépendances pairs) : React 19.2 ou plus récent (`useEffectEvent`), Tailwind CSS 4
14
14
  (`tailwindcss` et `@tailwindcss/vite`) et `lucide-react` (les icônes passées aux composants,
15
- `icone={UsersIcon}`, viennent de l'application).
15
+ `icone={UsersIcon}`, viennent de l'application). `recharts` 3.8 ou plus récent seulement pour les
16
+ graphiques (`@etic-insa/ui/charts`, voir [Graphiques](#graphiques)).
16
17
  `QueryBoundary` accepte tel quel le résultat de `useQuery` (TanStack Query), sans que la
17
18
  bibliothèque dépende de TanStack Query : il ne lit que la forme de la requête.
18
19
 
@@ -238,38 +239,65 @@ téléphone, 24 puis 32 px au-delà), espacement vertical régulier entre les bl
238
239
  et `largeur` maximale centrée (`md`, `lg`, `xl`, ou `full` par défaut). Les pages ne posent
239
240
  pas leurs propres marges.
240
241
 
242
+ Une entrée de la navigation porte une pastille avec `badge` (un compteur : éléments à
243
+ traiter ; rien pour `0`, `""` ou sans valeur) : à droite du libellé, lue après lui par les
244
+ lecteurs d'écran (`libelleBadge`, « 3 à traiter » ; le badge seul par défaut) ; barre
245
+ repliée, un point sur l'icône et le compte dans l'infobulle.
246
+
247
+ `NavTabs` est une barre d'onglets dont chaque onglet est une page (sous-pages de paramètres) :
248
+ `libelle` (nom de la barre), `liens` (`libelle`, `href`, `actif`), `lien` (celui du
249
+ `LienProvider` par défaut). Des liens et non des onglets ARIA (`Tabs`) : un lien mène à
250
+ l'onglet voulu, une garde de saisie retient la navigation. L'actif est souligné et annoncé
251
+ (`aria-current`) ; trop large, la barre défile de côté, sans jamais de barre de défilement
252
+ verticale (le trait de base est une ombre intérieure, rien ne déborde).
253
+
254
+ ```tsx
255
+ <NavTabs
256
+ libelle="Paramètres"
257
+ liens={SOUS_PAGES.map(({ chemin, libelle }) => ({
258
+ libelle,
259
+ href: chemin,
260
+ actif: pathname === chemin,
261
+ }))}
262
+ />
263
+ ```
264
+
241
265
  ### Retours et mise en page
242
266
 
243
267
  Compositions des primitives shadcn pour les états d'une page et les actions courantes. Elles ne
244
268
  connaissent ni l'API ni le routeur : l'application fournit ses fonctions (envoi, suppression,
245
269
  chargement d'une image) et, au besoin, son composant de lien (`lien`, comme pour `AppShell`).
246
270
 
247
- | Composant | Rôle |
248
- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
249
- | `ConfirmDialog` | Confirmation (`AlertDialog`) : `titre` qui nomme l'action, `description` qui nomme ce qu'elle touche, `saisie` pour exiger de taper une valeur non affichée (action critique). L'erreur de l'action s'affiche dans le dialogue, qui reste ouvert. |
250
- | `FormDialog` | Formulaire dans un `Dialog` : pied « Annuler / Enregistrer », curseur dans le premier champ à remplir, état d'envoi (champs figés), erreur en tête, `taille` `sm` à `xl`, `verrouEnvoi` pour dire pourquoi l'envoi est impossible. Les contraintes des champs (`required`, `type`, `pattern`…) sont vérifiées sans la bulle du navigateur : la liste des champs à corriger s'affiche en français. |
251
- | `DraftResumeDialog` | Ouverture d'un utilitaire à brouillon (compagnon de `useDraftAutosave`) : « Quitter », `libelleRepartir` (suppression du brouillon, `onRepartir` attendue, bouton occupé, erreur affichée, comme `erreur` venue d'ailleurs) et « Reprendre au même point » si `reprenable`. Sans croix ; Échap quitte, jamais pendant la suppression. |
252
- | `UnsavedChangesDialog`, `useUnsavedChangesWarning` | Garde « modifications non enregistrées », sans routeur : `useUnsavedChangesWarning(modifie)` (booléen, ou fonction lue au moment de quitter) retient la fermeture de l'onglet ; le dialogue confirme une navigation retenue par l'application (`blocage` : `state`, `proceed`, `reset`, la forme du `useBlocker` de react-router). |
253
- | `PageContainer` | Conteneur de page dans `AppShell` : marges, `largeur` maximale, espacement entre les blocs. |
254
- | `PageHeader`, `DetailHeader` | En-tête de page (`<h1>`, description, actions) ; en-tête de fiche avec fil d'Ariane (`chemin`), badges, méta, actions et menu « Plus d'actions » (`actionsSecondaires` : `onChoisir`, `destructif`, `verrou` affiché sous le libellé, l'entrée `DropdownMenuAction` des autres menus), `compact` quand la fiche répète déjà son nom. |
255
- | `SectionCard`, `DetailList`, `DetailItem` | Carte de section titrée (`<h2>`) ; liste `<dl>` de paires libellé / valeur, « — » pour une valeur absente (`null`, `undefined`, `false`, chaîne vide). `disposition` : `grille` (défaut, autant de colonnes de 14rem que la largeur en permet, quatre au plus : une liste courte laisse de l'air à droite sans tenir dans un coin), `pile` (une seule colonne, libellé au-dessus de la valeur : carte étroite, dialogue, valeurs longues), `ligne` (métadonnées secondaires : « libellé : valeur » en petit et en discret, l'une après l'autre). |
256
- | `ErrorBanner` | `Alert` destructive : message, code, détail technique replié (même circulaire), « Réessayer » (`onReessayer`, occupé pendant `enCours`). Lit toute erreur ayant un `message` (et `code`, `details`) ; voir `ErrorBannerProvider` pour masquer le code. |
257
- | `ErrorBoundary` | Filet sous le rendu : message, détail technique, « Réessayer », « Retour à l'accueil » ; `cleReinitialisation` (la route) l'efface. Le focus perdu avec la partie cassée passe sur le message. |
258
- | `EmptyState`, `Loading`, `SkeletonTable`, `SkeletonCard`, `SkeletonPage` | État vide (`Empty` dans un cadre pointillé, `icone` lucide : `icone={InboxIcon}`) ; attente annoncée (`Spinner`) ; squelettes de tableau, de carte et de fiche, un seul statut « Chargement… » chacun. |
259
- | `QueryBoundary` | Chargement, erreur (avec « Réessayer »), vide et données d'une requête ; accepte tel quel le résultat de `useQuery`. L'échec d'une actualisation garde les données, montées, sous le bandeau d'erreur ; pendant une nouvelle tentative, le bandeau reste, son bouton occupé. Sans enveloppe : rendu dans le parent, qui règle l'espacement. |
260
- | `QueryBoundary introuvable` | Fiche : `introuvable` (texte ou nœud, avec un lien de retour) remplace le bandeau quand l'erreur porte un `status` 404 (`ErreurApi` de `@etic-insa/auth`, ou même forme), sans « Réessayer ». Les autres échecs gardent le bandeau : une panne n'est jamais annoncée « introuvable ». |
261
- | `QueryErrorBanner` | Le bandeau d'erreur de `QueryBoundary`, seul (`requete` : `isError`, `error`, `isFetching`, `refetch`), pour une page qui place elle-même ses données ; rien tant que la requête n'a pas échoué. Accepte `titre`, `description`, `className` d'`ErrorBanner`. |
262
- | `Disclosure`, `DisclosureTrigger` | Section repliable à chevron tournant, fermée par défaut : `titre`, `compteur` en pastille, `variante` `lien` (en ligne), `discret` (fantôme estompé) ou `carte` (bloc encadré), `defautOuvert` ou `ouvert` / `onOuvertChange`. `DisclosureTrigger` seul pour un `Collapsible` composé à la main. |
263
- | `CenteredScreen`, `MessageScreen` | Écran hors de la coquille (connexion, page introuvable, vérification de session) : le `<main>` de la page, contenu centré sur toute la hauteur, fond estompé ; écran qui ne dit qu'une chose (page introuvable, lien expiré) : `icone` en pastille, `titre` (`<h1>`), `description`, `actions`. |
264
- | `StatTile`, `StatGrid`, `StatusBadge` | Chiffre clé d'un résumé (`href` : toute la tuile mène au détail, avec un chevron ; `lien` du routeur, ou celui du `LienProvider`) ; rangée de tuiles (colonnes de `largeurMin` au moins, 190 px par défaut, une seule sur téléphone) ; badge d'état à pastille. `ton` (type `StatusTon`) : `neutral`, `info`, `success`, `warning`, `destructive` ; il colore aussi `Progress` (8 px avec `size="lg"`), le segment choisi d'un `SegmentedControl` et un `IconToggle` actif. |
265
- | `RemovableBadge`, `ExplainedBadge` | Badge de 28 px (`size="lg"`, aussi pour les badges sans croix de la même liste) terminé par une croix « Retirer » (`onRetirer`, `libelleRetirer`, `enCours`, `verrou`) ; seul le premier élément du libellé se coupe, un marqueur qui le suit (cadenas) reste entier et centré ; badge dont l'`explication` s'ouvre au toucher, au clic, au survol et au focus (un `Toggletip`) et se lit après lui (`render` : un autre porteur, `<time>` par exemple). |
266
- | `Toggletip` | Explication d'un élément qui n'est pas une action (date, sigle) : bulle sur `Popover`, ouverte au toucher, au clic, au survol et au focus, fermée au toucher ailleurs, à Échap ou quand le focus part ; clic sans effet sur un parent cliquable ; lue après le contenu (`texteLu`) ; dans un badge, la bulle part de son contour. Un bouton qui agit garde son infobulle (`TooltipButton`). |
267
- | `SaveBar` | Pied d'un formulaire de page : « Enregistrer » (soumet le formulaire, ou `onEnregistrer`), occupé mais focalisable pendant `enCours` ; « Annuler » avec `onAnnuler` ; statut annoncé : « Enregistré » (`enregistre`), « Modifications non enregistrées » (`modifie`). `collante` : pied d'un long formulaire, sur une carte opaque alignée sur celles de la page, collé en bas de l'écran tant qu'il y a des modifications (`modifie`) ou un envoi en cours, à sa place sinon ; `masqueeAuRepos` ne l'affiche qu'avec quelque chose à dire. Les deux boutons ne se séparent jamais : au téléphone, le statut passe à la ligne ou se replie. |
268
- | `CopyButton`, `DeleteButton`, `IconToggle` | Copie avec retour « Copié ! », ou « Copie impossible » si le navigateur refuse (`onCopie`, `onEchec`) ; corbeille qui ouvre une confirmation ; bouton à icône qui pose ou retire un marqueur (`Toggle`, `aria-pressed`, `onActifChange`, `enCours` occupé sans perdre le focus ; actif, en couleur de son `ton`, `warning` par défaut). Tous ont une infobulle, et `verrou` pour dire pourquoi l'action est impossible. |
269
- | `TooltipButton` | `Button` avec infobulle et état `verrou` (désactivé mais focalisable, la raison en infobulle) : la règle pour tout bouton à icône seule, que l'infobulle nomme (`aria-label`, sauf nom donné). `destructif` : gris, rouge au survol seulement (corbeille, retrait dans une liste). |
270
- | `ButtonLink` | Lien à l'allure de bouton (`variant`, `size` de `Button`), annoncé comme un lien ; `lien` : le composant de lien du routeur, par défaut celui du `LienProvider` (`<a>` sans lui ; `lien="a"` force un rechargement complet). |
271
- | `AuthAvatar`, `AuthImage`, `useAuthObjectUrl` | Image servie par une adresse authentifiée : l'application passe `charger(src, signal)` (type `AuthImageCharger`) qui renvoie le `Blob` ; l'avatar garde les initiales tant que la photo manque. |
272
- | `useAuthObjectUrlEtat`, `secoursEchec`, `diametre` | État complet d'une image authentifiée (`url`, `enCours`, `echec`, `erreur`) pour dire « indisponible » plutôt que charger sans fin ; `secoursEchec` d'`AuthImage` en cas d'échec ; `diametre` (px) d'`AuthAvatar` et d'`Avatar`, initiales proportionnées (leur graisse suit la racine). |
271
+ | Composant | Rôle |
272
+ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
273
+ | `ConfirmDialog` | Confirmation (`AlertDialog`) : `titre` qui nomme l'action, `description` qui nomme ce qu'elle touche, `saisie` pour exiger de taper une valeur non affichée (action critique). L'erreur de l'action s'affiche dans le dialogue, qui reste ouvert. |
274
+ | `FormDialog` | Formulaire dans un `Dialog` : pied « Annuler / Enregistrer », curseur dans le premier champ à remplir, état d'envoi (champs figés), erreur en tête, `taille` `sm` à `xl`, `verrouEnvoi` pour dire pourquoi l'envoi est impossible. Les contraintes des champs (`required`, `type`, `pattern`…) sont vérifiées sans la bulle du navigateur : la liste des champs à corriger s'affiche en français. |
275
+ | `DraftResumeDialog` | Ouverture d'un utilitaire à brouillon (compagnon de `useDraftAutosave`) : « Quitter », `libelleRepartir` (suppression du brouillon, `onRepartir` attendue, bouton occupé, erreur affichée, comme `erreur` venue d'ailleurs) et « Reprendre au même point » si `reprenable`. Sans croix ; Échap quitte, jamais pendant la suppression. |
276
+ | `UnsavedChangesDialog`, `useUnsavedChangesWarning` | Garde « modifications non enregistrées », sans routeur : `useUnsavedChangesWarning(modifie)` (booléen, ou fonction lue au moment de quitter) retient la fermeture de l'onglet ; le dialogue confirme une navigation retenue par l'application (`blocage` : `state`, `proceed`, `reset`, la forme du `useBlocker` de react-router). |
277
+ | `PageContainer` | Conteneur de page dans `AppShell` : marges, `largeur` maximale, espacement entre les blocs. |
278
+ | `PageHeader`, `DetailHeader` | En-tête de page (`<h1>`, description, actions) ; en-tête de fiche avec fil d'Ariane (`chemin`), badges, méta, actions et menu « Plus d'actions » (`actionsSecondaires` : `onChoisir`, `destructif`, `verrou` affiché sous le libellé, l'entrée `DropdownMenuAction` des autres menus), `compact` quand la fiche répète déjà son nom. |
279
+ | `SectionCard`, `DetailList`, `DetailItem` | Carte de section titrée (`<h2>`) ; liste `<dl>` de paires libellé / valeur, « — » pour une valeur absente (`null`, `undefined`, `false`, chaîne vide). `disposition` : `grille` (défaut, autant de colonnes de 14rem que la largeur en permet, quatre au plus : une liste courte laisse de l'air à droite sans tenir dans un coin), `pile` (une seule colonne, libellé au-dessus de la valeur : carte étroite, dialogue, valeurs longues), `ligne` (métadonnées secondaires : « libellé : valeur » en petit et en discret, l'une après l'autre). |
280
+ | `SubSection`, `CodeBlock` | Bloc titré dans une carte, un tiroir ou un dialogue : `section` nommée par son `titre` (`<h3>`), `aCote` sur la ligne du titre (un badge) ; donnée technique telle quelle (contexte, trace) : un texte tel quel, toute autre `valeur` en JSON indenté, à chasse fixe, dans un bloc qui défile (`className` borne sa hauteur, `retourLigne` coupe les lignes longues). |
281
+ | `ErrorBanner` | `Alert` destructive : message, code, détail technique replié (même circulaire), « Réessayer » (`onReessayer`, occupé pendant `enCours`). Lit toute erreur ayant un `message` (et `code`, `details`) ; voir `ErrorBannerProvider` pour masquer le code. |
282
+ | `ErrorBoundary` | Filet sous le rendu : message, détail technique, « Réessayer », « Retour à l'accueil » ; `cleReinitialisation` (la route) l'efface. Le focus perdu avec la partie cassée passe sur le message. |
283
+ | `EmptyState`, `Loading`, `SkeletonTable`, `SkeletonCard`, `SkeletonPage` | État vide (`Empty` dans un cadre pointillé, `icone` lucide : `icone={InboxIcon}`) ; attente annoncée (`Spinner`) ; squelettes de tableau, de carte et de fiche, un seul statut « Chargement… » chacun. |
284
+ | `QueryBoundary` | Chargement, erreur (avec « Réessayer »), vide et données d'une requête ; accepte tel quel le résultat de `useQuery`. L'échec d'une actualisation garde les données, montées, sous le bandeau d'erreur ; pendant une nouvelle tentative, le bandeau reste, son bouton occupé. Sans enveloppe : rendu dans le parent, qui règle l'espacement. |
285
+ | `QueryBoundary introuvable` | Fiche : `introuvable` (texte ou nœud, avec un lien de retour) remplace le bandeau quand l'erreur porte un `status` 404 (`ErreurApi` de `@etic-insa/auth`, ou même forme), sans « Réessayer ». Les autres échecs gardent le bandeau : une panne n'est jamais annoncée « introuvable ». |
286
+ | `QueryErrorBanner` | Le bandeau d'erreur de `QueryBoundary`, seul (`requete` : `isError`, `error`, `isFetching`, `refetch`), pour une page qui place elle-même ses données ; rien tant que la requête n'a pas échoué. Accepte `titre`, `description`, `className` d'`ErrorBanner`. |
287
+ | `Disclosure`, `DisclosureTrigger` | Section repliable à chevron tournant, fermée par défaut : `titre`, `compteur` en pastille, `variante` `lien` (en ligne), `discret` (fantôme estompé) ou `carte` (bloc encadré), `defautOuvert` ou `ouvert` / `onOuvertChange`. `DisclosureTrigger` seul pour un `Collapsible` composé à la main. |
288
+ | `CenteredScreen`, `MessageScreen` | Écran hors de la coquille (connexion, page introuvable, vérification de session) : le `<main>` de la page, contenu centré sur toute la hauteur, fond estompé ; écran qui ne dit qu'une chose (page introuvable, lien expiré) : `icone` en pastille, `titre` (`<h1>`), `description`, `actions`. |
289
+ | `StatTile`, `StatGrid`, `StatusBadge` | Chiffre clé d'un résumé (`href` : toute la tuile mène au détail, avec un chevron ; `lien` du routeur, ou celui du `LienProvider`) ; rangée de tuiles (colonnes de `largeurMin` au moins, 190 px par défaut, une seule sur téléphone) ; badge d'état à pastille. `ton` (type `StatusTon`) : `neutral`, `info`, `success`, `warning`, `destructive` ; il colore aussi `Progress` (8 px avec `size="lg"`), `ProgressRing`, `VerdictPanel`, le segment choisi d'un `SegmentedControl` et un `IconToggle` actif. |
290
+ | `VerdictPanel` | Verdict d'une page de supervision, lu avant le détail : `ton` (`success` tout va bien, `warning` à surveiller, `destructive` en panne), `titre` (la phrase qui dit l'état), `detail`, `action` (un bouton, qui passe sous le texte quand la place manque). Carte au liseré du ton ; signe du ton en pastille (coche, triangle, croix, `i`, trait), caché aux lecteurs d'écran, `icone` pour un autre. |
291
+ | `ProgressRing` | Jauge circulaire d'une ressource qui se remplit (mémoire, disque, quota), le pendant rond de `Progress`, en SVG sans bibliothèque de graphiques : `valeur` de 0 à 100 (bornée ; `null`, piste vide), `ton` de l'arc (l'accent par défaut), `libelle` lu par les lecteurs d'écran (« Mémoire : 45 % »), `children` au centre (le pourcentage), caché à ces lecteurs. Taille par `className` (`size-28` par défaut). |
292
+ | `RemovableBadge`, `ExplainedBadge` | Badge de 28 px (`size="lg"`, aussi pour les badges sans croix de la même liste) terminé par une croix « Retirer » (`onRetirer`, `libelleRetirer`, `enCours`, `verrou`) ; seul le premier élément du libellé se coupe, un marqueur qui le suit (cadenas) reste entier et centré ; badge dont l'`explication` s'ouvre au toucher, au clic, au survol et au focus (un `Toggletip`) et se lit après lui (`render` : un autre porteur, `<time>` par exemple). |
293
+ | `Toggletip` | Explication d'un élément qui n'est pas une action (date, sigle) : bulle sur `Popover`, ouverte au toucher, au clic, au survol et au focus, fermée au toucher ailleurs, à Échap ou quand le focus part ; clic sans effet sur un parent cliquable ; lue après le contenu (`texteLu`) ; dans un badge, la bulle part de son contour. Un bouton qui agit garde son infobulle (`TooltipButton`). |
294
+ | `SaveBar` | Pied d'un formulaire de page : « Enregistrer » (soumet le formulaire, ou `onEnregistrer`), occupé mais focalisable pendant `enCours` ; « Annuler » avec `onAnnuler` ; statut annoncé : « Enregistré » (`enregistre`), « Modifications non enregistrées » (`modifie`). `collante` : pied d'un long formulaire, sur une carte opaque alignée sur celles de la page, collé en bas de l'écran tant qu'il y a des modifications (`modifie`) ou un envoi en cours, à sa place sinon ; `masqueeAuRepos` ne l'affiche qu'avec quelque chose à dire. Les deux boutons ne se séparent jamais : au téléphone, le statut passe à la ligne ou se replie. Après « Annuler », le focus passe à « Enregistrer ». `retablirDefauts` (`onRetablir`, `masque`) : le ↶ général d'un formulaire à valeurs par défaut, à l'autre bout des boutons ; `masque`, il n'est pas rendu ; offert, il garde la barre visible même au repos. |
295
+ | `ResetButton` | Retour à la valeur par défaut : icône ↶ seule, « Rétablir la valeur par défaut : 6 » en infobulle (`valeur`, telle qu'elle s'affiche), jamais de texte « Rétablir 6 » sous le champ. Dans un `FormField`, passé à son `action` : à droite du contrôle, nommé avec le libellé du champ, focus rendu au contrôle au clic (dans un groupe, à l'option rétablie). Toujours rendu, `masque` (invisible, sa place gardée) quand la valeur est déjà celle par défaut. Hors d'un `FormField` (`FieldSet`) : `libelleId` dit quel libellé citer, `cible` qui reçoit le focus. Sans `valeur` : « Rétablir toutes les valeurs par défaut ». Voir « Valeurs enregistrées et valeurs par défaut » plus bas. |
296
+ | `CopyButton`, `DeleteButton`, `IconToggle` | Copie avec retour « Copié ! », ou « Copie impossible » si le navigateur refuse (`onCopie`, `onEchec`) ; corbeille qui ouvre une confirmation ; bouton à icône qui pose ou retire un marqueur (`Toggle`, `aria-pressed`, `onActifChange`, `enCours` occupé sans perdre le focus ; actif, en couleur de son `ton`, `warning` par défaut). Tous ont une infobulle, et `verrou` pour dire pourquoi l'action est impossible. |
297
+ | `TooltipButton` | `Button` avec infobulle et état `verrou` (désactivé mais focalisable, la raison en infobulle) : la règle pour tout bouton à icône seule, que l'infobulle nomme (`aria-label`, sauf nom donné). `destructif` : gris, rouge au survol seulement (corbeille, retrait dans une liste). |
298
+ | `ButtonLink` | Lien à l'allure de bouton (`variant`, `size` de `Button`), annoncé comme un lien ; `lien` : le composant de lien du routeur, par défaut celui du `LienProvider` (`<a>` sans lui ; `lien="a"` force un rechargement complet). |
299
+ | `AuthAvatar`, `AuthImage`, `useAuthObjectUrl` | Image servie par une adresse authentifiée : l'application passe `charger(src, signal)` (type `AuthImageCharger`) qui renvoie le `Blob` ; l'avatar garde les initiales tant que la photo manque. |
300
+ | `useAuthObjectUrlEtat`, `secoursEchec`, `diametre` | État complet d'une image authentifiée (`url`, `enCours`, `echec`, `erreur`) pour dire « indisponible » plutôt que charger sans fin ; `secoursEchec` d'`AuthImage` en cas d'échec ; `diametre` (px) d'`AuthAvatar` et d'`Avatar`, initiales proportionnées (leur graisse suit la racine). |
273
301
 
274
302
  `ConfirmDialog` et `FormDialog` s'ouvrent par un `declencheur`, ou sont contrôlés (`ouvert`,
275
303
  `onOuvertChange`). `DeleteButton` est son propre déclencheur ; `ouvert` et `onOuvertChange`
@@ -366,6 +394,94 @@ const [conflit, setConflit] = useState(false)
366
394
  </QueryBoundary>
367
395
  ```
368
396
 
397
+ #### Ligne d'informations et liens externes
398
+
399
+ `DetailMeta` est la ligne d'informations sous le titre d'une fiche (`meta` de
400
+ `DetailHeader`) : un élément par enfant (un enfant `null` ou `false` ne laisse rien), séparés
401
+ par des points, passant à la ligne quand la place manque ; une rangée ne commence jamais par un
402
+ point. `DetailMetaLink` y est le lien discret, du ton de la ligne et souligné au survol
403
+ (`href`, `lien` du routeur, `externe` : nouvel onglet et flèche sortante). Hors de cette ligne,
404
+ `ExternalLink` mène à une page hébergée ailleurs : nouvel onglet, flèche sortante et « (nouvel
405
+ onglet) » pour les lecteurs d'écran, dans le texte par défaut, `variant` pour un bouton ;
406
+ `DropdownMenuExternalLink` en est l'entrée de menu.
407
+
408
+ ```tsx
409
+ <DetailHeader
410
+ titre={dossier.nom}
411
+ meta={
412
+ <DetailMeta>
413
+ {dossier.parent ? (
414
+ <DetailMetaLink href={`/dossiers/${dossier.parent.id}`}>Dossier parent</DetailMetaLink>
415
+ ) : null}
416
+ <DetailMetaLink href={dossier.lienPartage} externe>
417
+ Partage
418
+ </DetailMetaLink>
419
+ <span>Créé le {formaterDate(dossier.cree_le)}</span>
420
+ </DetailMeta>
421
+ }
422
+ />
423
+ <ExternalLink href={adresseExport}>Ouvrir l'export</ExternalLink>
424
+ ```
425
+
426
+ #### Tiroir de détail
427
+
428
+ Un tiroir (`Sheet`) prend une `taille` (`sm` à `xl` : 384 à 576 px au-delà de 640 px, tout
429
+ l'écran en dessous) ; son contenu va dans `SheetHeader`, `SheetBody` (seul à défiler) et
430
+ `SheetFooter`. `DetailSheet` est le tiroir de détail d'une liste, à droite (`lg` par défaut) :
431
+ `element` (`undefined` : il se charge, `null` : `introuvable`, avec `titre`, `message`,
432
+ `description`), `ouvert`, `onOuvertChange`, et `children`, une fonction de l'élément. Fermé, il
433
+ garde ce qu'il affichait le temps de son animation. `useDetailSheet` le pilote par un
434
+ identifiant gardé ailleurs, un paramètre d'URL le plus souvent : `id` (`null` : fermé),
435
+ `elements` chargés, `idElement`, `enChargement`, `onIdChange`. Il rend `ouvert`, `element` (le
436
+ dernier ouvert reste affiché quand un tri ou un filtre le sort de la liste ; un identifiant
437
+ absent de la liste arrivée donne `null`, jamais un lien ignoré en silence), et `ouvrir`,
438
+ `fermer`, `onOuvertChange`, stables.
439
+
440
+ ```tsx
441
+ const [params, setParams] = useSearchParams()
442
+ const definirDocument = useCallback(
443
+ (id: string | null) =>
444
+ setParams(
445
+ (p) => {
446
+ if (id === null) p.delete("document")
447
+ else p.set("document", id)
448
+ return p
449
+ },
450
+ { replace: true }
451
+ ),
452
+ [setParams]
453
+ )
454
+ const tiroir = useDetailSheet({
455
+ id: params.get("document"),
456
+ elements: documents.data?.items,
457
+ idElement: (document) => String(document.id),
458
+ enChargement: documents.isPending,
459
+ onIdChange: definirDocument,
460
+ })
461
+
462
+ <DataTable table={table} onActiverLigne={tiroir.ouvrir} … />
463
+ <DetailSheet
464
+ element={tiroir.element}
465
+ ouvert={tiroir.ouvert}
466
+ onOuvertChange={tiroir.onOuvertChange}
467
+ introuvable={{
468
+ titre: "Document introuvable",
469
+ message: "Ce document n'est pas dans la page affichée",
470
+ description: "Retrouvez-le par les filtres de la liste.",
471
+ }}
472
+ >
473
+ {(document) => (
474
+ <>
475
+ <SheetHeader>
476
+ <SheetTitle>{document.nom}</SheetTitle>
477
+ </SheetHeader>
478
+ <SheetBody>…</SheetBody>
479
+ <SheetFooter>…</SheetFooter>
480
+ </>
481
+ )}
482
+ </DetailSheet>
483
+ ```
484
+
369
485
  #### Affichage des erreurs
370
486
 
371
487
  Une application dont les codes d'erreur ne parlent qu'aux développeurs (`not_found`…) les
@@ -450,6 +566,55 @@ texte affiché ; `SearchSelect` soumet `idElement(valeur)`.
450
566
  `useFormField()` renvoie `{ id, libelleId, descriptionId, erreurId, describedBy,
451
567
  obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe seul.
452
568
  `FormSection` regroupe des champs sous un titre (`FieldSet` + `FieldLegend`).
569
+ `action` : un bouton à droite du contrôle, sur sa ligne (un `ResetButton`). À passer
570
+ toujours, masqué au besoin : la ligne ajoutée ou retirée pendant la frappe ferait perdre le
571
+ focus au contrôle. Le contrôle prend la place restante, dans la limite de sa largeur
572
+ maximale.
573
+
574
+ #### Valeurs enregistrées et valeurs par défaut
575
+
576
+ Règle commune aux formulaires de page (profil, paramètres) :
577
+
578
+ - **« Enregistrer » est commun à toute la page**, une seule `SaveBar`, avec à ses côtés
579
+ **« Annuler »**, qui remet chaque champ à sa valeur enregistrée (`onAnnuler`, passé tant
580
+ qu'il y a des modifications).
581
+ - **Un champ qui a une valeur par défaut** porte un `ResetButton` (son `action`), visible dès
582
+ que la valeur s'en écarte, enregistrée ou non (en un fondu bref) ; l'infobulle dit la valeur
583
+ rétablie. La page ajoute le bouton général, `retablirDefauts` de la `SaveBar`, visible
584
+ seulement quand une valeur **enregistrée** s'écarte de son défaut (et que la saisie ne les
585
+ vaut pas déjà toutes) : quand seule la saisie s'en écarte, « Annuler » fait la même chose.
586
+ - **Rétablir ne fait que remplir le formulaire** : rien n'est écrit avant « Enregistrer », qui
587
+ confirme ; « Annuler » revient encore à l'enregistré. Pas d'autre confirmation.
588
+ - **Aucun texte « Rétablir 8 Mo » ni « Défaut : 8 Mo »** sous les champs : la valeur par
589
+ défaut n'est dite que par l'infobulle du bouton.
590
+
591
+ ```tsx
592
+ <FormField
593
+ libelle="Copies conservées"
594
+ action={
595
+ <ResetButton
596
+ valeur={String(defauts.copies)}
597
+ masque={saisie.copies === defauts.copies}
598
+ onRetablir={() => modifier("copies", defauts.copies)}
599
+ />
600
+ }
601
+ >
602
+ <Input className="max-w-24" value={saisie.copies} onChange={…} />
603
+ </FormField>
604
+
605
+ <SaveBar
606
+ collante
607
+ modifie={modifie}
608
+ desactive={!modifie}
609
+ onAnnuler={modifie ? annuler : undefined}
610
+ retablirDefauts={{
611
+ onRetablir: toutRetablir,
612
+ // Rien à rétablir : la saisie vaut tous les défauts, ou ce qui est enregistré les vaut
613
+ // (« Annuler » y revient alors).
614
+ masque: toutAuDefaut || enregistreAuDefaut,
615
+ }}
616
+ />
617
+ ```
453
618
 
454
619
  - `DatePicker` : le Date Picker de shadcn avec saisie au clavier (jj/mm/aaaa, ou les chiffres
455
620
  seuls `05032026` pour le pavé numérique de l'iPhone ; lue en quittant le champ ou sur
@@ -467,7 +632,8 @@ obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe
467
632
  pays ou l'indicatif) et numéro, lus et validés par
468
633
  libphonenumber-js. `onValeurChange(valeur, { valide, pays })` reçoit l'E.164
469
634
  (`+33612345678`) dès que la longueur est possible ; un numéro tapé avec « + » choisit le
470
- pays. En erreur (`aria-invalid` du numéro), le groupe est traité comme un seul champ :
635
+ pays. Le champ n'accepte que des chiffres, des séparateurs (espaces, points, tirets,
636
+ parenthèses) et un « + » en tête : une lettre tapée ou collée est écartée. En erreur (`aria-invalid` du numéro), le groupe est traité comme un seul champ :
471
637
  bordure rouge sur le sélecteur de pays comme sur le numéro, un seul halo autour des deux.
472
638
  `formaterTelephone(numero, { paysParDefaut = "FR" })` écrit un numéro pour l'affichage
473
639
  hors d'un champ (fiche, liste), sans drapeau : national pour le pays par défaut
@@ -496,6 +662,11 @@ obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe
496
662
  annoncée aux lecteurs d'écran. `SelectItem` prend une `description` sous son libellé,
497
663
  reliée à l'option : la raison d'une option figée (`disabled`), qui reste lisible quand le
498
664
  libellé s'estompe ; le libellé passe alors à la ligne plutôt que d'être coupé.
665
+ - `SelectField` : ce `Select` dans son `FormField`, pour une liste courte de choix :
666
+ `libelle`, `valeur` (`null` : rien de choisi, `placeholder`, « Choisir… » par défaut,
667
+ s'affiche ; aucune option « Choisir… » cochable ne le remplace), `options` (`valeur`,
668
+ `libelle`, `desactive`, `description`), `onValeurChange`, et `description`, `erreur`,
669
+ `obligatoire`, `desactive`, `name`, `vide`, `action` du champ.
499
670
  - `FileUploadButton` et `FileDropZone` : bouton, ou zone de glisser-déposer avec bouton, sur
500
671
  react-dropzone. Types (`accepter={{ "text/csv": [".csv"] }}`) et taille (`tailleMax`, en
501
672
  octets) vérifiés, refus en français : à `onRefuser` pour les deux, et affichés dans la zone
@@ -503,7 +674,9 @@ obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe
503
674
  rangée `flex-wrap` ; sans refus, rien d'autre que le bouton n'occupe le flux, ce qui le
504
675
  laisse dans une barre d'outils ou un `ButtonGroup`). Pendant `enCours`, le bouton reste
505
676
  focalisé, indisponible, et l'envoi est annoncé. `FileUploadButton` relaie les props de
506
- `Button` (`id`, `aria-*` : il fonctionne dans un `FormField`).
677
+ `Button` (`id`, `aria-*` : il fonctionne dans un `FormField`). `SelectedFile` prend la
678
+ place de la zone une fois le fichier choisi : nom, taille et « Changer de fichier »
679
+ (`onChanger`, `libelleChanger`, `desactive` pendant l'envoi).
507
680
  - `SegmentedControl` : choix exclusif en boutons joints (`ToggleGroup`), sans désélection ;
508
681
  le segment choisi prend, en plus du fond `bg-muted`, un liseré intérieur, ou la couleur
509
682
  du `ton` de son option (celle de l'état que produit le choix). L'`infobulle`
@@ -556,23 +729,26 @@ La famille `DataTable` suit le [guide Data Table de shadcn](https://ui.shadcn.co
556
729
  sur [TanStack Table v9](https://tanstack.com/table/latest) : les colonnes se déclarent avec
557
730
  l'assistant typé, `useDataTable` crée l'instance, les composants la reçoivent en `table`.
558
731
 
559
- | Composant | Rôle |
560
- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
561
- | `useDataTable` | instance TanStack : tri, filtre et pagination (côté client, ou serveur avec `triManuel`), colonnes, sélection, dépliage |
562
- | `DataTable` | la Table de shadcn ; état vide, lignes fantômes du chargement, bandeau d'erreur (`requete`), clic de ligne, détail déplié |
563
- | `DataTableColumnHeader` | en-tête triable : un clic trie par ordre croissant, le suivant inverse le sens |
564
- | `dataTableSelectionColumn` | colonne de cases ; Maj+clic sélectionne une plage ; raison d'une case verrouillée |
565
- | `dataTableExpandColumn` | colonne du chevron qui déplie une ligne (`aria-expanded`, `aria-controls`) |
566
- | `dataTableActionsColumn` | colonne des commandes d'une ligne : en-tête lu mais invisible, commandes à droite |
567
- | `DataTableCellLink` | titre d'une ligne : vrai lien (`href`, routeur par `lien`) ou bouton |
568
- | `DataTableRowActions` | menu « … » d'une ligne |
569
- | `DropdownMenuAction` | entrée d'un menu d'actions : `libelle`, `icone`, `destructif`, `description` ; `verrou` grise l'entrée et affiche sa raison sous le libellé |
570
- | `DataTableViewOptions` | bouton « Colonnes » : afficher, masquer, réordonner (glisser-déposer, clavier compris) |
571
- | `DataTableToolbar` | recherche, filtres (`DataTableSelectFilter`), compteur (`DataTableCount`), commandes |
572
- | `DataTablePagination` | pagination par décalage (offset/limit, total connu), ou celle du tableau (`table`) |
573
- | `DataTableBulkActions` | barre d'actions groupées, collante en bas, avec la sélection ; actions moins fréquentes dans « … » (`actionsSecondaires`) ; croix et Échap désélectionnent |
574
- | `useColumnPrefs` | colonnes affichées et leur ordre, gardés dans le navigateur par liste et par personne |
575
- | `usePersistedState` | `useState` gardé dans le navigateur (filtre choisi…), sous la portée `PorteeStockageLocal` |
732
+ | Composant | Rôle |
733
+ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
734
+ | `useDataTable` | instance TanStack : tri, filtre et pagination (côté client, ou serveur avec `triManuel`), colonnes, sélection, dépliage |
735
+ | `DataTable` | la Table de shadcn ; état vide, lignes fantômes du chargement, bandeau d'erreur (`requete`), clic de ligne, détail déplié |
736
+ | `DataTableColumnHeader` | en-tête triable : un clic trie par ordre croissant, le suivant inverse le sens |
737
+ | `dataTableSelectionColumn` | colonne de cases ; Maj+clic sélectionne une plage ; raison d'une case verrouillée |
738
+ | `dataTableExpandColumn` | colonne du chevron qui déplie une ligne (`aria-expanded`, `aria-controls`) |
739
+ | `dataTableActionsColumn` | colonne des commandes d'une ligne : en-tête lu mais invisible, commandes à droite |
740
+ | `DataTableCellLink` | titre d'une ligne : vrai lien (`href`, routeur par `lien`) ou bouton |
741
+ | `DataTableRowActions` | menu « … » d'une ligne |
742
+ | `DropdownMenuAction` | entrée d'un menu d'actions : `libelle`, `icone`, `destructif`, `description` ; `verrou` grise l'entrée et affiche sa raison sous le libellé |
743
+ | `DataTableViewOptions` | bouton « Colonnes » : afficher, masquer, réordonner (glisser-déposer, clavier compris) ; absent sans colonne à régler |
744
+ | `DataTableToolbar` | recherche, filtres (`DataTableSelectFilter`), filtres moins courants derrière « Plus de filtres » (`filtresSecondaires`), compteur (`DataTableCount`), commandes |
745
+ | `DataTablePagination` | pagination par décalage (offset/limit, total connu), ou celle du tableau (`table`) |
746
+ | `DataTableBulkActions` | barre d'actions groupées, collante en bas, avec la sélection ; actions moins fréquentes dans « … » (`actionsSecondaires`) ; croix et Échap désélectionnent |
747
+ | `useColumnPrefs` | colonnes affichées et leur ordre, gardés dans le navigateur par liste et par personne |
748
+ | `useServerPagination` | compteur et pagination d'une page reçue du serveur ; un décalage au-delà du total ramène à la dernière page |
749
+ | `useServerSorting` | tri d'une liste triée par le serveur, à étaler dans `useDataTable` |
750
+ | `FilteredEmptyState` | vide d'une liste filtrée, distinct d'un vide réel : « Réinitialiser les filtres » |
751
+ | `usePersistedState` | `useState` gardé dans le navigateur (filtre choisi…), sous la portée `PorteeStockageLocal` |
576
752
 
577
753
  ```tsx
578
754
  import { keepPreviousData, useQuery } from "@tanstack/react-query"
@@ -692,6 +868,51 @@ du `DeleteButton` (`icon-lg` pour la corbeille dans un en-tête de page ; avec `
692
868
  l'en-tête l'agrandit seul). La recherche de `DataTableToolbar` porte `NO_AUTOFILL` ;
693
869
  `recherche.attributs` lui ajoute des attributs.
694
870
 
871
+ #### Liste paginée et triée par le serveur
872
+
873
+ `useServerPagination` prend `decalage`, `limite`, `onDecalageChange`, `onLimiteChange`, la
874
+ `requete` de la page (`data` : `{ total, items }`, `isPlaceholderData`), `unite`, `feminin` et
875
+ `limites`, et rend `compteur` (pour `DataTableToolbar`) et `pagination` (pour
876
+ `DataTablePagination`), tous deux `undefined` avant la première page. Un décalage au-delà du
877
+ total (lien vers une page qui n'existe plus, suppression qui vide la dernière) ramène à la
878
+ dernière page ; une page conservée (`keepPreviousData`) n'y compte pas. `useServerSorting({ tri,
879
+ sens, definirTri })` rend `tri`, `onTriChange` et `triManuel`, à étaler dans `useDataTable` :
880
+ les identifiants des colonnes triables sont les clés de tri du serveur, un tri retiré appelle
881
+ `definirTri(null, …)`. `useDebouncedSearch(valeur, onValeurChange)` tient le champ de recherche
882
+ d'une liste dont la recherche vit ailleurs (l'URL) : la saisie, recopiée sans ses espaces de
883
+ bord après une pause de frappe ; `recopierAuDemontage` pour un champ dans un panneau qui se
884
+ ferme. Une liste filtrée qui ne rend rien passe `FilteredEmptyState` (`onReinitialiser`) en
885
+ `vide`, distinct de son vide réel.
886
+
887
+ `filtresSecondaires` de `DataTableToolbar` range les filtres moins courants, au-delà des trois
888
+ ou quatre de `filtres` : sur ordinateur, dans un panneau ouvert par « Plus de filtres (n) »
889
+ (`filtresSecondairesActifs`) ; sur téléphone, à plat après les autres, repliés avec eux par
890
+ `filtresActifs`. Chacun y porte son libellé visible.
891
+
892
+ ```tsx
893
+ const page = useServerPagination({
894
+ decalage,
895
+ limite,
896
+ onDecalageChange: setDecalage,
897
+ onLimiteChange: setLimite,
898
+ requete: documents,
899
+ unite: { singulier: "document", pluriel: "documents" },
900
+ })
901
+ const table = useDataTable({
902
+ donnees: documents.data?.items ?? AUCUN,
903
+ colonnes,
904
+ idLigne,
905
+ ...useServerSorting({ tri, sens, definirTri }),
906
+ })
907
+
908
+ <DataTableToolbar compteur={page.compteur} filtresSecondaires={<FiltreAuteur />} …>
909
+ <DataTable
910
+ table={table}
911
+ vide={filtresPoses ? <FilteredEmptyState onReinitialiser={reinitialiser} /> : "Aucun document."}
912
+ />
913
+ {page.pagination ? <DataTablePagination {...page.pagination} /> : null}
914
+ ```
915
+
695
916
  L'en-tête du tableau ne se surligne pas au survol (seules les lignes de données le font). Quand
696
917
  le tableau se vide (filtre sans résultat, page suivante en chargement), ses colonnes gardent leur
697
918
  largeur. La colonne de sélection a la largeur de la zone de ses cases (40 px) ; une case
@@ -861,8 +1082,13 @@ contredirait le bandeau. Sans `enChargement`, `isFetching` en tient lieu.
861
1082
  `useColumnPrefs` garde, pour chaque liste et chaque personne, les colonnes affichées et leur
862
1083
  ordre (`localStorage`, format `{ order, visible }`) ; `optionsTableau` s'étale dans
863
1084
  `useDataTable`. Une colonne apparue depuis l'enregistrement s'ajoute à la fin, affichée si elle
864
- l'est par défaut ; une colonne non offerte ici (`disponibles` : droit manquant) garde son état et
865
- sa place ; `fixesEnTete` reste hors préférences. `optionsTableau.colonnesReglables` (une option
1085
+ l'est par défaut ; une colonne non offerte ici (`disponibles` : droit manquant, donnée non
1086
+ servie, colonne qui ne dirait rien dans la vue) est masquée et sort du panneau, mais garde son
1087
+ état et sa place dans les préférences ; `fixesEnTete` reste hors préférences. `affichees`
1088
+ impose des colonnes à l'écran (un filtre posé sur leur donnée montre sa colonne), hors du
1089
+ panneau le temps de l'imposition, sans toucher à leur préférence. `mobile` : sur téléphone,
1090
+ les seules colonnes réglables affichées (celles qui permettent de reconnaître la ligne), le
1091
+ panneau « Colonnes », alors sans objet, disparaissant ; les préférences restent intactes. `optionsTableau.colonnesReglables` (une option
866
1092
  de `useDataTable` et de `DataTableViewOptions`) limite le panneau « Colonnes » aux colonnes des
867
1093
  préférences : les fixes et les autres n'y sont ni masquables ni déplaçables. `reinitialiser()`
868
1094
  revient aux valeurs par
@@ -914,16 +1140,23 @@ focus revient).
914
1140
  Textes chiffrés en français : une valeur absente rend un repli (« — » par défaut, dernier
915
1141
  argument ou option `repli`), une date illisible est rendue telle quelle.
916
1142
 
917
- | Fonction | Rôle |
918
- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
919
- | `compte`, `accorde`, `nombreFr`, `uniteAccordee`, `participe` | « 1 234 lignes », « 0 doublon » (0 et 1 au singulier) ; le mot seul, pluriel irrégulier en option ; nombre au format français ; participe accordé en genre. |
920
- | `formaterOctets` | « 512 o », « 1,5 Ko », « 120 Mo » (base 1 024, une décimale sous 100). |
921
- | `formaterDuree`, `formaterDureeArrondie`, `formaterAnciennete` | « 3 j 4 h » ; « 3 j » ; « il y a 3 j 4 h » ou « à l'instant » (`arrondie`, `ilYA: false` pour « 3 j »). |
922
- | `formaterDate`, `formaterDateHeure`, `formaterHorodatage`, `formaterDateHeureLongue` | « 05 juillet 2026 » (une date sans heure reste ce jour-là dans tous les fuseaux) ; « 05/07/2026 14:30 » ; à la seconde ; « 05 juillet 2026 à 14:30 ». |
923
- | `lireDateIso`, `ecrireDateIso` | Date sans heure de l'API (`AAAA-MM-JJ`) ↔ `Date` du `DatePicker`, en heure locale ; un 31 février est refusé. |
924
- | `normaliser`, `correspondance` | Texte sans accents ni casse ; filtre d'une recherche locale (`correspondance(recherche)(...textes)`, recherche vide : tout passe). |
925
- | `NO_AUTOFILL` | Attributs à étaler sur un champ qui n'est pas un identifiant : les gestionnaires de mots de passe s'en écartent. |
926
- | `useDebouncedValue`, `useDocumentTitle` | Valeur recopiée après un délai sans changement (300 ms par défaut) ; titre de l'onglet le temps que la page est montée. |
1143
+ | Fonction | Rôle |
1144
+ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1145
+ | `compte`, `accorde`, `nombreFr`, `uniteAccordee`, `participe` | « 1 234 lignes », « 0 doublon » (0 et 1 au singulier) ; le mot seul, pluriel irrégulier en option ; nombre au format français ; participe accordé en genre. |
1146
+ | `formaterOctets` | « 512 o », « 1,5 Ko », « 120 Mo » (base 1 024, une décimale sous 100). |
1147
+ | `formaterNombre`, `formaterMontant`, `formaterPourcentage` | « 2,5 », « 1 234 » ; « 1 234,50 € » (`devise` ISO 4217, euros par défaut) ; une fraction en pourcentage, 0,55 → « 55 % » (`decimales` au plus, 0 par défaut). Repli pour une valeur absente ou non finie. |
1148
+ | `capitaliser`, `initiales` | Première lettre en capitale (« en attente » → « En attente ») ; initiales d'un nom pour un avatar (« Camille Martin » → « CM »), sinon la première lettre du secours (l'e-mail), sinon « ? ». |
1149
+ | `formaterDuree`, `formaterDureeArrondie`, `formaterAnciennete` | « 3 j 4 h » ; « 3 j » ; « il y a 3 j 4 h » ou « à l'instant » (`arrondie`, `ilYA: false` pour « 3 j »). |
1150
+ | `formaterDureePrecise`, `formaterHeure` | Durée à la seconde : « moins d'une seconde », « 23 s », « 1 min 05 s », « 1 h 02 min 05 s » ; heure seule à la seconde, « 14:30:12 », d'un instant en millisecondes (`dataUpdatedAt`) ou d'une date ISO. |
1151
+ | `formaterDate`, `formaterDateHeure`, `formaterHorodatage`, `formaterDateHeureLongue` | « 05 juillet 2026 » (une date sans heure reste ce jour-là dans tous les fuseaux) ; « 05/07/2026 14:30 » ; à la seconde ; « 05 juillet 2026 à 14:30 ». |
1152
+ | `lireDateIso`, `ecrireDateIso` | Date sans heure de l'API (`AAAA-MM-JJ`) ↔ `Date` du `DatePicker`, en heure locale ; un 31 février est refusé. |
1153
+ | `normaliser`, `correspondance` | Texte sans accents ni casse ; filtre d'une recherche locale (`correspondance(recherche)(...textes)`, recherche vide : tout passe). |
1154
+ | `NO_AUTOFILL` | Attributs à étaler sur un champ qui n'est pas un identifiant : les gestionnaires de mots de passe s'en écartent. |
1155
+ | `useDebouncedValue`, `useDocumentTitle` | Valeur recopiée après un délai sans changement (300 ms par défaut) ; titre de l'onglet le temps que la page est montée. |
1156
+ | `useDebouncedSearch` | Champ de recherche dont la valeur vit ailleurs (l'URL), recopiée sans ses espaces de bord après une pause de frappe (voir « Liste paginée et triée par le serveur »). |
1157
+ | `useFreshDialog` | Dialogue qui repart d'un formulaire neuf à chaque ouverture : `cle` (sa `key`, nouvelle à chaque `ouvrir()`), `monte` (rien n'est monté avant la première demande), `ouvert`, `onOuvertChange` ; fermé, il reste monté le temps de son animation. `demandesExternes` : un compteur tenu ailleurs, dont chaque incrément l'ouvre. |
1158
+ | `useLoadOnOpen` | Lecture relancée à chaque ouverture d'un dialogue et oubliée à sa fermeture (`mutate` et `reset`, la forme d'une mutation TanStack) ; rend la relecture, pour « Réessayer ». |
1159
+ | `useSaveByKey` | Formulaire de réglages enregistré clé par clé : `enregistrer(envois, envoyer, refusDe)` envoie dans l'ordre ; un refus de saisie reste sous son champ (`refus[cle]`) et les suivantes partent, une panne arrête tout (`panne`) ; `enCours`, `enregistre`, `saisieChangee(cle)`, `oublierTout()`. |
927
1160
 
928
1161
  ```tsx
929
1162
  const [recherche, setRecherche] = useState("")
@@ -938,6 +1171,28 @@ const visibles = postes.filter((p) => correspond(p.nom, p.pole?.nom))
938
1171
  <Input type="search" {...NO_AUTOFILL} />
939
1172
  ```
940
1173
 
1174
+ ### Graphiques
1175
+
1176
+ `@etic-insa/ui/charts` : le [Chart de shadcn](https://ui.shadcn.com/docs/components/base/chart)
1177
+ (`ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`,
1178
+ `ChartStyle`, type `ChartConfig`), tel quel, sur [recharts](https://recharts.github.io). Une
1179
+ entrée à part, parce que `recharts` (~420 Ko) est une dépendance pair facultative : seule une
1180
+ application à graphiques l'installe (`npm i recharts`), et elle peut charger ses graphiques à
1181
+ la demande (`React.lazy`). Les composants de recharts (`AreaChart`, `XAxis`…) s'importent de
1182
+ `recharts` ; la taille vient de `className` (`aspect-video` par défaut). Une jauge circulaire
1183
+ seule n'en a pas besoin : `ProgressRing`, dans l'entrée principale.
1184
+
1185
+ ```tsx
1186
+ const config = { charge: { label: "Charge", color: "var(--primary)" } } satisfies ChartConfig
1187
+
1188
+ <ChartContainer config={config} className="h-52 w-full">
1189
+ <AreaChart data={points}>
1190
+ <ChartTooltip content={<ChartTooltipContent />} />
1191
+ <Area dataKey="charge" stroke="var(--color-charge)" fill="var(--color-charge)" />
1192
+ </AreaChart>
1193
+ </ChartContainer>
1194
+ ```
1195
+
941
1196
  ### Tests des applications
942
1197
 
943
1198
  `@etic-insa/ui/test` réunit des outils pour les tests (vitest) des applications ; une entrée à
@@ -977,9 +1232,10 @@ export default defineConfig({
977
1232
  Les sources sont celles de `ETIC_UI_SOURCES` (chemin de `packages/ui/src`), sinon d'un
978
1233
  `etic-packages` à côté du dépôt de l'application (depuis un worktree aussi), et seulement si ce
979
1234
  checkout a ses `node_modules` (`npm ci` à sa racine) ; `ETIC_UI_SOURCES=npm` force les paquets
980
- installés. Le plugin pose les alias (`@etic-insa/ui`, ses `/styles.css` et `/test`,
981
- `@etic-ui/…` ; `@etic-insa/auth` avec `auth: true`), une seule copie de React (`dedupe` en
982
- ajoute : `["@tanstack/react-query"]` pour que l'`AuthProvider` des sources voie le
1235
+ installés. Le plugin pose les alias (`@etic-insa/ui`, ses `/styles.css`, `/test` et `/charts`,
1236
+ `@etic-ui/…` ; `@etic-insa/auth` avec `auth: true`), une seule copie de React et de recharts
1237
+ (le `ChartContainer` des sources partage ses contextes avec les graphiques de l'application ;
1238
+ `dedupe` en ajoute : `["@tanstack/react-query"]` pour que l'`AuthProvider` des sources voie le
983
1239
  `QueryClient` de l'application), l'accès du serveur au checkout, le `@source` de Tailwind, et
984
1240
  annonce au démarrage ce qu'il sert (branche, commit, modifications). Il n'emploie que Node et
985
1241
  Vite (`vite`, dépendance pair facultative).
@@ -1149,7 +1405,10 @@ overflow-y-auto`), en-tête, croix et pied restant visibles ; sans elle, tout le
1149
1405
  - `sheet.tsx` : `SheetHeader` réserve à droite la place de la croix (`pr-12`) quand
1150
1406
  `SheetContent` l'affiche (`showCloseButton`, vrai par défaut), au lieu de laisser un long
1151
1407
  titre passer dessous ; `SheetContent` le lui dit par un contexte. Un `className` de
1152
- l'application l'emporte.
1408
+ l'application l'emporte ;
1409
+ - `sheet.tsx` : `taille` de `SheetContent` (`sm` à `xl`, tiroir à gauche ou à droite :
1410
+ tout l'écran sous 640 px, puis 384 à 576 px ; sans elle, la largeur de shadcn) et
1411
+ `SheetBody`, la zone qui défile seule entre l'en-tête et le pied, comme `DialogBody`.
1153
1412
 
1154
1413
  Le thème ajoute aussi (`styles.css`, hors composants shadcn) la règle de mouvement réduit.
1155
1414
 
@@ -1176,6 +1435,8 @@ overflow-y-auto`), en-tête, croix et pied restant visibles ; sans elle, tout le
1176
1435
 
1177
1436
  - `src/components/etic/` : composants ETIC qui importent ceux de `ui/` et ajoutent
1178
1437
  comportement, composition ou variantes.
1438
+ - `src/charts/index.ts` : l'entrée `@etic-insa/ui/charts` (`components/ui/chart.tsx`, sans
1439
+ écart, seul à importer recharts : `charts.test.tsx` le vérifie).
1179
1440
  - `src/index.ts` : tout ce qu'une application peut importer. Un composant non exporté ici
1180
1441
  n'existe pas pour les applications.
1181
1442
  - `src/styles.css` : thème commun (clair et sombre). Au build, `scripts/build-css.mjs` y recopie