@etic-insa/ui 0.6.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 (76) hide show
  1. package/README.md +250 -62
  2. package/dist/components/etic/app-shell.d.ts +10 -0
  3. package/dist/components/etic/app-shell.js +144 -117
  4. package/dist/components/etic/app-shell.js.map +1 -1
  5. package/dist/components/etic/code-block.d.ts +15 -0
  6. package/dist/components/etic/code-block.js +21 -0
  7. package/dist/components/etic/code-block.js.map +1 -0
  8. package/dist/components/etic/data-table-toolbar.d.ts +12 -1
  9. package/dist/components/etic/data-table-toolbar.js +50 -39
  10. package/dist/components/etic/data-table-toolbar.js.map +1 -1
  11. package/dist/components/etic/data-table-view-options.d.ts +2 -1
  12. package/dist/components/etic/data-table-view-options.js +1 -1
  13. package/dist/components/etic/data-table-view-options.js.map +1 -1
  14. package/dist/components/etic/detail-meta.d.ts +28 -0
  15. package/dist/components/etic/detail-meta.js +51 -0
  16. package/dist/components/etic/detail-meta.js.map +1 -0
  17. package/dist/components/etic/detail-sheet.d.ts +36 -0
  18. package/dist/components/etic/detail-sheet.js +37 -0
  19. package/dist/components/etic/detail-sheet.js.map +1 -0
  20. package/dist/components/etic/empty-state.d.ts +15 -0
  21. package/dist/components/etic/empty-state.js +24 -12
  22. package/dist/components/etic/empty-state.js.map +1 -1
  23. package/dist/components/etic/external-link.d.ts +40 -0
  24. package/dist/components/etic/external-link.js +47 -0
  25. package/dist/components/etic/external-link.js.map +1 -0
  26. package/dist/components/etic/file-upload.d.ts +19 -0
  27. package/dist/components/etic/file-upload.js +24 -1
  28. package/dist/components/etic/file-upload.js.map +1 -1
  29. package/dist/components/etic/nav-tabs.d.ts +27 -0
  30. package/dist/components/etic/nav-tabs.js +22 -0
  31. package/dist/components/etic/nav-tabs.js.map +1 -0
  32. package/dist/components/etic/phone-input.d.ts +4 -3
  33. package/dist/components/etic/phone-input.js +51 -37
  34. package/dist/components/etic/phone-input.js.map +1 -1
  35. package/dist/components/etic/save-bar.d.ts +3 -2
  36. package/dist/components/etic/save-bar.js +16 -15
  37. package/dist/components/etic/save-bar.js.map +1 -1
  38. package/dist/components/etic/select-field.d.ts +38 -0
  39. package/dist/components/etic/select-field.js +42 -0
  40. package/dist/components/etic/select-field.js.map +1 -0
  41. package/dist/components/etic/sub-section.d.ts +15 -0
  42. package/dist/components/etic/sub-section.js +23 -0
  43. package/dist/components/etic/sub-section.js.map +1 -0
  44. package/dist/components/etic/use-detail-sheet.d.ts +58 -0
  45. package/dist/components/etic/use-detail-sheet.js +35 -0
  46. package/dist/components/etic/use-detail-sheet.js.map +1 -0
  47. package/dist/components/etic/use-server-pagination.d.ts +55 -0
  48. package/dist/components/etic/use-server-pagination.js +31 -0
  49. package/dist/components/etic/use-server-pagination.js.map +1 -0
  50. package/dist/components/etic/use-server-sorting.d.ts +29 -0
  51. package/dist/components/etic/use-server-sorting.js +19 -0
  52. package/dist/components/etic/use-server-sorting.js.map +1 -0
  53. package/dist/components/ui/sheet.d.ts +20 -2
  54. package/dist/components/ui/sheet.js +21 -8
  55. package/dist/components/ui/sheet.js.map +1 -1
  56. package/dist/hooks/use-column-prefs.d.ts +25 -7
  57. package/dist/hooks/use-column-prefs.js +44 -35
  58. package/dist/hooks/use-column-prefs.js.map +1 -1
  59. package/dist/hooks/use-debounced-search.d.ts +29 -0
  60. package/dist/hooks/use-debounced-search.js +29 -0
  61. package/dist/hooks/use-debounced-search.js.map +1 -0
  62. package/dist/hooks/use-fresh-dialog.d.ts +33 -0
  63. package/dist/hooks/use-fresh-dialog.js +17 -0
  64. package/dist/hooks/use-fresh-dialog.js.map +1 -0
  65. package/dist/hooks/use-load-on-open.d.ts +23 -0
  66. package/dist/hooks/use-load-on-open.js +21 -0
  67. package/dist/hooks/use-load-on-open.js.map +1 -0
  68. package/dist/hooks/use-save-by-key.d.ts +45 -0
  69. package/dist/hooks/use-save-by-key.js +49 -0
  70. package/dist/hooks/use-save-by-key.js.map +1 -0
  71. package/dist/index.d.ts +18 -4
  72. package/dist/index.js +117 -103
  73. package/dist/lib/format.d.ts +31 -0
  74. package/dist/lib/format.js +53 -18
  75. package/dist/lib/format.js.map +1 -1
  76. package/package.json +1 -1
package/README.md CHANGED
@@ -239,41 +239,65 @@ téléphone, 24 puis 32 px au-delà), espacement vertical régulier entre les bl
239
239
  et `largeur` maximale centrée (`md`, `lg`, `xl`, ou `full` par défaut). Les pages ne posent
240
240
  pas leurs propres marges.
241
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
+
242
265
  ### Retours et mise en page
243
266
 
244
267
  Compositions des primitives shadcn pour les états d'une page et les actions courantes. Elles ne
245
268
  connaissent ni l'API ni le routeur : l'application fournit ses fonctions (envoi, suppression,
246
269
  chargement d'une image) et, au besoin, son composant de lien (`lien`, comme pour `AppShell`).
247
270
 
248
- | Composant | Rôle |
249
- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
250
- | `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. |
251
- | `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. |
252
- | `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. |
253
- | `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). |
254
- | `PageContainer` | Conteneur de page dans `AppShell` : marges, `largeur` maximale, espacement entre les blocs. |
255
- | `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. |
256
- | `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). |
257
- | `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. |
258
- | `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. |
259
- | `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. |
260
- | `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. |
261
- | `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 ». |
262
- | `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`. |
263
- | `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. |
264
- | `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`. |
265
- | `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. |
266
- | `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. |
267
- | `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). |
268
- | `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). |
269
- | `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`). |
270
- | `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. |
271
- | `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. |
272
- | `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. |
273
- | `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). |
274
- | `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). |
275
- | `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. |
276
- | `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). |
277
301
 
278
302
  `ConfirmDialog` et `FormDialog` s'ouvrent par un `declencheur`, ou sont contrôlés (`ouvert`,
279
303
  `onOuvertChange`). `DeleteButton` est son propre déclencheur ; `ouvert` et `onOuvertChange`
@@ -370,6 +394,94 @@ const [conflit, setConflit] = useState(false)
370
394
  </QueryBoundary>
371
395
  ```
372
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
+
373
485
  #### Affichage des erreurs
374
486
 
375
487
  Une application dont les codes d'erreur ne parlent qu'aux développeurs (`not_found`…) les
@@ -495,7 +607,12 @@ Règle commune aux formulaires de page (profil, paramètres) :
495
607
  modifie={modifie}
496
608
  desactive={!modifie}
497
609
  onAnnuler={modifie ? annuler : undefined}
498
- retablirDefauts={{ onRetablir: toutRetablir, masque: toutAuDefaut }}
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
+ }}
499
616
  />
500
617
  ```
501
618
 
@@ -515,7 +632,8 @@ Règle commune aux formulaires de page (profil, paramètres) :
515
632
  pays ou l'indicatif) et numéro, lus et validés par
516
633
  libphonenumber-js. `onValeurChange(valeur, { valide, pays })` reçoit l'E.164
517
634
  (`+33612345678`) dès que la longueur est possible ; un numéro tapé avec « + » choisit le
518
- 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 :
519
637
  bordure rouge sur le sélecteur de pays comme sur le numéro, un seul halo autour des deux.
520
638
  `formaterTelephone(numero, { paysParDefaut = "FR" })` écrit un numéro pour l'affichage
521
639
  hors d'un champ (fiche, liste), sans drapeau : national pour le pays par défaut
@@ -544,6 +662,11 @@ Règle commune aux formulaires de page (profil, paramètres) :
544
662
  annoncée aux lecteurs d'écran. `SelectItem` prend une `description` sous son libellé,
545
663
  reliée à l'option : la raison d'une option figée (`disabled`), qui reste lisible quand le
546
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.
547
670
  - `FileUploadButton` et `FileDropZone` : bouton, ou zone de glisser-déposer avec bouton, sur
548
671
  react-dropzone. Types (`accepter={{ "text/csv": [".csv"] }}`) et taille (`tailleMax`, en
549
672
  octets) vérifiés, refus en français : à `onRefuser` pour les deux, et affichés dans la zone
@@ -551,7 +674,9 @@ Règle commune aux formulaires de page (profil, paramètres) :
551
674
  rangée `flex-wrap` ; sans refus, rien d'autre que le bouton n'occupe le flux, ce qui le
552
675
  laisse dans une barre d'outils ou un `ButtonGroup`). Pendant `enCours`, le bouton reste
553
676
  focalisé, indisponible, et l'envoi est annoncé. `FileUploadButton` relaie les props de
554
- `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).
555
680
  - `SegmentedControl` : choix exclusif en boutons joints (`ToggleGroup`), sans désélection ;
556
681
  le segment choisi prend, en plus du fond `bg-muted`, un liseré intérieur, ou la couleur
557
682
  du `ton` de son option (celle de l'état que produit le choix). L'`infobulle`
@@ -604,23 +729,26 @@ La famille `DataTable` suit le [guide Data Table de shadcn](https://ui.shadcn.co
604
729
  sur [TanStack Table v9](https://tanstack.com/table/latest) : les colonnes se déclarent avec
605
730
  l'assistant typé, `useDataTable` crée l'instance, les composants la reçoivent en `table`.
606
731
 
607
- | Composant | Rôle |
608
- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
609
- | `useDataTable` | instance TanStack : tri, filtre et pagination (côté client, ou serveur avec `triManuel`), colonnes, sélection, dépliage |
610
- | `DataTable` | la Table de shadcn ; état vide, lignes fantômes du chargement, bandeau d'erreur (`requete`), clic de ligne, détail déplié |
611
- | `DataTableColumnHeader` | en-tête triable : un clic trie par ordre croissant, le suivant inverse le sens |
612
- | `dataTableSelectionColumn` | colonne de cases ; Maj+clic sélectionne une plage ; raison d'une case verrouillée |
613
- | `dataTableExpandColumn` | colonne du chevron qui déplie une ligne (`aria-expanded`, `aria-controls`) |
614
- | `dataTableActionsColumn` | colonne des commandes d'une ligne : en-tête lu mais invisible, commandes à droite |
615
- | `DataTableCellLink` | titre d'une ligne : vrai lien (`href`, routeur par `lien`) ou bouton |
616
- | `DataTableRowActions` | menu « … » d'une ligne |
617
- | `DropdownMenuAction` | entrée d'un menu d'actions : `libelle`, `icone`, `destructif`, `description` ; `verrou` grise l'entrée et affiche sa raison sous le libellé |
618
- | `DataTableViewOptions` | bouton « Colonnes » : afficher, masquer, réordonner (glisser-déposer, clavier compris) |
619
- | `DataTableToolbar` | recherche, filtres (`DataTableSelectFilter`), compteur (`DataTableCount`), commandes |
620
- | `DataTablePagination` | pagination par décalage (offset/limit, total connu), ou celle du tableau (`table`) |
621
- | `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 |
622
- | `useColumnPrefs` | colonnes affichées et leur ordre, gardés dans le navigateur par liste et par personne |
623
- | `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` |
624
752
 
625
753
  ```tsx
626
754
  import { keepPreviousData, useQuery } from "@tanstack/react-query"
@@ -740,6 +868,51 @@ du `DeleteButton` (`icon-lg` pour la corbeille dans un en-tête de page ; avec `
740
868
  l'en-tête l'agrandit seul). La recherche de `DataTableToolbar` porte `NO_AUTOFILL` ;
741
869
  `recherche.attributs` lui ajoute des attributs.
742
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
+
743
916
  L'en-tête du tableau ne se surligne pas au survol (seules les lignes de données le font). Quand
744
917
  le tableau se vide (filtre sans résultat, page suivante en chargement), ses colonnes gardent leur
745
918
  largeur. La colonne de sélection a la largeur de la zone de ses cases (40 px) ; une case
@@ -909,8 +1082,13 @@ contredirait le bandeau. Sans `enChargement`, `isFetching` en tient lieu.
909
1082
  `useColumnPrefs` garde, pour chaque liste et chaque personne, les colonnes affichées et leur
910
1083
  ordre (`localStorage`, format `{ order, visible }`) ; `optionsTableau` s'étale dans
911
1084
  `useDataTable`. Une colonne apparue depuis l'enregistrement s'ajoute à la fin, affichée si elle
912
- l'est par défaut ; une colonne non offerte ici (`disponibles` : droit manquant) garde son état et
913
- 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
914
1092
  de `useDataTable` et de `DataTableViewOptions`) limite le panneau « Colonnes » aux colonnes des
915
1093
  préférences : les fixes et les autres n'y sont ni masquables ni déplaçables. `reinitialiser()`
916
1094
  revient aux valeurs par
@@ -962,16 +1140,23 @@ focus revient).
962
1140
  Textes chiffrés en français : une valeur absente rend un repli (« — » par défaut, dernier
963
1141
  argument ou option `repli`), une date illisible est rendue telle quelle.
964
1142
 
965
- | Fonction | Rôle |
966
- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
967
- | `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. |
968
- | `formaterOctets` | « 512 o », « 1,5 Ko », « 120 Mo » (base 1 024, une décimale sous 100). |
969
- | `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 »). |
970
- | `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 ». |
971
- | `lireDateIso`, `ecrireDateIso` | Date sans heure de l'API (`AAAA-MM-JJ`) ↔ `Date` du `DatePicker`, en heure locale ; un 31 février est refusé. |
972
- | `normaliser`, `correspondance` | Texte sans accents ni casse ; filtre d'une recherche locale (`correspondance(recherche)(...textes)`, recherche vide : tout passe). |
973
- | `NO_AUTOFILL` | Attributs à étaler sur un champ qui n'est pas un identifiant : les gestionnaires de mots de passe s'en écartent. |
974
- | `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()`. |
975
1160
 
976
1161
  ```tsx
977
1162
  const [recherche, setRecherche] = useState("")
@@ -1220,7 +1405,10 @@ overflow-y-auto`), en-tête, croix et pied restant visibles ; sans elle, tout le
1220
1405
  - `sheet.tsx` : `SheetHeader` réserve à droite la place de la croix (`pr-12`) quand
1221
1406
  `SheetContent` l'affiche (`showCloseButton`, vrai par défaut), au lieu de laisser un long
1222
1407
  titre passer dessous ; `SheetContent` le lui dit par un contexte. Un `className` de
1223
- 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`.
1224
1412
 
1225
1413
  Le thème ajoute aussi (`styles.css`, hors composants shadcn) la règle de mouvement réduit.
1226
1414
 
@@ -11,6 +11,16 @@ export interface AppShellLien {
11
11
  /** Page à l'écran. Calculé par l'application, seule à savoir qu'une fiche
12
12
  * appartient à telle rubrique. */
13
13
  actif?: boolean;
14
+ /**
15
+ * Pastille à droite de l'entrée : un compteur (éléments à traiter…). Rien
16
+ * pour `0`, `""` ou sans valeur. Barre repliée : un point sur l'icône, le
17
+ * compte dans l'infobulle.
18
+ */
19
+ badge?: number | string | null;
20
+ /** Ce que lisent les lecteurs d'écran après le libellé, et ce que dit
21
+ * l'infobulle de la barre repliée : « 3 à traiter ». Le badge seul par
22
+ * défaut. */
23
+ libelleBadge?: string;
14
24
  }
15
25
  export interface AppShellSection {
16
26
  titre?: string;