@etic-insa/ui 0.8.0 → 0.9.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 (49) hide show
  1. package/README.md +110 -63
  2. package/dist/components/etic/data-table.d.ts +13 -2
  3. package/dist/components/etic/data-table.js +227 -213
  4. package/dist/components/etic/data-table.js.map +1 -1
  5. package/dist/components/etic/empty-value.d.ts +17 -0
  6. package/dist/components/etic/empty-value.js +20 -0
  7. package/dist/components/etic/empty-value.js.map +1 -0
  8. package/dist/components/etic/external-link.d.ts +5 -2
  9. package/dist/components/etic/external-link.js +7 -3
  10. package/dist/components/etic/external-link.js.map +1 -1
  11. package/dist/components/etic/form-field.d.ts +6 -6
  12. package/dist/components/etic/form-field.js +40 -38
  13. package/dist/components/etic/form-field.js.map +1 -1
  14. package/dist/components/etic/lien.d.ts +22 -0
  15. package/dist/components/etic/lien.js +10 -1
  16. package/dist/components/etic/lien.js.map +1 -1
  17. package/dist/components/etic/save-bar.d.ts +16 -0
  18. package/dist/components/etic/save-bar.js +4 -1
  19. package/dist/components/etic/save-bar.js.map +1 -1
  20. package/dist/components/etic/search-select.js +77 -76
  21. package/dist/components/etic/search-select.js.map +1 -1
  22. package/dist/components/etic/unit-input.d.ts +25 -0
  23. package/dist/components/etic/unit-input.js +21 -0
  24. package/dist/components/etic/unit-input.js.map +1 -0
  25. package/dist/components/etic/use-unsaved-changes-guard.d.ts +32 -0
  26. package/dist/components/etic/use-unsaved-changes-guard.js +25 -0
  27. package/dist/components/etic/use-unsaved-changes-guard.js.map +1 -0
  28. package/dist/hooks/use-debounced-search.d.ts +2 -1
  29. package/dist/hooks/use-debounced-search.js.map +1 -1
  30. package/dist/hooks/use-debounced-value.js +8 -7
  31. package/dist/hooks/use-debounced-value.js.map +1 -1
  32. package/dist/index.d.ts +8 -4
  33. package/dist/index.js +122 -118
  34. package/dist/lib/delai-frappe.d.ts +3 -0
  35. package/dist/lib/delai-frappe.js +15 -0
  36. package/dist/lib/delai-frappe.js.map +1 -0
  37. package/dist/lib/format.d.ts +18 -0
  38. package/dist/lib/format.js +31 -24
  39. package/dist/lib/format.js.map +1 -1
  40. package/dist/lib/grouper.d.ts +20 -0
  41. package/dist/lib/grouper.js +16 -0
  42. package/dist/lib/grouper.js.map +1 -0
  43. package/dist/testing/controles.d.ts +35 -0
  44. package/dist/testing/controles.js +33 -0
  45. package/dist/testing/controles.js.map +1 -0
  46. package/dist/testing/index.d.ts +8 -0
  47. package/dist/testing/index.js +21 -17
  48. package/dist/testing/index.js.map +1 -1
  49. package/package.json +9 -1
package/README.md CHANGED
@@ -220,7 +220,10 @@ gras d'un éditeur). Sur mobile, la page réserve en haut la hauteur de la barre
220
220
  Le composant de lien du routeur se donne une fois, autour de l'application :
221
221
  `<LienProvider lien={LienRouteur}>`, où `LienRouteur` est une référence stable, définie
222
222
  au niveau du module (un composant écrit en ligne serait nouveau à chaque rendu, et React
223
- remonterait tous les liens). `AppShell`, `DetailHeader`, `ButtonLink` et
223
+ remonterait tous les liens). `creerLienRouteur(Link)` le fabrique à partir du `Link` d'un
224
+ routeur qui prend sa destination dans `to` (react-router, TanStack Router), sans que la
225
+ bibliothèque en importe aucun : `const LienRouteur = creerLienRouteur(Link)`. Sans `href`, il
226
+ rend un `<a>` sans adresse (texte inerte), pas un lien vers l'accueil. `AppShell`, `DetailHeader`, `ButtonLink` et
224
227
  `DataTableCellLink` le prennent alors par défaut, sans `lien={…}` à chaque appel ; leur
225
228
  prop `lien` reste prioritaire. Téléchargement ou adresse externe : `lien="a"` (un vrai
226
229
  `<a>`, rechargement complet). Sans fournisseur ni prop, un `<a>`. `useLien(lien?)` rend le
@@ -268,36 +271,36 @@ Compositions des primitives shadcn pour les états d'une page et les actions cou
268
271
  connaissent ni l'API ni le routeur : l'application fournit ses fonctions (envoi, suppression,
269
272
  chargement d'une image) et, au besoin, son composant de lien (`lien`, comme pour `AppShell`).
270
273
 
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). |
274
+ | Composant | Rôle |
275
+ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
276
+ | `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. |
277
+ | `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. |
278
+ | `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. |
279
+ | `UnsavedChangesDialog`, `useUnsavedChangesWarning`, `useUnsavedChangesGuard` | 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). `useUnsavedChangesGuard(modifie, resteDansLaPage?)` fait les deux : il retient la fermeture de l'onglet et rend le garde à passer au routeur (`useBlocker`), qui laisse passer une navigation sans changement de chemin (paramètres d'URL, tiroir) ; stable, il lit `modifie` au moment de naviguer. |
280
+ | `PageContainer` | Conteneur de page dans `AppShell` : marges, `largeur` maximale, espacement entre les blocs. |
281
+ | `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. |
282
+ | `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). |
283
+ | `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). |
284
+ | `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. |
285
+ | `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. |
286
+ | `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. |
287
+ | `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. |
288
+ | `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 ». |
289
+ | `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`. |
290
+ | `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. |
291
+ | `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`. |
292
+ | `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. |
293
+ | `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. |
294
+ | `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). |
295
+ | `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). |
296
+ | `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`). |
297
+ | `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. |
298
+ | `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. |
299
+ | `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. |
300
+ | `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). |
301
+ | `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). |
302
+ | `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. |
303
+ | `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). |
301
304
 
302
305
  `ConfirmDialog` et `FormDialog` s'ouvrent par un `declencheur`, ou sont contrôlés (`ouvert`,
303
306
  `onOuvertChange`). `DeleteButton` est son propre déclencheur ; `ouvert` et `onOuvertChange`
@@ -348,12 +351,9 @@ contenu dans `DialogBody` (aussi dans un `AlertDialogContent`) ; sans lui, tout
348
351
  défile.
349
352
 
350
353
  ```tsx
351
- // Garde « modifications non enregistrées » avec react-router (routeur « data »).
352
- useUnsavedChangesWarning(modifie)
353
- const blocage = useBlocker(
354
- ({ currentLocation, nextLocation }) =>
355
- modifie && currentLocation.pathname !== nextLocation.pathname
356
- )
354
+ // Garde « modifications non enregistrées » avec react-router (routeur « data ») :
355
+ // fermeture de l'onglet et navigation vers une autre page.
356
+ const blocage = useBlocker(useUnsavedChangesGuard(modifie))
357
357
  <UnsavedChangesDialog blocage={blocage} />
358
358
  ```
359
359
 
@@ -403,7 +403,12 @@ point. `DetailMetaLink` y est le lien discret, du ton de la ligne et souligné a
403
403
  (`href`, `lien` du routeur, `externe` : nouvel onglet et flèche sortante). Hors de cette ligne,
404
404
  `ExternalLink` mène à une page hébergée ailleurs : nouvel onglet, flèche sortante et « (nouvel
405
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.
406
+ `DropdownMenuExternalLink` en est l'entrée de menu, `DataTableCellLink` avec `externe` le
407
+ titre d'une ligne (un fichier partagé). Un lien sortant composé à la main étale
408
+ `NOUVEL_ONGLET` (`target="_blank"` et `rel="noopener noreferrer"`, jamais l'un sans l'autre)
409
+ et finit par `MarqueExterne` (flèche, et « (nouvel onglet) » pour les lecteurs d'écran ; `libelle`
410
+ précise la destination : « ouvrir sur le Drive, nouvel onglet »). `DataTableCellLink` relaie ce
411
+ libellé par `libelleExterne`.
407
412
 
408
413
  ```tsx
409
414
  <DetailHeader
@@ -551,7 +556,7 @@ texte affiché ; `SearchSelect` soumet `idElement(valeur)`.
551
556
  - l'enfant direct reçoit toujours `id`, `aria-describedby` et `aria-invalid` ; autour d'un
552
557
  `InputGroup`, c'est son champ (`InputGroupInput`, `InputGroupTextarea`) qui les reçoit ;
553
558
  - s'il est un champ natif ou une primitive shadcn de saisie (`Input`, `Textarea`,
554
- `NativeSelect`, champ d'`InputGroup`), il reçoit `required` ; sinon `aria-required`
559
+ `NativeSelect`, champ d'`InputGroup`, `UnitInput`), il reçoit `required` ; sinon `aria-required`
555
560
  (déclencheur de `Select`, `ComboboxInput`…) ;
556
561
  - un contrôle composite lit le contexte du champ, `useFormField()`, et pose lui-même ces
557
562
  attributs et un vrai `required` sur son élément de saisie : c'est ce que font
@@ -571,6 +576,11 @@ obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe
571
576
  focus au contrôle. Le contrôle prend la place restante, dans la limite de sa largeur
572
577
  maximale.
573
578
 
579
+ - `UnitInput` : champ chiffré suivi de son unité (`unite` : « % », « € », « Mo »), un
580
+ `InputGroup` tout fait. `className` va à l'enveloppe (sa largeur), le reste au champ ; par
581
+ défaut `inputMode="decimal"`, chiffres à chasse fixe et `NO_AUTOFILL`. En champ texte relu
582
+ par `lireNombre`, il admet la virgule, que `type="number"` refuse selon le navigateur.
583
+
574
584
  #### Valeurs enregistrées et valeurs par défaut
575
585
 
576
586
  Règle commune aux formulaires de page (profil, paramètres) :
@@ -611,7 +621,11 @@ Règle commune aux formulaires de page (profil, paramètres) :
611
621
  onRetablir: toutRetablir,
612
622
  // Rien à rétablir : la saisie vaut tous les défauts, ou ce qui est enregistré les vaut
613
623
  // (« Annuler » y revient alors).
614
- masque: toutAuDefaut || enregistreAuDefaut,
624
+ masque: retablirDefautsMasque(
625
+ CHAMPS,
626
+ (champ) => saisie[champ] === defauts[champ],
627
+ (champ) => enregistre[champ] === defauts[champ]
628
+ ),
615
629
  }}
616
630
  />
617
631
  ```
@@ -729,27 +743,28 @@ La famille `DataTable` suit le [guide Data Table de shadcn](https://ui.shadcn.co
729
743
  sur [TanStack Table v9](https://tanstack.com/table/latest) : les colonnes se déclarent avec
730
744
  l'assistant typé, `useDataTable` crée l'instance, les composants la reçoivent en `table`.
731
745
 
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
- | `useListUrlState` | page, taille, tri, recherche et filtres d'une liste gardés dans l'URL : le retour arrière depuis un élément retrouve la liste telle qu'on l'a laissée |
751
- | `FilteredEmptyState` | vide d'une liste filtrée, distinct d'un vide réel : « Réinitialiser les filtres » |
752
- | `usePersistedState` | `useState` gardé dans le navigateur (filtre choisi…), sous la portée `PorteeStockageLocal` |
746
+ | Composant | Rôle |
747
+ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
748
+ | `useDataTable` | instance TanStack : tri, filtre et pagination (côté client, ou serveur avec `triManuel`), colonnes, sélection, dépliage |
749
+ | `DataTable` | la Table de shadcn ; état vide, lignes fantômes du chargement, bandeau d'erreur (`requete`), clic de ligne, détail déplié |
750
+ | `DataTableColumnHeader` | en-tête triable : un clic trie par ordre croissant, le suivant inverse le sens |
751
+ | `dataTableSelectionColumn` | colonne de cases ; Maj+clic sélectionne une plage ; raison d'une case verrouillée |
752
+ | `dataTableExpandColumn` | colonne du chevron qui déplie une ligne (`aria-expanded`, `aria-controls`) |
753
+ | `dataTableActionsColumn` | colonne des commandes d'une ligne : en-tête lu mais invisible, commandes à droite |
754
+ | `DataTableCellLink` | titre d'une ligne : vrai lien (`href`, routeur par `lien`) ou bouton ; `externe` : page hébergée ailleurs, nouvel onglet et flèche sortante (`libelleExterne` pour dire la destination) |
755
+ | `EmptyValue` | valeur absente d'une cellule : « — » gris, lu « non renseigné » (`libelle`) par les lecteurs d'écran |
756
+ | `DataTableRowActions` | menu « … » d'une ligne |
757
+ | `DropdownMenuAction` | entrée d'un menu d'actions : `libelle`, `icone`, `destructif`, `description` ; `verrou` grise l'entrée et affiche sa raison sous le libellé |
758
+ | `DataTableViewOptions` | bouton « Colonnes » : afficher, masquer, réordonner (glisser-déposer, clavier compris) ; absent sans colonne à régler |
759
+ | `DataTableToolbar` | recherche, filtres (`DataTableSelectFilter`), filtres moins courants derrière « Plus de filtres » (`filtresSecondaires`), compteur (`DataTableCount`), commandes |
760
+ | `DataTablePagination` | pagination par décalage (offset/limit, total connu), ou celle du tableau (`table`) |
761
+ | `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 |
762
+ | `useColumnPrefs` | colonnes affichées et leur ordre, gardés dans le navigateur par liste et par personne |
763
+ | `useServerPagination` | compteur et pagination d'une page reçue du serveur ; un décalage au-delà du total ramène à la dernière page |
764
+ | `useServerSorting` | tri d'une liste triée par le serveur, à étaler dans `useDataTable` |
765
+ | `useListUrlState` | page, taille, tri, recherche et filtres d'une liste gardés dans l'URL : le retour arrière depuis un élément retrouve la liste telle qu'on l'a laissée |
766
+ | `FilteredEmptyState` | vide d'une liste filtrée, distinct d'un vide réel : « Réinitialiser les filtres » |
767
+ | `usePersistedState` | `useState` gardé dans le navigateur (filtre choisi…), sous la portée `PorteeStockageLocal` |
753
768
 
754
769
  ```tsx
755
770
  import { keepPreviousData, useQuery } from "@tanstack/react-query"
@@ -1182,6 +1197,8 @@ argument ou option `repli`), une date illisible est rendue telle quelle.
1182
1197
  | `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 »). |
1183
1198
  | `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. |
1184
1199
  | `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 ». |
1200
+ | `lireNombre` | Nombre saisi à la française, pendant de `formaterNombre` : virgule ou point, espaces (insécables compris) ; `pourcentage` tolère un « % » final (« 15 % » → 15) ; `null` si illisible ou vide (jamais 0), écriture décimale seule (« 1e3 » refusé). |
1201
+ | `grouperPar` | Regroupe une liste par clé (`grouperPar(elements, cle, libelle)` → `{ cle, libelle, elements }[]`), dans l'ordre d'apparition des groupes et de leurs éléments ; libellé lu sur le premier élément. |
1185
1202
  | `lireDateIso`, `ecrireDateIso` | Date sans heure de l'API (`AAAA-MM-JJ`) ↔ `Date` du `DatePicker`, en heure locale ; un 31 février est refusé. |
1186
1203
  | `normaliser`, `correspondance` | Texte sans accents ni casse ; filtre d'une recherche locale (`correspondance(recherche)(...textes)`, recherche vide : tout passe). |
1187
1204
  | `NO_AUTOFILL` | Attributs à étaler sur un champ qui n'est pas un identifiant : les gestionnaires de mots de passe s'en écartent. |
@@ -1233,17 +1250,47 @@ part, qui n'entre pas dans leur bundle. `installMatchMedia()` remplace `window.m
1233
1250
  une doublure pilotable (celui de jsdom n'existe pas, celui de happy-dom suit une fenêtre fixe de
1234
1251
  1 024 px, donc mobile pour la bibliothèque) ; `setMobileViewport(true)` passe en affichage
1235
1252
  mobile, dans un `act()` sur un composant déjà monté. Seule la requête de `useIsMobile` est
1236
- connue ; toute autre ne correspond pas.
1253
+ connue ; toute autre ne correspond pas. `setSearchDelay(0)` supprime la pause de frappe par
1254
+ défaut (300 ms) de `SearchSelect`, `useDebouncedValue` et `useDebouncedSearch` : une recherche
1255
+ simulée n'attend plus réellement ; un `delai` passé explicitement reste respecté.
1237
1256
 
1238
1257
  ```ts
1239
1258
  // src/test/setup.ts de l'application
1240
1259
  import { beforeEach } from "vitest"
1241
- import { installMatchMedia, setMobileViewport } from "@etic-insa/ui/test"
1260
+ import {
1261
+ installMatchMedia,
1262
+ setMobileViewport,
1263
+ setSearchDelay,
1264
+ } from "@etic-insa/ui/test"
1242
1265
 
1243
1266
  installMatchMedia()
1267
+ setSearchDelay(0)
1244
1268
  beforeEach(() => setMobileViewport(false))
1245
1269
  ```
1246
1270
 
1271
+ `@etic-insa/ui/test/controles` lit et manipule les contrôles de la bibliothèque comme un
1272
+ utilisateur. Une entrée à part, seule à importer `@testing-library/react` (dépendance pair
1273
+ facultative) : `@etic-insa/ui/test` reste utilisable sans lui.
1274
+
1275
+ - `inactif(bouton)` : `disabled`, ou `aria-disabled` d'un bouton retenu par son `verrou`, qui
1276
+ reste focalisable ; `coche(controle)` : `checked` natif ou `aria-checked` de la
1277
+ bibliothèque.
1278
+ - `appuyer(element)` : un appui complet (appui, relâché, clic) ; les options de Base UI
1279
+ réagissent au relâché, qu'un `fireEvent.click` n'envoie pas.
1280
+ - `choisir(liste, option)`, `optionsDe(liste)`, `valeurAffichee(liste)` : choisir une option
1281
+ d'un `Select` et attendre qu'il se referme ; lire ses options ; lire le libellé affiché
1282
+ (ou le texte d'invite).
1283
+ - `chercher(champ, texte, option)` : taper dans un `SearchSelect` et choisir une suggestion.
1284
+ Elle attend la recherche différée puis la réponse : relever le délai des attentes
1285
+ (`configure({ asyncUtilTimeout })`) plutôt que d'ajouter des `timeout`.
1286
+
1287
+ ```ts
1288
+ import { choisir, inactif } from "@etic-insa/ui/test/controles"
1289
+
1290
+ await choisir(screen.getByRole("combobox", { name: "Thème" }), "Sombre")
1291
+ expect(inactif(screen.getByRole("button", { name: "Supprimer" }))).toBe(true)
1292
+ ```
1293
+
1247
1294
  ### Développer contre les sources locales
1248
1295
 
1249
1296
  Pour voir une modification de la bibliothèque instantanément dans une application, sans publier,
@@ -412,20 +412,31 @@ type DataTableCellLinkCommun = {
412
412
  export type DataTableCellLinkProps = DataTableCellLinkCommun & Omit<ComponentProps<"a">, "children" | "className"> & {
413
413
  href: string;
414
414
  /** Lien du routeur de l'application ; par défaut, celui du
415
- * `LienProvider`, sinon un `<a>`. */
415
+ * `LienProvider`, sinon un `<a>`. Ignoré avec `externe`. */
416
416
  lien?: LienComposant;
417
+ /** Page hébergée ailleurs (document partagé…) : un vrai `<a>` ouvert
418
+ * dans un nouvel onglet, flèche sortante et « (nouvel onglet) » pour
419
+ * les lecteurs d'écran, comme `ExternalLink`. */
420
+ externe?: boolean;
421
+ /** Avec `externe`, ce que disent les lecteurs d'écran entre parenthèses
422
+ * après le titre : « nouvel onglet » par défaut ; à préciser pour dire
423
+ * la destination (« ouvrir sur le Drive, nouvel onglet »). */
424
+ libelleExterne?: string;
417
425
  };
418
426
  /** Bouton de cellule : une action sur place (ouvrir la modification…). */
419
427
  export type DataTableCellButtonProps = DataTableCellLinkCommun & Omit<ComponentProps<"button">, "children" | "className"> & {
420
428
  href?: never;
421
429
  lien?: never;
430
+ externe?: never;
431
+ libelleExterne?: never;
422
432
  };
423
433
  /**
424
434
  * Titre d'une ligne qui mène à sa fiche : un vrai lien (`href`, routeur par
425
435
  * `lien` ou le `LienProvider`), ou un bouton sans `href` (ouvrir la modification). Le clic de
426
436
  * ligne (`onActiverLigne`) n'est qu'un raccourci à la souris : ce lien est
427
437
  * le chemin du clavier et des lecteurs d'écran, et garde l'ouverture dans un
428
- * nouvel onglet.
438
+ * nouvel onglet. `externe` : une page hébergée ailleurs, ouverte dans un
439
+ * nouvel onglet, et qui le dit.
429
440
  */
430
441
  export declare function DataTableCellLink(props: DataTableCellLinkProps | DataTableCellButtonProps): import("react").JSX.Element;
431
442
  export {};