@etic-insa/ui 0.0.0 → 0.2.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 (239) hide show
  1. package/README.md +549 -9
  2. package/dist/components/etic/action.d.ts +33 -0
  3. package/dist/components/etic/action.js +43 -0
  4. package/dist/components/etic/action.js.map +1 -0
  5. package/dist/components/etic/app-shell.d.ts +72 -0
  6. package/dist/components/etic/app-shell.js +218 -0
  7. package/dist/components/etic/app-shell.js.map +1 -0
  8. package/dist/components/etic/auth-image.d.ts +48 -0
  9. package/dist/components/etic/auth-image.js +44 -0
  10. package/dist/components/etic/auth-image.js.map +1 -0
  11. package/dist/components/etic/checkbox-list.d.ts +30 -0
  12. package/dist/components/etic/checkbox-list.js +56 -0
  13. package/dist/components/etic/checkbox-list.js.map +1 -0
  14. package/dist/components/etic/confirm-dialog.d.ts +63 -0
  15. package/dist/components/etic/confirm-dialog.js +84 -0
  16. package/dist/components/etic/confirm-dialog.js.map +1 -0
  17. package/dist/components/etic/copy-button.d.ts +24 -0
  18. package/dist/components/etic/copy-button.js +46 -0
  19. package/dist/components/etic/copy-button.js.map +1 -0
  20. package/dist/components/etic/data-table-bulk-actions.d.ts +29 -0
  21. package/dist/components/etic/data-table-bulk-actions.js +97 -0
  22. package/dist/components/etic/data-table-bulk-actions.js.map +1 -0
  23. package/dist/components/etic/data-table-format.d.ts +12 -0
  24. package/dist/components/etic/data-table-format.js +8 -0
  25. package/dist/components/etic/data-table-format.js.map +1 -0
  26. package/dist/components/etic/data-table-pagination.d.ts +22 -0
  27. package/dist/components/etic/data-table-pagination.js +104 -0
  28. package/dist/components/etic/data-table-pagination.js.map +1 -0
  29. package/dist/components/etic/data-table-toolbar.d.ts +69 -0
  30. package/dist/components/etic/data-table-toolbar.js +127 -0
  31. package/dist/components/etic/data-table-toolbar.js.map +1 -0
  32. package/dist/components/etic/data-table-view-options.d.ts +16 -0
  33. package/dist/components/etic/data-table-view-options.js +151 -0
  34. package/dist/components/etic/data-table-view-options.js.map +1 -0
  35. package/dist/components/etic/data-table.d.ts +263 -0
  36. package/dist/components/etic/data-table.js +403 -0
  37. package/dist/components/etic/data-table.js.map +1 -0
  38. package/dist/components/etic/date-picker.d.ts +32 -0
  39. package/dist/components/etic/date-picker.js +162 -0
  40. package/dist/components/etic/date-picker.js.map +1 -0
  41. package/dist/components/etic/delete-button.d.ts +57 -0
  42. package/dist/components/etic/delete-button.js +38 -0
  43. package/dist/components/etic/delete-button.js.map +1 -0
  44. package/dist/components/etic/detail-list.d.ts +14 -0
  45. package/dist/components/etic/detail-list.js +36 -0
  46. package/dist/components/etic/detail-list.js.map +1 -0
  47. package/dist/components/etic/empty-state.d.ts +20 -0
  48. package/dist/components/etic/empty-state.js +20 -0
  49. package/dist/components/etic/empty-state.js.map +1 -0
  50. package/dist/components/etic/error-banner.d.ts +50 -0
  51. package/dist/components/etic/error-banner.js +89 -0
  52. package/dist/components/etic/error-banner.js.map +1 -0
  53. package/dist/components/etic/error-boundary.d.ts +53 -0
  54. package/dist/components/etic/error-boundary.js +82 -0
  55. package/dist/components/etic/error-boundary.js.map +1 -0
  56. package/dist/components/etic/file-upload.d.ts +52 -0
  57. package/dist/components/etic/file-upload.js +142 -0
  58. package/dist/components/etic/file-upload.js.map +1 -0
  59. package/dist/components/etic/form-dialog.d.ts +45 -0
  60. package/dist/components/etic/form-dialog.js +136 -0
  61. package/dist/components/etic/form-dialog.js.map +1 -0
  62. package/dist/components/etic/form-field-context.d.ts +66 -0
  63. package/dist/components/etic/form-field-context.js +28 -0
  64. package/dist/components/etic/form-field-context.js.map +1 -0
  65. package/dist/components/etic/form-field.d.ts +53 -0
  66. package/dist/components/etic/form-field.js +105 -0
  67. package/dist/components/etic/form-field.js.map +1 -0
  68. package/dist/components/etic/icon-toggle.d.ts +33 -0
  69. package/dist/components/etic/icon-toggle.js +28 -0
  70. package/dist/components/etic/icon-toggle.js.map +1 -0
  71. package/dist/components/etic/loading.d.ts +45 -0
  72. package/dist/components/etic/loading.js +82 -0
  73. package/dist/components/etic/loading.js.map +1 -0
  74. package/dist/components/etic/page-container.d.ts +17 -0
  75. package/dist/components/etic/page-container.js +20 -0
  76. package/dist/components/etic/page-container.js.map +1 -0
  77. package/dist/components/etic/page-header.d.ts +58 -0
  78. package/dist/components/etic/page-header.js +104 -0
  79. package/dist/components/etic/page-header.js.map +1 -0
  80. package/dist/components/etic/phone-input.d.ts +31 -0
  81. package/dist/components/etic/phone-input.js +133 -0
  82. package/dist/components/etic/phone-input.js.map +1 -0
  83. package/dist/components/etic/query-boundary.d.ts +50 -0
  84. package/dist/components/etic/query-boundary.js +25 -0
  85. package/dist/components/etic/query-boundary.js.map +1 -0
  86. package/dist/components/etic/search-select.d.ts +41 -0
  87. package/dist/components/etic/search-select.js +126 -0
  88. package/dist/components/etic/search-select.js.map +1 -0
  89. package/dist/components/etic/section-card.d.ts +12 -0
  90. package/dist/components/etic/section-card.js +23 -0
  91. package/dist/components/etic/section-card.js.map +1 -0
  92. package/dist/components/etic/segmented-control.d.ts +29 -0
  93. package/dist/components/etic/segmented-control.js +44 -0
  94. package/dist/components/etic/segmented-control.js.map +1 -0
  95. package/dist/components/etic/stat-tile.d.ts +18 -0
  96. package/dist/components/etic/stat-tile.js +39 -0
  97. package/dist/components/etic/stat-tile.js.map +1 -0
  98. package/dist/components/etic/status-badge.d.ts +16 -0
  99. package/dist/components/etic/status-badge.js +30 -0
  100. package/dist/components/etic/status-badge.js.map +1 -0
  101. package/dist/components/etic/theme-menu.d.ts +21 -0
  102. package/dist/components/etic/theme-menu.js +72 -0
  103. package/dist/components/etic/theme-menu.js.map +1 -0
  104. package/dist/components/etic/tooltip-button.d.ts +29 -0
  105. package/dist/components/etic/tooltip-button.js +39 -0
  106. package/dist/components/etic/tooltip-button.js.map +1 -0
  107. package/dist/components/etic/use-draft-autosave.d.ts +68 -0
  108. package/dist/components/etic/use-draft-autosave.js +102 -0
  109. package/dist/components/etic/use-draft-autosave.js.map +1 -0
  110. package/dist/components/ui/alert-dialog.d.ts +18 -0
  111. package/dist/components/ui/alert-dialog.js +95 -0
  112. package/dist/components/ui/alert-dialog.js.map +1 -0
  113. package/dist/components/ui/alert.d.ts +10 -0
  114. package/dist/components/ui/alert.js +47 -0
  115. package/dist/components/ui/alert.js.map +1 -0
  116. package/dist/components/ui/avatar.d.ts +11 -0
  117. package/dist/components/ui/avatar.js +52 -0
  118. package/dist/components/ui/avatar.js.map +1 -0
  119. package/dist/components/ui/badge.d.ts +7 -0
  120. package/dist/components/ui/badge.js +32 -0
  121. package/dist/components/ui/badge.js.map +1 -0
  122. package/dist/components/ui/breadcrumb.d.ts +10 -0
  123. package/dist/components/ui/breadcrumb.js +73 -0
  124. package/dist/components/ui/breadcrumb.js.map +1 -0
  125. package/dist/components/ui/button-group.d.ts +10 -0
  126. package/dist/components/ui/button-group.js +42 -0
  127. package/dist/components/ui/button-group.js.map +1 -0
  128. package/dist/components/ui/button.d.ts +1 -1
  129. package/dist/components/ui/button.js +8 -8
  130. package/dist/components/ui/button.js.map +1 -1
  131. package/dist/components/ui/calendar.d.ts +10 -0
  132. package/dist/components/ui/calendar.js +96 -0
  133. package/dist/components/ui/calendar.js.map +1 -0
  134. package/dist/components/ui/card.d.ts +11 -0
  135. package/dist/components/ui/card.js +57 -0
  136. package/dist/components/ui/card.js.map +1 -0
  137. package/dist/components/ui/checkbox.d.ts +3 -0
  138. package/dist/components/ui/checkbox.js +20 -0
  139. package/dist/components/ui/checkbox.js.map +1 -0
  140. package/dist/components/ui/collapsible.d.ts +5 -0
  141. package/dist/components/ui/collapsible.js +25 -0
  142. package/dist/components/ui/collapsible.js.map +1 -0
  143. package/dist/components/ui/combobox.d.ts +24 -0
  144. package/dist/components/ui/combobox.js +165 -0
  145. package/dist/components/ui/combobox.js.map +1 -0
  146. package/dist/components/ui/dialog.d.ts +17 -0
  147. package/dist/components/ui/dialog.js +92 -0
  148. package/dist/components/ui/dialog.js.map +1 -0
  149. package/dist/components/ui/dropdown-menu.d.ts +29 -0
  150. package/dist/components/ui/dropdown-menu.js +137 -0
  151. package/dist/components/ui/dropdown-menu.js.map +1 -0
  152. package/dist/components/ui/empty.d.ts +11 -0
  153. package/dist/components/ui/empty.js +60 -0
  154. package/dist/components/ui/empty.js.map +1 -0
  155. package/dist/components/ui/field.d.ts +24 -0
  156. package/dist/components/ui/field.js +108 -0
  157. package/dist/components/ui/field.js.map +1 -0
  158. package/dist/components/ui/input-group.d.ts +18 -0
  159. package/dist/components/ui/input-group.js +79 -0
  160. package/dist/components/ui/input-group.js.map +1 -0
  161. package/dist/components/ui/input.d.ts +3 -0
  162. package/dist/components/ui/input.js +16 -0
  163. package/dist/components/ui/input.js.map +1 -0
  164. package/dist/components/ui/item.d.ts +22 -0
  165. package/dist/components/ui/item.js +122 -0
  166. package/dist/components/ui/item.js.map +1 -0
  167. package/dist/components/ui/kbd.d.ts +3 -0
  168. package/dist/components/ui/kbd.js +20 -0
  169. package/dist/components/ui/kbd.js.map +1 -0
  170. package/dist/components/ui/label.d.ts +3 -0
  171. package/dist/components/ui/label.js +14 -0
  172. package/dist/components/ui/label.js.map +1 -0
  173. package/dist/components/ui/native-select.d.ts +8 -0
  174. package/dist/components/ui/native-select.js +39 -0
  175. package/dist/components/ui/native-select.js.map +1 -0
  176. package/dist/components/ui/pagination.d.ts +17 -0
  177. package/dist/components/ui/pagination.js +81 -0
  178. package/dist/components/ui/pagination.js.map +1 -0
  179. package/dist/components/ui/popover.d.ts +9 -0
  180. package/dist/components/ui/popover.js +55 -0
  181. package/dist/components/ui/popover.js.map +1 -0
  182. package/dist/components/ui/progress.d.ts +7 -0
  183. package/dist/components/ui/progress.js +45 -0
  184. package/dist/components/ui/progress.js.map +1 -0
  185. package/dist/components/ui/radio-group.d.ts +5 -0
  186. package/dist/components/ui/radio-group.js +27 -0
  187. package/dist/components/ui/radio-group.js.map +1 -0
  188. package/dist/components/ui/scroll-area.d.ts +4 -0
  189. package/dist/components/ui/scroll-area.js +36 -0
  190. package/dist/components/ui/scroll-area.js.map +1 -0
  191. package/dist/components/ui/select.d.ts +15 -0
  192. package/dist/components/ui/select.js +99 -0
  193. package/dist/components/ui/select.js.map +1 -0
  194. package/dist/components/ui/separator.d.ts +3 -0
  195. package/dist/components/ui/separator.js +15 -0
  196. package/dist/components/ui/separator.js.map +1 -0
  197. package/dist/components/ui/sheet.d.ts +14 -0
  198. package/dist/components/ui/sheet.js +90 -0
  199. package/dist/components/ui/sheet.js.map +1 -0
  200. package/dist/components/ui/sidebar.d.ts +63 -0
  201. package/dist/components/ui/sidebar.js +358 -0
  202. package/dist/components/ui/sidebar.js.map +1 -0
  203. package/dist/components/ui/skeleton.d.ts +2 -0
  204. package/dist/components/ui/skeleton.js +13 -0
  205. package/dist/components/ui/skeleton.js.map +1 -0
  206. package/dist/components/ui/slider.d.ts +3 -0
  207. package/dist/components/ui/slider.js +36 -0
  208. package/dist/components/ui/slider.js.map +1 -0
  209. package/dist/components/ui/spinner.d.ts +2 -0
  210. package/dist/components/ui/spinner.js +16 -0
  211. package/dist/components/ui/spinner.js.map +1 -0
  212. package/dist/components/ui/switch.d.ts +5 -0
  213. package/dist/components/ui/switch.js +20 -0
  214. package/dist/components/ui/switch.js.map +1 -0
  215. package/dist/components/ui/table.d.ts +10 -0
  216. package/dist/components/ui/table.js +67 -0
  217. package/dist/components/ui/table.js.map +1 -0
  218. package/dist/components/ui/tabs.d.ts +10 -0
  219. package/dist/components/ui/tabs.js +46 -0
  220. package/dist/components/ui/tabs.js.map +1 -0
  221. package/dist/components/ui/textarea.d.ts +3 -0
  222. package/dist/components/ui/textarea.js +14 -0
  223. package/dist/components/ui/textarea.js.map +1 -0
  224. package/dist/components/ui/toggle-group.d.ts +11 -0
  225. package/dist/components/ui/toggle-group.js +54 -0
  226. package/dist/components/ui/toggle-group.js.map +1 -0
  227. package/dist/components/ui/toggle.d.ts +8 -0
  228. package/dist/components/ui/toggle.js +36 -0
  229. package/dist/components/ui/toggle.js.map +1 -0
  230. package/dist/components/ui/tooltip.d.ts +6 -0
  231. package/dist/components/ui/tooltip.js +42 -0
  232. package/dist/components/ui/tooltip.js.map +1 -0
  233. package/dist/hooks/use-mobile.d.ts +18 -0
  234. package/dist/hooks/use-mobile.js +16 -0
  235. package/dist/hooks/use-mobile.js.map +1 -0
  236. package/dist/index.d.ts +78 -0
  237. package/dist/index.js +77 -2
  238. package/dist/styles.css +39 -4
  239. package/package.json +19 -7
package/README.md CHANGED
@@ -10,7 +10,11 @@ sur [shadcn/ui](https://ui.shadcn.com) (style Nova, couleur de base Neutral) et
10
10
  npm i @etic-insa/ui
11
11
  ```
12
12
 
13
- Prérequis : React 19 et Tailwind CSS 4 (`tailwindcss` et `@tailwindcss/vite`).
13
+ Prérequis (dépendances pairs) : React 19.2 ou plus récent (`useEffectEvent`), Tailwind CSS 4
14
+ (`tailwindcss` et `@tailwindcss/vite`) et `lucide-react` (les icônes passées aux composants,
15
+ `icone={UsersIcon}`, viennent de l'application).
16
+ `QueryBoundary` accepte tel quel le résultat de `useQuery` (TanStack Query), sans que la
17
+ bibliothèque dépende de TanStack Query : il ne lit que la forme de la requête.
14
18
 
15
19
  ```css
16
20
  /* CSS principal de l'application */
@@ -57,10 +61,9 @@ dans l'atelier ; `npm test` vérifie que ces exemples tiennent les exigences ci-
57
61
  pas publié et n'est pas la référence d'une application.
58
62
 
59
63
  Dans les classes, l'accent comme texte s'écrit `text-primary-text`, jamais `text-primary`. Les
60
- composants shadcn d'origine (`src/components/ui/`) emploient parfois `text-primary` (variante
61
- `link` du bouton) : leurs enveloppes ETIC devront le corriger. **Limite actuelle** : le `Button`
62
- exporté est encore celui de shadcn ; avec un accent clair (Docs, Intervenant, Browser), sa
63
- variante `link` est illisible en thème clair. Ne pas l'employer avant son enveloppe.
64
+ composants shadcn d'origine emploient `text-primary` (variante `link` du bouton et du badge,
65
+ liens survolés) : c'est corrigé dans `src/components/ui/`, et `npm test` échoue si
66
+ `text-primary` y réapparaît.
64
67
 
65
68
  Le thème sombre s'active par la classe `dark` sur `<html>`.
66
69
 
@@ -76,6 +79,494 @@ export function Export() {
76
79
  }
77
80
  ```
78
81
 
82
+ ### Coquille d'application
83
+
84
+ `AppShell` pose la mise en page commune : barre latérale de shadcn (marque, rubriques, menu du
85
+ compte, thème), repliable en colonne d'icônes sur ordinateur (rail ou Ctrl+B, état gardé dans le
86
+ cookie `sidebar_state` de shadcn), qui devient un tiroir ouvert par une barre du haut sous
87
+ 1 025 px (téléphones et tablettes). Il ne connaît ni le routeur ni l'authentification : l'application donne les liens et
88
+ leur état actif, le compte et le thème, et son composant de lien.
89
+
90
+ ```tsx
91
+ import { AppShell } from "@etic-insa/ui"
92
+ import { Link, Outlet, useLocation } from "react-router-dom"
93
+ import { UsersIcon } from "lucide-react"
94
+
95
+ const LienRouteur = ({ href, ...props }: React.ComponentProps<"a">) => (
96
+ <Link to={href!} {...props} />
97
+ )
98
+
99
+ export function MiseEnPage() {
100
+ const { pathname } = useLocation()
101
+ return (
102
+ <AppShell
103
+ application={{ nom: "ETIC Docs", logo: <img src={logo} alt="" /> }}
104
+ sections={[
105
+ {
106
+ titre: "Études",
107
+ liens: [
108
+ {
109
+ libelle: "Études",
110
+ href: "/etudes",
111
+ icone: UsersIcon,
112
+ actif: pathname.startsWith("/etudes"),
113
+ },
114
+ ],
115
+ },
116
+ ]}
117
+ compte={{ nom: "Ada Lovelace", initiales: "AL", onSeDeconnecter }}
118
+ theme={{ valeur: theme, onValeurChange: changerTheme }}
119
+ lien={LienRouteur}
120
+ >
121
+ <Outlet />
122
+ </AppShell>
123
+ )
124
+ }
125
+
126
+ // Dans chaque page
127
+ export function Groupes() {
128
+ return (
129
+ <PageContainer>
130
+ <PageHeader titre="Groupes" />
131
+ <SectionCard titre="Liste">…</SectionCard>
132
+ </PageContainer>
133
+ )
134
+ }
135
+ ```
136
+
137
+ `onValeurChange` peut renvoyer une promesse : rejetée, elle affiche « Thème non enregistré »
138
+ quelques secondes. La déconnexion (`onSeDeconnecter`) est toujours confirmée ; une entrée du
139
+ menu du compte est un lien (`href`) ou une action (`onChoisir`). La coquille fournit l'élément
140
+ `<main>` : les pages n'en ajoutent pas. Elle ouvre la tabulation par un lien « Aller au
141
+ contenu », visible au focus, qui met le focus sur ce `<main>`. Sur ordinateur, un bouton de
142
+ l'en-tête replie la colonne (Ctrl+B aussi, sauf dans un champ de saisie, où il reste au
143
+ gras d'un éditeur). Sur mobile, la page réserve en haut la hauteur de la barre collante
144
+ (`scroll-padding-top`) : une ancre ne s'arrête pas dessous. `ThemeMenu` existe aussi seul
145
+ (page de connexion…) ; son `className` va sur le bouton.
146
+
147
+ `PageContainer` est le conteneur de chaque page dans `AppShell` : marges (16 px sur
148
+ téléphone, 24 puis 32 px au-delà), espacement vertical régulier entre les blocs (`gap-6`),
149
+ et `largeur` maximale centrée (`md`, `lg`, `xl`, ou `full` par défaut). Les pages ne posent
150
+ pas leurs propres marges.
151
+
152
+ ### Retours et mise en page
153
+
154
+ Compositions des primitives shadcn pour les états d'une page et les actions courantes. Elles ne
155
+ connaissent ni l'API ni le routeur : l'application fournit ses fonctions (envoi, suppression,
156
+ chargement d'une image) et, au besoin, son composant de lien (`lien`, comme pour `AppShell`).
157
+
158
+ | Composant | Rôle |
159
+ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
160
+ | `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. |
161
+ | `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. |
162
+ | `PageContainer` | Conteneur de page dans `AppShell` : marges, `largeur` maximale, espacement entre les blocs. |
163
+ | `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é), `compact` quand la fiche répète déjà son nom. |
164
+ | `SectionCard`, `DetailList`, `DetailItem` | Carte de section titrée (`<h2>`) ; grille `<dl>` de paires libellé / valeur, « — » pour une valeur absente (`null`, `undefined`, `false`, chaîne vide). |
165
+ | `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`). |
166
+ | `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. |
167
+ | `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. |
168
+ | `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. |
169
+ | `StatTile`, `StatusBadge` | Chiffre clé d'un résumé ; badge d'état à pastille. `ton` (type `StatusTon`) : `neutral`, `success`, `warning`, `destructive`. |
170
+ | `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). Tous ont une infobulle, et `verrou` pour dire pourquoi l'action est impossible. |
171
+ | `TooltipButton` | `Button` avec infobulle et état `verrou` (désactivé mais focalisable, la raison en infobulle) : la règle pour tout bouton à icône seule. |
172
+ | `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. |
173
+
174
+ `ConfirmDialog` et `FormDialog` s'ouvrent par un `declencheur`, ou sont contrôlés (`ouvert`,
175
+ `onOuvertChange`). `DeleteButton` est son propre déclencheur ; `ouvert` et `onOuvertChange`
176
+ permettent de suivre sa confirmation. Leur action (`onConfirmer`, `onEnvoyer`, `onSupprimer`)
177
+ peut renvoyer une promesse : le dialogue l'attend (boutons occupés mais focalisables, Échap sans
178
+ effet), se ferme si elle aboutit, affiche l'erreur si elle échoue. Avec TanStack Query, passer
179
+ `mutateAsync`. Si l'action renvoie `false` (ou une promesse résolue à `false`), le dialogue
180
+ reste ouvert sans erreur : suppression en deux temps, où la page change sa question (la
181
+ description de `ConfirmDialog` est une région polie : la nouvelle est lue).
182
+
183
+ Un envoi de `FormDialog` refusé par les contraintes marque chaque champ fautif
184
+ (`aria-invalid`, retiré dès qu'il est corrigé) et le nomme par son libellé, y compris une
185
+ liste (`Select`, `SearchSelect`…) dont l'entrée cachée porte la valeur : le libellé de son
186
+ `FormField`, et le focus va à son contrôle visible.
187
+
188
+ Une action qui fait disparaître le déclencheur (ligne supprimée) passe `finalFocus` (un ref
189
+ ou une fonction, comme le `finalFocus` de Base UI) : le focus va à la ligne suivante ou au
190
+ titre de la liste au lieu de tomber sur la page.
191
+
192
+ ```tsx
193
+ <DeleteButton
194
+ libelle="ce groupe"
195
+ confirmation={{ description: `Le groupe « ${groupe.nom} » sera supprimé définitivement.` }}
196
+ verrou={groupe.critique ? "Groupe critique : suppression impossible" : undefined}
197
+ finalFocus={titreListe}
198
+ onSupprimer={() => supprimer.mutateAsync(groupe.id)}
199
+ />
200
+
201
+ // Suppression en deux temps : le serveur répond 409 « confirmation requise ».
202
+ const [conflit, setConflit] = useState(false)
203
+ <ConfirmDialog
204
+ titre="Supprimer le groupe"
205
+ description={conflit ? "14 rattachements seront supprimés aussi." : "Le groupe sera supprimé."}
206
+ libelleConfirmer={conflit ? "Supprimer quand même" : "Supprimer"}
207
+ onOuvertChange={(ouvert) => !ouvert && setConflit(false)}
208
+ onConfirmer={async () => {
209
+ try {
210
+ await supprimer.mutateAsync({ id, confirmer: conflit })
211
+ } catch (erreur) {
212
+ if (conflit || !confirmationRequise(erreur)) throw erreur
213
+ setConflit(true)
214
+ return false
215
+ }
216
+ }}
217
+ declencheur={<Button variant="destructive">Supprimer</Button>}
218
+ />
219
+
220
+ <QueryBoundary requete={useQuery(...)} vide="Aucun groupe.">
221
+ {(groupes) => <TableGroupes groupes={groupes} />}
222
+ </QueryBoundary>
223
+ ```
224
+
225
+ Primitives shadcn ajoutées pour ces usages : `Alert` a, en plus de `destructive`, les variantes
226
+ `warning`, `info` et `success` (couleur `--info` dans le thème, contrastes vérifiés) ; `info` et
227
+ `success`, messages d'état, portent `role="status"` (annoncés sans interrompre), les autres
228
+ `role="alert"` comme dans shadcn. `Slider` (Base UI) se nomme par `aria-labelledby` ou
229
+ `aria-label` (relayé à chaque curseur) et prend une valeur simple (`value={1.5}`, un curseur)
230
+ ou un tableau (une plage, dont les curseurs s'annoncent « minimum » et « maximum »).
231
+
232
+ Utilitaires : `cn(...classes)` fusionne des classes Tailwind (la dernière l'emporte en cas de
233
+ conflit, comme `clsx` + `tailwind-merge`) ; `useIsMobile()` vaut vrai sous le seuil mobile de
234
+ la suite, `MOBILE_MEDIA_QUERY` (`(width < 1025px)`), dès le premier rendu.
235
+
236
+ Mouvement réduit : sous `prefers-reduced-motion: reduce`, `styles.css` neutralise animations
237
+ et transitions (squelettes, ouverture des dialogues et des menus, tiroir, repli de la barre) ;
238
+ seule la roue de chargement tourne encore.
239
+
240
+ ### Formulaires
241
+
242
+ Compositions des primitives `Field`, `Combobox`, `Popover` + `Calendar`, `ToggleGroup` et
243
+ `Checkbox` de shadcn. Les champs sont contrôlés : `valeur` et `onValeurChange`
244
+ (`valeurs` et `onValeursChange` pour `CheckboxList`) ; les fichiers n'ont pas de valeur, ils
245
+ arrivent à `onChoisir`. Désactiver : `disabled`, comme en HTML. Règle : toujours le
246
+ composant shadcn le plus adapté à l'usage plutôt qu'un contrôle natif ou minimal (une longue
247
+ liste prend un `Combobox` avec recherche).
248
+
249
+ Dans les composites (`DatePicker`, `PhoneInput`, `SearchSelect`), `className` va à
250
+ l'enveloppe (`InputGroup` ou `ButtonGroup`) et les autres attributs (`ref`, `onBlur`,
251
+ `autoComplete`, `data-*`…) au champ de saisie. Avec `name`, `DatePicker` et `PhoneInput`
252
+ soumettent leur valeur (date ISO `2026-03-05`, numéro E.164) par un champ caché, et non le
253
+ texte affiché ; `SearchSelect` soumet `idElement(valeur)`.
254
+
255
+ - `FormField` : libellé (astérisque si `obligatoire`), contrôle, `description` et `erreur`
256
+ (texte ou liste), reliés au contrôle par `htmlFor`, `aria-describedby` et `aria-invalid`.
257
+ L'erreur n'est pas une alerte (`role="alert"` de shadcn retiré) : cinq champs fautifs
258
+ feraient cinq annonces. Un astérisque implique un champ requis. Règle, sur le modèle du
259
+ `useFormField()` du Form de shadcn :
260
+ - l'enfant direct reçoit toujours `id`, `aria-describedby` et `aria-invalid` ; autour d'un
261
+ `InputGroup`, c'est son champ (`InputGroupInput`, `InputGroupTextarea`) qui les reçoit ;
262
+ - s'il est un champ natif ou une primitive shadcn de saisie (`Input`, `Textarea`,
263
+ `NativeSelect`, champ d'`InputGroup`), il reçoit `required` ; sinon `aria-required`
264
+ (déclencheur de `Select`, `ComboboxInput`…) ;
265
+ - un contrôle composite lit le contexte du champ, `useFormField()`, et pose lui-même ces
266
+ attributs et un vrai `required` sur son élément de saisie : c'est ce que font
267
+ `DatePicker`, `PhoneInput` et `SearchSelect`, et ce que doit faire un composant de
268
+ l'application ;
269
+ - un groupe (`CheckboxList`, `SegmentedControl`) n'a ni `required` natif ni droit à
270
+ `aria-required` (`role="group"`) : il cite le libellé du champ par
271
+ `aria-labelledby={champ.libelleId}` (un `<label for>` ne nomme pas un groupe) et, s'il
272
+ est obligatoire, une mention masquée, ce qui donne le nom « Groupes obligatoire ». Il
273
+ prend aussi `required` hors d'un `FormField`. La vérification reste à l'application.
274
+
275
+ `useFormField()` renvoie `{ id, libelleId, descriptionId, erreurId, describedBy,
276
+ obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe seul.
277
+ `FormSection` regroupe des champs sous un titre (`FieldSet` + `FieldLegend`).
278
+
279
+ - `DatePicker` : le Date Picker de shadcn avec saisie au clavier (jj/mm/aaaa, ou les chiffres
280
+ seuls `05032026` pour le pavé numérique de l'iPhone ; lue en quittant le champ ou sur
281
+ Entrée), calendrier en français navigable aux flèches, bornes `dateMin`/`dateMax`, listes du
282
+ mois et de l'année (`listesMoisAnnee`, pour une date de naissance), bouton d'effacement.
283
+ Valeur : `Date`. Une saisie illisible ou hors bornes dit pourquoi sous le champ, bloque
284
+ l'envoi d'un formulaire natif, et `onValeurChange(undefined, { invalide: true })` prévient
285
+ l'application (à bloquer avant l'envoi).
286
+ - `PhoneInput` : sélecteur de pays (Combobox : drapeau et indicatif, recherche sur le nom du
287
+ pays ou l'indicatif) et numéro, lus et validés par
288
+ libphonenumber-js. `onValeurChange(valeur, { valide, pays })` reçoit l'E.164
289
+ (`+33612345678`) dès que la longueur est possible ; un numéro tapé avec « + » choisit le
290
+ pays.
291
+ - `SearchSelect` : choix dans une longue liste cherchée par l'application.
292
+ `rechercher(texte, signal)` renvoie une promesse (texte vide : premières suggestions) ;
293
+ `libelleElement`, `idElement` et `rendreOption` décrivent un élément. Anti-rebond,
294
+ chargement (la liste reste vide tant que la réponse ne correspond pas à la saisie : un
295
+ ancien résultat ne se choisit pas), échec avec « Réessayer » (l'erreur va à `onErreur`, ou
296
+ à la console ; au clavier, Entrée dans le champ relance la recherche, même identique),
297
+ liste vide (`vide`) et effacement sont gérés. Sans élément choisi, le texte tapé reste
298
+ quand la liste se ferme (Entrée, Tab), et la recherche reprend à la réouverture. `form`
299
+ va, comme `name`, à l'entrée cachée qui porte la valeur.
300
+ - `FileUploadButton` et `FileDropZone` : bouton, ou zone de glisser-déposer avec bouton, sur
301
+ react-dropzone. Types (`accepter={{ "text/csv": [".csv"] }}`) et taille (`tailleMax`, en
302
+ octets) vérifiés, refus en français : à `onRefuser` pour les deux, et affichés dans la zone
303
+ (après le bouton s'il n'y a pas d'`onRefuser`, en rouge, sur une ligne entière dans une
304
+ rangée `flex-wrap` ; sans refus, rien d'autre que le bouton n'occupe le flux, ce qui le
305
+ laisse dans une barre d'outils ou un `ButtonGroup`). Pendant `enCours`, le bouton reste
306
+ focalisé, indisponible, et l'envoi est annoncé. `FileUploadButton` relaie les props de
307
+ `Button` (`id`, `aria-*` : il fonctionne dans un `FormField`).
308
+ - `SegmentedControl` : choix exclusif en boutons joints (`ToggleGroup`), sans désélection ;
309
+ le segment choisi prend, en plus du fond `bg-muted`, un liseré intérieur. L'`infobulle`
310
+ d'une option nomme un segment à icône seule, sans masquer un libellé texte.
311
+ - `CheckboxList` : plusieurs valeurs parmi une liste de cases (`CheckboxGroup` de Base UI) ;
312
+ la `description` d'une option est reliée à sa case.
313
+ - `useDraftAutosave({ contenu, enregistrer })` : sauvegarde automatique d'un brouillon là où
314
+ l'application le range (API ou stockage du navigateur) — anti-rebond, sans doublon, une
315
+ écriture à la fois, version pour un verrou optimiste, `erreur` et `reessayer()`, alerte à la
316
+ fermeture de l'onglet ; `enregistrerMaintenant()` avant de quitter. Démonté (navigation
317
+ interne), il range aussitôt l'écriture en attente ; `annuler()` (avant de supprimer le
318
+ brouillon) l'abandonne, elle et celles en file. Un brouillon chargé (`versionInitiale` > 0)
319
+ n'est pas réécrit au montage ; `enregistrer` reçoit le contenu tel quel (sans passer par
320
+ JSON) ; l'objet renvoyé est stable. `marquerEnregistre(contenu)` : appelé dans le même
321
+ gestionnaire que la mise à jour du contenu, passer le nouveau.
322
+
323
+ ```tsx
324
+ <FormField libelle="Téléphone" obligatoire erreur={erreurs.telephone}>
325
+ <PhoneInput valeur={telephone} onValeurChange={setTelephone} />
326
+ </FormField>
327
+
328
+ <FormField libelle="Taille maximale">
329
+ <InputGroup>
330
+ <InputGroupInput inputMode="numeric" />
331
+ <InputGroupAddon align="inline-end">
332
+ <InputGroupText>Mo</InputGroupText>
333
+ </InputGroupAddon>
334
+ </InputGroup>
335
+ </FormField>
336
+ ```
337
+
338
+ ```tsx
339
+ // Contrôle de l'application dans un FormField
340
+ function ChampCode() {
341
+ const champ = useFormField()
342
+ return (
343
+ <input
344
+ id={champ?.id}
345
+ required={champ?.obligatoire}
346
+ aria-describedby={champ?.describedBy}
347
+ aria-invalid={champ?.invalide || undefined}
348
+ />
349
+ )
350
+ }
351
+ ```
352
+
353
+ ### Tableau de données
354
+
355
+ La famille `DataTable` suit le [guide Data Table de shadcn](https://ui.shadcn.com/docs/components/data-table)
356
+ sur [TanStack Table v9](https://tanstack.com/table/latest) : les colonnes se déclarent avec
357
+ l'assistant typé, `useDataTable` crée l'instance, les composants la reçoivent en `table`.
358
+
359
+ | Composant | Rôle |
360
+ | -------------------------- | -------------------------------------------------------------------------------------------- |
361
+ | `useDataTable` | instance TanStack : tri (client, ou serveur avec `triManuel`), colonnes, sélection, dépliage |
362
+ | `DataTable` | la Table de shadcn ; état vide, lignes fantômes du chargement, clic de ligne, détail déplié |
363
+ | `DataTableColumnHeader` | en-tête triable : un clic trie par ordre croissant, le suivant inverse le sens |
364
+ | `dataTableSelectionColumn` | colonne de cases ; Maj+clic sélectionne une plage ; raison d'une case verrouillée |
365
+ | `dataTableExpandColumn` | colonne du chevron qui déplie une ligne (`aria-expanded`, `aria-controls`) |
366
+ | `DataTableRowActions` | menu « … » d'une ligne |
367
+ | `DataTableViewOptions` | bouton « Colonnes » : afficher, masquer, réordonner (glisser-déposer, clavier compris) |
368
+ | `DataTableToolbar` | recherche, filtres (`DataTableSelectFilter`), compteur (`DataTableCount`), commandes |
369
+ | `DataTablePagination` | pagination par décalage (offset/limit, total connu), nombre de lignes par page |
370
+ | `DataTableBulkActions` | barre d'actions groupées, collante en bas, avec la sélection ; Échap désélectionne |
371
+
372
+ ```tsx
373
+ import { keepPreviousData, useQuery } from "@tanstack/react-query"
374
+ import {
375
+ DataTable,
376
+ DataTableColumnHeader,
377
+ DataTablePagination,
378
+ DataTableRowActions,
379
+ DataTableToolbar,
380
+ DataTableViewOptions,
381
+ createDataTableColumnHelper,
382
+ dataTableSelectionColumn,
383
+ useDataTable,
384
+ type SortingState,
385
+ } from "@etic-insa/ui"
386
+
387
+ const aide = createDataTableColumnHelper<Etude>()
388
+ // Hors du composant (ou mémorisées) : des colonnes recréées à chaque rendu recalculent tout.
389
+ const colonnes = aide.columns([
390
+ dataTableSelectionColumn<Etude>({
391
+ libelleLigne: (e) => `Sélectionner ${e.titre}`,
392
+ }),
393
+ aide.accessor("titre", {
394
+ header: ({ column }) => (
395
+ <DataTableColumnHeader column={column} libelle="Titre" />
396
+ ),
397
+ meta: { libelle: "Titre" }, // nom dans le sélecteur de colonnes et l'annonce du tri
398
+ }),
399
+ aide.display({
400
+ id: "actions",
401
+ enableHiding: false,
402
+ cell: ({ row }) => (
403
+ // Un nom propre à la ligne : sinon, une liste de boutons « Actions » indiscernables.
404
+ <DataTableRowActions libelle={`Actions pour ${row.original.titre}`}>
405
+ {/* DropdownMenuItem… */}
406
+ </DataTableRowActions>
407
+ ),
408
+ }),
409
+ ])
410
+
411
+ export function Etudes() {
412
+ const [tri, setTri] = useState<SortingState>([{ id: "titre", desc: false }])
413
+ const [decalage, setDecalage] = useState(0)
414
+ const [limite, setLimite] = useState(25)
415
+ const { data, isFetching } = useQuery({
416
+ queryKey: ["etudes", tri, decalage, limite], // le serveur trie et pagine
417
+ queryFn: () => api.etudes({ tri, decalage, limite }),
418
+ // Garde la page affichée pendant le chargement de la suivante : le compteur
419
+ // et la pagination ne retombent pas à 0, la hauteur ne saute pas.
420
+ placeholderData: keepPreviousData,
421
+ })
422
+ const table = useDataTable({
423
+ donnees: data?.items ?? AUCUNE, // référence stable, pas un nouveau [] à chaque rendu
424
+ colonnes,
425
+ idLigne: (e) => e.id,
426
+ tri,
427
+ onTriChange: setTri,
428
+ triManuel: true,
429
+ })
430
+ return (
431
+ <>
432
+ <DataTableToolbar
433
+ compteur={{
434
+ total: data?.total ?? 0,
435
+ decalage,
436
+ nombre: data?.items.length ?? 0,
437
+ }}
438
+ >
439
+ <DataTableViewOptions table={table} />
440
+ </DataTableToolbar>
441
+ <DataTable
442
+ table={table}
443
+ libelle="Études"
444
+ enChargement={isFetching}
445
+ lignesChargement={limite}
446
+ />
447
+ <DataTablePagination
448
+ total={data?.total ?? 0}
449
+ decalage={decalage}
450
+ limite={limite}
451
+ onDecalageChange={setDecalage}
452
+ onLimiteChange={setLimite}
453
+ />
454
+ </>
455
+ )
456
+ }
457
+ ```
458
+
459
+ Chaque partie de l'état (`tri`, `visibiliteColonnes`, `ordreColonnes`, `selection`,
460
+ `lignesDepliees`) est contrôlée si l'application la fournit avec son `on…Change` (pour la
461
+ garder, en `localStorage` par exemple), interne sinon ; `etatInitial` donne la valeur de départ
462
+ d'une partie interne. La sélection se limite par défaut aux lignes présentes dans `donnees`
463
+ (changer de page ou de filtre la réduit) ; `conserverSelection` la garde. Sur mobile, le tableau
464
+ garde ses colonnes et son cadre défile horizontalement. Une colonne se masque par « Colonnes »,
465
+ pas depuis son en-tête ; la dernière colonne de données affichée ne se masque pas.
466
+
467
+ `donnees` et `colonnes` doivent être des références stables. `idLigne` peut s'écrire en ligne :
468
+ il n'est relu que quand `donnees` change. Une ligne ne se redessine que si ses données, sa
469
+ sélection, son dépliage ou les colonnes changent (cocher une case ne redessine pas les 1 000
470
+ autres) : une cellule qui affiche un autre état le lit elle-même (hook, contexte).
471
+
472
+ Accessibilité : le tri choisi, le chargement et « tous sélectionnés » sont annoncés par le
473
+ tableau ; `DataTableCount` est une zone de statut (le nouveau compte après une recherche ou un
474
+ filtre est annoncé) ; `DataTablePagination` annonce la page atteinte. Quand un contrôle disparaît
475
+ sous le focus (« Réinitialiser », la croix de la recherche, le bandeau ou la barre de sélection),
476
+ le focus passe à un élément stable (champ de recherche, premier filtre, case d'en-tête). Le clic
477
+ de ligne (`onActiverLigne`) est un raccourci à la souris : une cellule doit aussi offrir un lien
478
+ ou un bouton pour le clavier. Un bouton passé dans `vide` (« Réinitialiser les filtres »)
479
+ disparaît avec l'état vide : l'application rend d'abord le focus au champ de recherche.
480
+
481
+ #### Sélectionner tous les éléments
482
+
483
+ La case d'en-tête (« Sélectionner la page ») coche les lignes de la page. Avec la pagination
484
+ côté serveur, le tableau ne connaît pas les identifiants des autres pages : pour tout
485
+ sélectionner, `useDataTable` reçoit `total` et un état `toutSelectionne` que l'application
486
+ interprète (en envoyant ses filtres au serveur au lieu d'une liste d'identifiants, par exemple).
487
+ Avec `ligneSelectionnable`, `total` ne compte que les éléments sélectionnables : c'est le nombre
488
+ annoncé et visé par l'action groupée (le tableau ne connaît pas les lignes des autres pages).
489
+
490
+ ```tsx
491
+ const [toutSelectionne, setToutSelectionne] = useState(false)
492
+ const table = useDataTable({
493
+ // …
494
+ total: data?.total,
495
+ toutSelectionne,
496
+ onToutSelectionneChange: setToutSelectionne,
497
+ })
498
+ // Filtres ou tri changés : la sélection ne vaut plus.
499
+ const changerFiltre = (valeur) => {
500
+ setFiltre(valeur)
501
+ setToutSelectionne(false)
502
+ }
503
+ // Action groupée
504
+ const supprimer = () =>
505
+ toutSelectionne
506
+ ? api.supprimerSelon(filtres)
507
+ : api.supprimer(table.getSelectedRowIds())
508
+ ```
509
+
510
+ Quand toute la page est cochée et que `total` compte d'autres éléments, `DataTable` affiche
511
+ au-dessus des lignes « Les 25 éléments de la page sont sélectionnés. Sélectionner les 137
512
+ éléments », puis « Les 137 éléments sont sélectionnés. Tout désélectionner » (`unite` et
513
+ `feminin` accordent le texte, comme pour `DataTableCount` et `DataTableBulkActions`).
514
+ `DataTableBulkActions` compte alors le total. L'état repasse à `false` dès qu'une ligne de la
515
+ page n'est plus cochée (par le tableau ou par l'application), quand la page change (même avec
516
+ `conserverSelection`) et par « Tout désélectionner »
517
+ (`table.options.meta.toutDeselectionner()` pour un bouton de l'application) ; l'application le
518
+ remet à `false` quand ses filtres ou le tri changent.
519
+
520
+ Une ligne non sélectionnable avec `verrouLigne` garde une case focalisable, en lecture seule, qui
521
+ dit sa raison (infobulle et description). Échap vide la sélection quand le focus est dans le
522
+ tableau ou dans la barre d'actions, pas ailleurs (navigation, dialogue, menu). Un tableau rendu à
523
+ la main avec les primitives `Table` et une instance `useDataTable` pose
524
+ `ref={table.options.meta.racine}` sur son conteneur pour en profiter.
525
+
526
+ #### Lignes dépliables
527
+
528
+ Sur le modèle de TanStack (`rowExpandingFeature`) et des exemples shadcn : `dataTableExpandColumn`
529
+ ajoute le chevron (bouton à icône seule, infobulle, `aria-expanded`, `aria-controls`), et
530
+ `rendreDetail` de `DataTable` rend le détail sous la ligne, sur toute la largeur. Sans
531
+ `onActiverLigne`, un clic sur la ligne la déplie aussi ; la sélection et les commandes de la
532
+ ligne restent indépendantes. Sur mobile, le détail suit la largeur visible du cadre : il reste
533
+ lisible pendant que les colonnes défilent.
534
+
535
+ ```tsx
536
+ const colonnes = aide.columns([
537
+ dataTableExpandColumn<Evenement>({
538
+ libelleLigne: (e) => `Détail de « ${e.action} » du ${e.date}`,
539
+ }),
540
+ aide.accessor("action", { header: "Action" }),
541
+ // …
542
+ ])
543
+
544
+ const table = useDataTable({
545
+ donnees,
546
+ colonnes,
547
+ idLigne: (e) => e.id,
548
+ ligneDepliable: (e) => e.avant !== null, // pas de chevron sans détail
549
+ uneSeuleLigneDepliee: true, // déplier une ligne replie l'autre
550
+ })
551
+ <DataTable
552
+ table={table}
553
+ libelle="Journal"
554
+ rendreDetail={(e) => <DetailEvenement evenement={e} />}
555
+ />
556
+ ```
557
+
558
+ Une requête rechargée ne referme pas le détail ouvert ; une ligne qui disparaît des données est
559
+ retirée des lignes dépliées.
560
+
561
+ #### Pagination
562
+
563
+ `DataTablePagination` ramène sur la dernière page un `decalage` passé au-delà de la fin
564
+ (dernière ligne de la dernière page supprimée), par `onDecalageChange`, mais seulement une fois
565
+ le total connu (`total > 0`) : un total à 0 pendant un chargement ne renvoie pas à la première
566
+ page. Avec TanStack Query, `placeholderData: keepPreviousData` garde la page précédente (et son
567
+ total) pendant le chargement de la suivante. « Précédente » et « Suivante » restent focalisables
568
+ en bout de liste.
569
+
79
570
  ### Développer contre les sources locales
80
571
 
81
572
  Pour voir une modification de la bibliothèque instantanément dans une application, sans publier,
@@ -112,7 +603,7 @@ d'`etic-packages` installe tous les paquets.
112
603
 
113
604
  ```sh
114
605
  # depuis packages/ui
115
- npm run dev # atelier : tous les composants, touche « d » pour le thème sombre
606
+ npm run dev # atelier : tous les composants, thème au pied de la barre latérale
116
607
  npm test # vitest
117
608
  npm run typecheck
118
609
  npm run lint
@@ -122,9 +613,58 @@ npm run build # dist/ : un module par composant, types, styles.css
122
613
 
123
614
  ### Organisation
124
615
 
125
- - `src/components/ui/` : composants shadcn **intacts**, tels que le CLI les installe
126
- (`npx shadcn add <composant>`). On n'y modifie rien, pour que
127
- `npx shadcn add <composant> --diff` puis `--overwrite` suivent shadcn sans rien perdre.
616
+ - `src/components/ui/` et `src/hooks/` : composants shadcn, copiés par le CLI
617
+ (`npx shadcn add <composant>`). Ce code est le nôtre et se modifie comme le reste. Chaque
618
+ modification est listée ci-dessous, pour pouvoir la réappliquer si l'on reprend un jour la
619
+ version de shadcn (`npx shadcn add <composant> --diff`, puis `--overwrite`) ;
620
+ `src/ecarts-shadcn.test.ts` échoue si elle a disparu :
621
+ - seuil mobile à 1 024 px compris au lieu de 768 px : `hooks/use-mobile.ts` (réécrit avec
622
+ `useSyncExternalStore`, juste dès le premier rendu) et les variantes `md:` de
623
+ `components/ui/sidebar.tsx`, devenues `min-[1025px]:` ;
624
+ - textes en français, visibles ou lus par les lecteurs d'écran : `sidebar.tsx` (« Menu »,
625
+ « Navigation de l'application. », « Afficher ou masquer le menu »), `sheet.tsx` et `dialog.tsx` (« Fermer »),
626
+ `pagination.tsx` (« Pagination », « Précédente », « Suivante », « Page précédente »,
627
+ « Page suivante », « Autres pages »), `breadcrumb.tsx` (« Fil d’Ariane »,
628
+ « Niveaux masqués »), `spinner.tsx` (« Chargement »), `combobox.tsx` (« Effacer » et
629
+ « Retirer », libellés ajoutés aux boutons à icône seule) ;
630
+ - calendrier en français : `calendar.tsx` prend par défaut la locale `fr` de
631
+ react-day-picker (mois, jours et libellés d'accessibilité) et `weekStartsOn={1}` ;
632
+ - jours du calendrier de 36 px sous le seuil mobile (cible tactile), 28 px au-delà comme
633
+ dans shadcn : `--cell-size` de `calendar.tsx` ;
634
+ - thème (`styles.css`) : `--muted-foreground` plus foncé en clair (≥ 4,5:1 sur `--muted` :
635
+ initiales d'`Avatar`, `Kbd`), `--destructive` plus foncé en clair et plus clair en sombre
636
+ (≥ 4,5:1 sur sa teinte : bouton et badge `destructive`, y compris dans un pied de
637
+ dialogue) ; contrastes vérifiés par `src/theme.test.ts` ;
638
+ - l'accent comme texte en `text-primary-text` au lieu de `text-primary` : variante `link` de
639
+ `button.tsx` et `badge.tsx`, liens survolés de `empty.tsx`, `field.tsx` et `item.tsx` ;
640
+ - import inutilisé de React retiré de `scroll-area.tsx` (sans quoi `tsc` échoue) ;
641
+ - variantes `success` et `warning` ajoutées à `badge.tsx`, sur le modèle de `destructive`
642
+ (teinte à 10 %, 20 % en sombre, texte de la couleur) ;
643
+ - case à cocher partielle (`indeterminate`) : `checkbox.tsx` affiche un trait sur fond plein,
644
+ comme une case cochée, au lieu de la coche sur fond vide de shadcn (on croyait tout coché) ;
645
+ - variantes `warning`, `info` et `success` ajoutées à `alert.tsx`, sur le modèle de
646
+ `destructive` (fond de carte, texte de la couleur, description à 90 %), et couleur `--info`
647
+ dans `styles.css` ;
648
+ - Ctrl+B (repli de la barre latérale) ignoré quand le focus est dans un champ de saisie
649
+ (`input`, `textarea`, `select`, `contenteditable`) : `sidebar.tsx`, pour ne pas voler le
650
+ gras d'un éditeur riche ;
651
+ - anneau de focus (`focus-visible:ring-3 ring-ring/50`) sur le panneau de `tabs.tsx`, arrêt
652
+ de tabulation qui n'en avait pas ;
653
+ - `slider.tsx` : une valeur simple (un nombre) dessine un seul curseur, au lieu de deux ;
654
+ anneau de focus clavier `has-focus-visible:ring-3` sur le curseur (le focus va à l'input
655
+ range caché qu'il contient) ; `aria-label` du slider relayé aux curseurs ; une plage
656
+ annonce « 20 (minimum) », « 80 (maximum) » au lieu de « start/end range » ;
657
+ - déclencheurs de `select.tsx` et `native-select.tsx` en `text-base md:text-sm`, comme
658
+ `Input` (en 14 px sur téléphone, iOS zoome à la sélection) ;
659
+ - bouton qui ouvre la liste de `combobox.tsx` nommé « Afficher les options » ;
660
+ - `alert.tsx` : `role="status"` pour `info` et `success` (messages d'état, annoncés sans
661
+ interrompre), `role="alert"` gardé pour les autres variantes.
662
+
663
+ Le thème ajoute aussi (`styles.css`, hors composants shadcn) la règle de mouvement réduit.
664
+
665
+ Sans écart de code mais garanti par le même test : `Button` sans `type` rend
666
+ `type="button"` (Base UI le fait pour un bouton natif) et ne soumet donc pas son formulaire.
667
+
128
668
  - `src/components/etic/` : composants ETIC qui importent ceux de `ui/` et ajoutent
129
669
  comportement, composition ou variantes.
130
670
  - `src/index.ts` : tout ce qu'une application peut importer. Un composant non exporté ici
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Action d'un dialogue : synchrone, ou une promesse que le dialogue attend.
3
+ * Renvoyer `false` (ou une promesse résolue à `false`) garde le dialogue
4
+ * ouvert, sans erreur : la page change sa question (« Supprimer quand
5
+ * même ? ») ou signale elle-même ce qui manque.
6
+ */
7
+ export type ActionDialogue = () => unknown;
8
+ /**
9
+ * État d'une action lancée depuis un dialogue. `lancer` appelle l'action :
10
+ * si elle renvoie une promesse, `enCours` vaut vrai jusqu'à son issue. Puis
11
+ * `succes` est appelé, sauf si l'action a renvoyé `false` ; en cas d'échec,
12
+ * `erreur` reçoit la raison. Une action synchrone qui lève une exception
13
+ * échoue de même.
14
+ */
15
+ export declare function useAction(): {
16
+ enCours: boolean;
17
+ erreur: unknown;
18
+ lancer: (action: ActionDialogue, succes: () => void) => Promise<void>;
19
+ reinitialiser: () => void;
20
+ };
21
+ /**
22
+ * Ouverture d'un dialogue, contrôlée (`ouvert`, `onOuvertChange`) ou
23
+ * interne. Pendant l'action, toute demande de fermeture (Échap, Annuler,
24
+ * croix, clic sur le voile) est ignorée.
25
+ */
26
+ export declare function useOuvertureDialogue(ouvert: boolean | undefined, onOuvertChange: ((ouvert: boolean) => void) | undefined, enCours: boolean): {
27
+ ouvert: boolean;
28
+ definir: (suivant: boolean) => void;
29
+ changer: (suivant: boolean) => void;
30
+ };
31
+ /** Roue dans un bouton occupé, muette : le bouton garde son nom et porte
32
+ * `aria-busy`. */
33
+ export declare function SpinnerBouton(): import("react").JSX.Element;