@etic-insa/ui 0.1.0 → 0.3.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 (300) hide show
  1. package/README.md +897 -12
  2. package/dist/components/etic/action.d.ts +42 -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 +23 -11
  6. package/dist/components/etic/app-shell.js +133 -88
  7. package/dist/components/etic/app-shell.js.map +1 -1
  8. package/dist/components/etic/auth-image.d.ts +71 -0
  9. package/dist/components/etic/auth-image.js +67 -0
  10. package/dist/components/etic/auth-image.js.map +1 -0
  11. package/dist/components/etic/button-link.d.ts +19 -0
  12. package/dist/components/etic/button-link.js +19 -0
  13. package/dist/components/etic/button-link.js.map +1 -0
  14. package/dist/components/etic/centered-screen.d.ts +13 -0
  15. package/dist/components/etic/centered-screen.js +13 -0
  16. package/dist/components/etic/centered-screen.js.map +1 -0
  17. package/dist/components/etic/checkbox-list.d.ts +30 -0
  18. package/dist/components/etic/checkbox-list.js +56 -0
  19. package/dist/components/etic/checkbox-list.js.map +1 -0
  20. package/dist/components/etic/confirm-dialog.d.ts +93 -0
  21. package/dist/components/etic/confirm-dialog.js +109 -0
  22. package/dist/components/etic/confirm-dialog.js.map +1 -0
  23. package/dist/components/etic/copy-button.d.ts +25 -0
  24. package/dist/components/etic/copy-button.js +46 -0
  25. package/dist/components/etic/copy-button.js.map +1 -0
  26. package/dist/components/etic/data-table-bulk-actions.d.ts +53 -0
  27. package/dist/components/etic/data-table-bulk-actions.js +104 -0
  28. package/dist/components/etic/data-table-bulk-actions.js.map +1 -0
  29. package/dist/components/etic/data-table-focus.d.ts +17 -0
  30. package/dist/components/etic/data-table-focus.js +29 -0
  31. package/dist/components/etic/data-table-focus.js.map +1 -0
  32. package/dist/components/etic/data-table-format.d.ts +5 -0
  33. package/dist/components/etic/data-table-format.js +9 -0
  34. package/dist/components/etic/data-table-format.js.map +1 -0
  35. package/dist/components/etic/data-table-pagination.d.ts +36 -0
  36. package/dist/components/etic/data-table-pagination.js +134 -0
  37. package/dist/components/etic/data-table-pagination.js.map +1 -0
  38. package/dist/components/etic/data-table-toolbar.d.ts +90 -0
  39. package/dist/components/etic/data-table-toolbar.js +131 -0
  40. package/dist/components/etic/data-table-toolbar.js.map +1 -0
  41. package/dist/components/etic/data-table-view-options.d.ts +56 -0
  42. package/dist/components/etic/data-table-view-options.js +198 -0
  43. package/dist/components/etic/data-table-view-options.js.map +1 -0
  44. package/dist/components/etic/data-table.d.ts +421 -0
  45. package/dist/components/etic/data-table.js +582 -0
  46. package/dist/components/etic/data-table.js.map +1 -0
  47. package/dist/components/etic/date-picker.d.ts +36 -0
  48. package/dist/components/etic/date-picker.js +175 -0
  49. package/dist/components/etic/date-picker.js.map +1 -0
  50. package/dist/components/etic/delete-button.d.ts +65 -0
  51. package/dist/components/etic/delete-button.js +37 -0
  52. package/dist/components/etic/delete-button.js.map +1 -0
  53. package/dist/components/etic/detail-list.d.ts +26 -0
  54. package/dist/components/etic/detail-list.js +46 -0
  55. package/dist/components/etic/detail-list.js.map +1 -0
  56. package/dist/components/etic/disclosure.d.ts +52 -0
  57. package/dist/components/etic/disclosure.js +70 -0
  58. package/dist/components/etic/disclosure.js.map +1 -0
  59. package/dist/components/etic/draft-resume-dialog.d.ts +42 -0
  60. package/dist/components/etic/draft-resume-dialog.js +60 -0
  61. package/dist/components/etic/draft-resume-dialog.js.map +1 -0
  62. package/dist/components/etic/empty-state.d.ts +20 -0
  63. package/dist/components/etic/empty-state.js +20 -0
  64. package/dist/components/etic/empty-state.js.map +1 -0
  65. package/dist/components/etic/error-banner.d.ts +50 -0
  66. package/dist/components/etic/error-banner.js +85 -0
  67. package/dist/components/etic/error-banner.js.map +1 -0
  68. package/dist/components/etic/error-boundary.d.ts +53 -0
  69. package/dist/components/etic/error-boundary.js +83 -0
  70. package/dist/components/etic/error-boundary.js.map +1 -0
  71. package/dist/components/etic/explained-badge.d.ts +26 -0
  72. package/dist/components/etic/explained-badge.js +17 -0
  73. package/dist/components/etic/explained-badge.js.map +1 -0
  74. package/dist/components/etic/file-upload.d.ts +52 -0
  75. package/dist/components/etic/file-upload.js +137 -0
  76. package/dist/components/etic/file-upload.js.map +1 -0
  77. package/dist/components/etic/form-dialog.d.ts +68 -0
  78. package/dist/components/etic/form-dialog.js +154 -0
  79. package/dist/components/etic/form-dialog.js.map +1 -0
  80. package/dist/components/etic/form-field-context.d.ts +66 -0
  81. package/dist/components/etic/form-field-context.js +28 -0
  82. package/dist/components/etic/form-field-context.js.map +1 -0
  83. package/dist/components/etic/form-field.d.ts +53 -0
  84. package/dist/components/etic/form-field.js +105 -0
  85. package/dist/components/etic/form-field.js.map +1 -0
  86. package/dist/components/etic/icon-toggle.d.ts +51 -0
  87. package/dist/components/etic/icon-toggle.js +40 -0
  88. package/dist/components/etic/icon-toggle.js.map +1 -0
  89. package/dist/components/etic/lien.d.ts +34 -0
  90. package/dist/components/etic/lien.js +17 -0
  91. package/dist/components/etic/lien.js.map +1 -0
  92. package/dist/components/etic/loading.d.ts +37 -0
  93. package/dist/components/etic/loading.js +74 -0
  94. package/dist/components/etic/loading.js.map +1 -0
  95. package/dist/components/etic/page-container.d.ts +27 -0
  96. package/dist/components/etic/page-container.js +24 -0
  97. package/dist/components/etic/page-container.js.map +1 -0
  98. package/dist/components/etic/page-header.d.ts +64 -0
  99. package/dist/components/etic/page-header.js +109 -0
  100. package/dist/components/etic/page-header.js.map +1 -0
  101. package/dist/components/etic/phone-input.d.ts +47 -0
  102. package/dist/components/etic/phone-input.js +139 -0
  103. package/dist/components/etic/phone-input.js.map +1 -0
  104. package/dist/components/etic/query-boundary.d.ts +73 -0
  105. package/dist/components/etic/query-boundary.js +37 -0
  106. package/dist/components/etic/query-boundary.js.map +1 -0
  107. package/dist/components/etic/removable-badge.d.ts +30 -0
  108. package/dist/components/etic/removable-badge.js +31 -0
  109. package/dist/components/etic/removable-badge.js.map +1 -0
  110. package/dist/components/etic/save-bar.d.ts +31 -0
  111. package/dist/components/etic/save-bar.js +45 -0
  112. package/dist/components/etic/save-bar.js.map +1 -0
  113. package/dist/components/etic/search-select.d.ts +41 -0
  114. package/dist/components/etic/search-select.js +126 -0
  115. package/dist/components/etic/search-select.js.map +1 -0
  116. package/dist/components/etic/section-card.d.ts +12 -0
  117. package/dist/components/etic/section-card.js +23 -0
  118. package/dist/components/etic/section-card.js.map +1 -0
  119. package/dist/components/etic/segmented-control.d.ts +33 -0
  120. package/dist/components/etic/segmented-control.js +45 -0
  121. package/dist/components/etic/segmented-control.js.map +1 -0
  122. package/dist/components/etic/stat-grid.d.ts +15 -0
  123. package/dist/components/etic/stat-grid.js +17 -0
  124. package/dist/components/etic/stat-grid.js.map +1 -0
  125. package/dist/components/etic/stat-tile.d.ts +18 -0
  126. package/dist/components/etic/stat-tile.js +33 -0
  127. package/dist/components/etic/stat-tile.js.map +1 -0
  128. package/dist/components/etic/status-badge.d.ts +14 -0
  129. package/dist/components/etic/status-badge.js +20 -0
  130. package/dist/components/etic/status-badge.js.map +1 -0
  131. package/dist/components/etic/tailles-dialogue.d.ts +8 -0
  132. package/dist/components/etic/tailles-dialogue.js +10 -0
  133. package/dist/components/etic/tailles-dialogue.js.map +1 -0
  134. package/dist/components/etic/theme-menu.d.ts +6 -5
  135. package/dist/components/etic/theme-menu.js +46 -36
  136. package/dist/components/etic/theme-menu.js.map +1 -1
  137. package/dist/components/etic/toggletip.d.ts +36 -0
  138. package/dist/components/etic/toggletip.js +59 -0
  139. package/dist/components/etic/toggletip.js.map +1 -0
  140. package/dist/components/etic/tooltip-button.d.ts +39 -0
  141. package/dist/components/etic/tooltip-button.js +39 -0
  142. package/dist/components/etic/tooltip-button.js.map +1 -0
  143. package/dist/components/etic/unsaved-changes.d.ts +41 -0
  144. package/dist/components/etic/unsaved-changes.js +17 -0
  145. package/dist/components/etic/unsaved-changes.js.map +1 -0
  146. package/dist/components/etic/use-draft-autosave.d.ts +70 -0
  147. package/dist/components/etic/use-draft-autosave.js +98 -0
  148. package/dist/components/etic/use-draft-autosave.js.map +1 -0
  149. package/dist/components/etic/use-unsaved-changes-warning.d.ts +10 -0
  150. package/dist/components/etic/use-unsaved-changes-warning.js +20 -0
  151. package/dist/components/etic/use-unsaved-changes-warning.js.map +1 -0
  152. package/dist/components/ui/alert-dialog.js +33 -33
  153. package/dist/components/ui/alert-dialog.js.map +1 -1
  154. package/dist/components/ui/alert.d.ts +10 -0
  155. package/dist/components/ui/alert.js +47 -0
  156. package/dist/components/ui/alert.js.map +1 -0
  157. package/dist/components/ui/avatar.d.ts +5 -1
  158. package/dist/components/ui/avatar.js +20 -11
  159. package/dist/components/ui/avatar.js.map +1 -1
  160. package/dist/components/ui/badge.d.ts +8 -0
  161. package/dist/components/ui/badge.js +45 -0
  162. package/dist/components/ui/badge.js.map +1 -0
  163. package/dist/components/ui/breadcrumb.d.ts +10 -0
  164. package/dist/components/ui/breadcrumb.js +73 -0
  165. package/dist/components/ui/breadcrumb.js.map +1 -0
  166. package/dist/components/ui/button-group.d.ts +10 -0
  167. package/dist/components/ui/button-group.js +42 -0
  168. package/dist/components/ui/button-group.js.map +1 -0
  169. package/dist/components/ui/button.d.ts +16 -3
  170. package/dist/components/ui/button.js +28 -16
  171. package/dist/components/ui/button.js.map +1 -1
  172. package/dist/components/ui/calendar.d.ts +10 -0
  173. package/dist/components/ui/calendar.js +96 -0
  174. package/dist/components/ui/calendar.js.map +1 -0
  175. package/dist/components/ui/card.d.ts +11 -0
  176. package/dist/components/ui/card.js +57 -0
  177. package/dist/components/ui/card.js.map +1 -0
  178. package/dist/components/ui/checkbox.d.ts +3 -0
  179. package/dist/components/ui/checkbox.js +20 -0
  180. package/dist/components/ui/checkbox.js.map +1 -0
  181. package/dist/components/ui/collapsible.d.ts +5 -0
  182. package/dist/components/ui/collapsible.js +25 -0
  183. package/dist/components/ui/collapsible.js.map +1 -0
  184. package/dist/components/ui/combobox.d.ts +24 -0
  185. package/dist/components/ui/combobox.js +178 -0
  186. package/dist/components/ui/combobox.js.map +1 -0
  187. package/dist/components/ui/dialog.d.ts +26 -0
  188. package/dist/components/ui/dialog.js +99 -0
  189. package/dist/components/ui/dialog.js.map +1 -0
  190. package/dist/components/ui/dropdown-menu.js +36 -36
  191. package/dist/components/ui/empty.d.ts +11 -0
  192. package/dist/components/ui/empty.js +60 -0
  193. package/dist/components/ui/empty.js.map +1 -0
  194. package/dist/components/ui/field.d.ts +24 -0
  195. package/dist/components/ui/field.js +108 -0
  196. package/dist/components/ui/field.js.map +1 -0
  197. package/dist/components/ui/input-group.d.ts +18 -0
  198. package/dist/components/ui/input-group.js +79 -0
  199. package/dist/components/ui/input-group.js.map +1 -0
  200. package/dist/components/ui/item.d.ts +22 -0
  201. package/dist/components/ui/item.js +122 -0
  202. package/dist/components/ui/item.js.map +1 -0
  203. package/dist/components/ui/kbd.d.ts +3 -0
  204. package/dist/components/ui/kbd.js +20 -0
  205. package/dist/components/ui/kbd.js.map +1 -0
  206. package/dist/components/ui/label.d.ts +3 -0
  207. package/dist/components/ui/label.js +14 -0
  208. package/dist/components/ui/label.js.map +1 -0
  209. package/dist/components/ui/native-select.d.ts +8 -0
  210. package/dist/components/ui/native-select.js +39 -0
  211. package/dist/components/ui/native-select.js.map +1 -0
  212. package/dist/components/ui/pagination.d.ts +17 -0
  213. package/dist/components/ui/pagination.js +81 -0
  214. package/dist/components/ui/pagination.js.map +1 -0
  215. package/dist/components/ui/popover.d.ts +9 -0
  216. package/dist/components/ui/popover.js +56 -0
  217. package/dist/components/ui/popover.js.map +1 -0
  218. package/dist/components/ui/progress.d.ts +21 -0
  219. package/dist/components/ui/progress.js +53 -0
  220. package/dist/components/ui/progress.js.map +1 -0
  221. package/dist/components/ui/radio-group.d.ts +5 -0
  222. package/dist/components/ui/radio-group.js +27 -0
  223. package/dist/components/ui/radio-group.js.map +1 -0
  224. package/dist/components/ui/scroll-area.d.ts +4 -0
  225. package/dist/components/ui/scroll-area.js +36 -0
  226. package/dist/components/ui/scroll-area.js.map +1 -0
  227. package/dist/components/ui/select.d.ts +23 -0
  228. package/dist/components/ui/select.js +119 -0
  229. package/dist/components/ui/select.js.map +1 -0
  230. package/dist/components/ui/sidebar.d.ts +6 -1
  231. package/dist/components/ui/sidebar.js +92 -92
  232. package/dist/components/ui/sidebar.js.map +1 -1
  233. package/dist/components/ui/slider.d.ts +3 -0
  234. package/dist/components/ui/slider.js +36 -0
  235. package/dist/components/ui/slider.js.map +1 -0
  236. package/dist/components/ui/spinner.d.ts +8 -0
  237. package/dist/components/ui/spinner.js +24 -0
  238. package/dist/components/ui/spinner.js.map +1 -0
  239. package/dist/components/ui/switch.d.ts +5 -0
  240. package/dist/components/ui/switch.js +20 -0
  241. package/dist/components/ui/switch.js.map +1 -0
  242. package/dist/components/ui/table.d.ts +10 -0
  243. package/dist/components/ui/table.js +67 -0
  244. package/dist/components/ui/table.js.map +1 -0
  245. package/dist/components/ui/tabs.d.ts +10 -0
  246. package/dist/components/ui/tabs.js +46 -0
  247. package/dist/components/ui/tabs.js.map +1 -0
  248. package/dist/components/ui/textarea.d.ts +3 -0
  249. package/dist/components/ui/textarea.js +14 -0
  250. package/dist/components/ui/textarea.js.map +1 -0
  251. package/dist/components/ui/toggle-group.d.ts +11 -0
  252. package/dist/components/ui/toggle-group.js +54 -0
  253. package/dist/components/ui/toggle-group.js.map +1 -0
  254. package/dist/components/ui/toggle.d.ts +8 -0
  255. package/dist/components/ui/toggle.js +36 -0
  256. package/dist/components/ui/toggle.js.map +1 -0
  257. package/dist/components/ui/tooltip.d.ts +7 -2
  258. package/dist/components/ui/tooltip.js +27 -19
  259. package/dist/components/ui/tooltip.js.map +1 -1
  260. package/dist/hooks/use-column-prefs.d.ts +84 -0
  261. package/dist/hooks/use-column-prefs.js +71 -0
  262. package/dist/hooks/use-column-prefs.js.map +1 -0
  263. package/dist/hooks/use-debounced-value.d.ts +13 -0
  264. package/dist/hooks/use-debounced-value.js +12 -0
  265. package/dist/hooks/use-debounced-value.js.map +1 -0
  266. package/dist/hooks/use-document-title.d.ts +5 -0
  267. package/dist/hooks/use-document-title.js +13 -0
  268. package/dist/hooks/use-document-title.js.map +1 -0
  269. package/dist/hooks/use-persisted-state.d.ts +43 -0
  270. package/dist/hooks/use-persisted-state.js +40 -0
  271. package/dist/hooks/use-persisted-state.js.map +1 -0
  272. package/dist/index.d.ts +91 -1
  273. package/dist/index.js +99 -13
  274. package/dist/lib/autofill.d.ts +18 -0
  275. package/dist/lib/autofill.js +10 -0
  276. package/dist/lib/autofill.js.map +1 -0
  277. package/dist/lib/dates.d.ts +20 -0
  278. package/dist/lib/dates.js +16 -0
  279. package/dist/lib/dates.js.map +1 -0
  280. package/dist/lib/focus-rendu.d.ts +24 -0
  281. package/dist/lib/focus-rendu.js +14 -0
  282. package/dist/lib/focus-rendu.js.map +1 -0
  283. package/dist/lib/format.d.ts +54 -0
  284. package/dist/lib/format.js +80 -0
  285. package/dist/lib/format.js.map +1 -0
  286. package/dist/lib/normalize.d.ts +28 -0
  287. package/dist/lib/normalize.js +21 -0
  288. package/dist/lib/normalize.js.map +1 -0
  289. package/dist/lib/ordre-colonnes.d.ts +15 -0
  290. package/dist/lib/ordre-colonnes.js +14 -0
  291. package/dist/lib/ordre-colonnes.js.map +1 -0
  292. package/dist/lib/ton.d.ts +23 -0
  293. package/dist/lib/ton.js +51 -0
  294. package/dist/lib/ton.js.map +1 -0
  295. package/dist/styles.css +140 -58
  296. package/dist/theme.d.ts +34 -0
  297. package/dist/theme.js +45 -0
  298. package/dist/theme.js.map +1 -0
  299. package/package.json +21 -8
  300. package/src/theme-boot.js +22 -0
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,13 +61,67 @@ 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) : à corriger, dans le composant ou dans une enveloppe ETIC. **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
 
70
+ Les neutres (fonds, panneaux, bordures, textes) sont ceux de la couleur de base `gray` de
71
+ shadcn (palette `gray` de Tailwind 4, légèrement bleutée), communs à toute la suite : une
72
+ application ne les redéfinit pas. `--muted-foreground` est un peu plus foncé en clair
73
+ (≥ 4,5:1 sur `--muted`), écart vérifié avec les contrastes par `src/theme.test.ts`.
74
+
75
+ Le fond de la page elle-même est un jeton ajouté, `--page` (classe `bg-page`) : gray-50 en
76
+ clair, si bien que cartes, menus et tableaux blancs s'en détachent (en sombre, il vaut
77
+ `--background` et les cartes sont déjà plus claires). Le `body` et le contenu d'`AppShell`
78
+ le prennent ; un conteneur pleine page d'une application aussi, plutôt que `bg-background`,
79
+ qui reste la surface blanche de shadcn (onglet actif, bouton `outline`, calendrier…).
80
+ `color-scheme` suit le thème (`light`, `dark`) : barres de défilement et contrôles natifs
81
+ compris.
82
+
83
+ #### Thème clair, sombre ou système
84
+
85
+ `appliquerTheme(theme)` pose la classe `dark` sur `<html>` pour `"dark"`, la retire pour
86
+ `"light"` et, pour `"system"`, suit `prefers-color-scheme`, y compris quand le système change.
87
+ La préférence vient du compte (`theme` de `@etic-insa/auth`) ; `useThemeApplique` la peint,
88
+ la mémorise dans ce navigateur (`localStorage`, clé `"etic-theme"`) et suit un changement
89
+ fait dans un autre onglet. Une valeur `null` ou inconnue vaut `"system"`. Le rappel est
90
+ obligatoire : sans lui, l'état de l'application garderait l'ancien thème et le rechoisir ne
91
+ changerait rien.
92
+
93
+ ```tsx
94
+ import { useThemeApplique } from "@etic-insa/ui"
95
+
96
+ // Une fois, près de la racine : thème du compte, undefined tant qu'il n'est pas chargé.
97
+ useThemeApplique(me?.preferences?.theme, (theme) => {
98
+ /* autre onglet : aligner l'état local sans rappeler le serveur */
99
+ })
100
+ ```
101
+
102
+ Hors de React (atelier, page sans compte), `appliquerTheme` seul : il ne mémorise rien.
103
+
104
+ Pour que la première image soit déjà dans le bon thème, avant le chargement du compte,
105
+ l'application charge le script de démarrage du paquet dans `<head>`, avant le bundle, sans
106
+ `type="module"`, depuis sa propre origine (une CSP `script-src 'self'` l'admet) :
107
+
108
+ ```html
109
+ <script src="/theme-boot.js"></script>
110
+ ```
111
+
112
+ Vite ne regroupe pas un script classique : le copier dans `public/` avant `dev` et `build`
113
+ (copie ignorée dans git) :
114
+
115
+ ```json
116
+ "scripts": {
117
+ "theme-boot": "node -e \"const fs = require('fs'); fs.mkdirSync('public', { recursive: true }); fs.copyFileSync(require.resolve('@etic-insa/ui/theme-boot.js'), 'public/theme-boot.js')\"",
118
+ "predev": "npm run theme-boot",
119
+ "prebuild": "npm run theme-boot"
120
+ }
121
+ ```
122
+
123
+ Il relit le thème mémorisé ; sans thème mémorisé, il suit le système.
124
+
67
125
  ```tsx
68
126
  import { Button } from "@etic-insa/ui"
69
127
 
@@ -111,19 +169,709 @@ export function MiseEnPage() {
111
169
  ],
112
170
  },
113
171
  ]}
114
- compte={{ nom: "Ada Lovelace", initiales: "AL", seDeconnecter }}
115
- theme={{ valeur: theme, changer: changerTheme }}
172
+ compte={{ nom: "Ada Lovelace", initiales: "AL", onSeDeconnecter }}
173
+ theme={{ valeur: theme, onValeurChange: changerTheme }}
116
174
  lien={LienRouteur}
117
175
  >
118
176
  <Outlet />
119
177
  </AppShell>
120
178
  )
121
179
  }
180
+
181
+ // Dans chaque page
182
+ export function Groupes() {
183
+ return (
184
+ <PageContainer>
185
+ <PageHeader titre="Groupes" />
186
+ <SectionCard titre="Liste">…</SectionCard>
187
+ </PageContainer>
188
+ )
189
+ }
190
+ ```
191
+
192
+ `onValeurChange` peut renvoyer une promesse : rejetée, elle affiche « Thème non enregistré »
193
+ quelques secondes. La déconnexion (`onSeDeconnecter`) est toujours confirmée ; une entrée du
194
+ menu du compte est un lien (`href`) ou une action (`onChoisir`). La coquille fournit l'élément
195
+ `<main>` : les pages n'en ajoutent pas. Elle ouvre la tabulation par un lien « Aller au
196
+ contenu », visible au focus, qui met le focus sur ce `<main>`. Sur ordinateur, un bouton de
197
+ l'en-tête replie la colonne (Ctrl+B aussi, sauf dans un champ de saisie, où il reste au
198
+ gras d'un éditeur). Sur mobile, la page réserve en haut la hauteur de la barre collante
199
+ (`scroll-padding-top`) : une ancre ne s'arrête pas dessous. `ThemeMenu` existe aussi seul
200
+ (page de connexion…) ; son `className` va sur le bouton.
201
+
202
+ Le composant de lien du routeur se donne une fois, autour de l'application :
203
+ `<LienProvider lien={LienRouteur}>`, où `LienRouteur` est une référence stable, définie
204
+ au niveau du module (un composant écrit en ligne serait nouveau à chaque rendu, et React
205
+ remonterait tous les liens). `AppShell`, `DetailHeader`, `ButtonLink` et
206
+ `DataTableCellLink` le prennent alors par défaut, sans `lien={…}` à chaque appel ; leur
207
+ prop `lien` reste prioritaire. Téléchargement ou adresse externe : `lien="a"` (un vrai
208
+ `<a>`, rechargement complet). Sans fournisseur ni prop, un `<a>`. `useLien(lien?)` rend le
209
+ même choix aux liens propres de l'application (`const Lien = useLien()`) ; le type
210
+ `LienComposant` le décrit (`AppShellLienComposant`, son ancien nom, est déprécié).
211
+
212
+ `bandeau` (un `ErrorBanner` qui concerne toute l'application…) s'affiche au-dessus du
213
+ contenu avec les marges latérales de `PageContainer` : l'application le passe nu. Un bandeau
214
+ qui ne rend rien (`ErrorBanner` sans erreur) ne laisse pas d'espace vide. Il prend toute la
215
+ largeur du contenu, car la coquille ignore la `largeur` de la page : sur grand écran, il
216
+ déborde d'une page étroite (`largeur="md"`). Il sert donc aux messages de toute
217
+ l'application ; un message propre à une page se place dans son `PageContainer`.
218
+
219
+ `PageContainer` est le conteneur de chaque page dans `AppShell` : marges (16 px sur
220
+ téléphone, 24 puis 32 px au-delà), espacement vertical régulier entre les blocs (`gap-6`),
221
+ et `largeur` maximale centrée (`md`, `lg`, `xl`, ou `full` par défaut). Les pages ne posent
222
+ pas leurs propres marges.
223
+
224
+ ### Retours et mise en page
225
+
226
+ Compositions des primitives shadcn pour les états d'une page et les actions courantes. Elles ne
227
+ connaissent ni l'API ni le routeur : l'application fournit ses fonctions (envoi, suppression,
228
+ chargement d'une image) et, au besoin, son composant de lien (`lien`, comme pour `AppShell`).
229
+
230
+ | Composant | Rôle |
231
+ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
232
+ | `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. |
233
+ | `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. |
234
+ | `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. |
235
+ | `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). |
236
+ | `PageContainer` | Conteneur de page dans `AppShell` : marges, `largeur` maximale, espacement entre les blocs. |
237
+ | `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é ; `tailleActions="lg"` pour des actions en `size="lg"`), `compact` quand la fiche répète déjà son nom. |
238
+ | `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 que la largeur en permet), `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). |
239
+ | `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`). |
240
+ | `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. |
241
+ | `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. |
242
+ | `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. |
243
+ | `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 ». |
244
+ | `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`. |
245
+ | `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. |
246
+ | `CenteredScreen` | É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é. |
247
+ | `StatTile`, `StatGrid`, `StatusBadge` | Chiffre clé d'un résumé ; rangée de tuiles (colonnes de `largeurMin` au moins, 190 px par défaut, une seule sur téléphone) ; badge d'état à pastille. `ton` (type `StatusTon`) : `neutral`, `info`, `success`, `warning`, `destructive` ; il colore aussi `Progress` (8 px avec `size="lg"`), le segment choisi d'un `SegmentedControl` et un `IconToggle` actif. |
248
+ | `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`) ; 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). |
249
+ | `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`). Un bouton qui agit garde son infobulle (`TooltipButton`). |
250
+ | `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` : barre collée en bas d'un long formulaire. |
251
+ | `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. |
252
+ | `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). |
253
+ | `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). |
254
+ | `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. |
255
+ | `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). |
256
+
257
+ `ConfirmDialog` et `FormDialog` s'ouvrent par un `declencheur`, ou sont contrôlés (`ouvert`,
258
+ `onOuvertChange`). `DeleteButton` est son propre déclencheur ; `ouvert` et `onOuvertChange`
259
+ permettent de suivre sa confirmation. Leur action (`onConfirmer`, `onEnvoyer`, `onSupprimer`)
260
+ peut renvoyer une promesse : le dialogue l'attend (boutons occupés mais focalisables, Échap sans
261
+ effet), se ferme si elle aboutit, affiche l'erreur si elle échoue. Avec TanStack Query, passer
262
+ `mutateAsync`. Si l'action renvoie `false` (ou une promesse résolue à `false`), le dialogue
263
+ reste ouvert sans erreur : suppression en deux temps, où la page change sa question (la
264
+ description de `ConfirmDialog` est une région polie : la nouvelle est lue).
265
+
266
+ Hors de ces dialogues, un bouton qui lance une action longue passe `enCours` au `Button` (ou au
267
+ `TooltipButton`) : la roue remplace ses icônes, `libelleEnCours` (« Suppression… ») son texte,
268
+ et il reste focalisable (`aria-busy`, clics ignorés, curseur d'attente, pas de survol). Un
269
+ dialogue composé à la main s'ouvre normalement mais refuse de se fermer pendant l'action avec
270
+ `onOpenChange={fermerSaufEnCours(enCours, setOuvert)}`. Un lien dans
271
+ une phrase ou une cellule : `<Button variant="link" size="inline">`. `SpinnerDecoratif` est
272
+ la roue muette, à côté d'un texte qui dit déjà l'attente. Un `CopyButton` placé dans un
273
+ `InputGroupAddon` passe à 24 px, comme le bouton de shadcn dans un groupe (sauf `size` donnée).
274
+
275
+ Un envoi de `FormDialog` refusé par les contraintes marque chaque champ fautif
276
+ (`aria-invalid`, retiré dès qu'il est corrigé) et le nomme par son libellé, y compris une
277
+ liste (`Select`, `SearchSelect`…) dont l'entrée cachée porte la valeur : le libellé de son
278
+ `FormField`, et le focus va à son contrôle visible.
279
+
280
+ Options de `ConfirmDialog` : `verrou` (confirmation impossible, et pourquoi : bouton focalisable,
281
+ raison en infobulle et en description), `libelleAnnuler` (« Revenir au tableau »), `taille`
282
+ (`sm` par défaut, `md` ou `lg` pour un récapitulatif), `elements` et `libelleElements` (liste
283
+ nommée des éléments concernés, qui défile au-delà d'une dizaine de lignes), `onAnnuler`
284
+ (appelé quand la personne renonce : « Annuler » ou Échap ; jamais après une
285
+ réussite, alors que `onOuvertChange(false)` suit les deux). Si `saisie.attendu` change pendant
286
+ l'ouverture (le nombre d'éléments a changé côté serveur), la saisie est vidée, sans remonter le
287
+ dialogue : pas de `key` à forcer. `FormDialog` prend `libelleAnnuler` (« Plus tard ») et
288
+ `actionSecondaire` (`libelle`, `onChoisir`, `destructif`) : une troisième sortie discrète en
289
+ tête du pied (« Se déconnecter »), indisponible pendant l'envoi, qui ne ferme pas le dialogue
290
+ d'elle-même ; si `onChoisir` renvoie une promesse, le dialogue l'attend comme un envoi (ce
291
+ bouton en cours, le reste figé, erreur en tête), et `destructif` la rend grise, rouge au
292
+ survol (comme `TooltipButton`). Les boutons occupés de ces dialogues, de « Réessayer »
293
+ (`ErrorBanner`), de `FileUploadButton` et d'`IconToggle` sont tous le `Button` en cours. Sans champ où l'on tape, il s'ouvre sur le premier contrôle actif et affiché (case,
294
+ liste, choix segmenté… ; un panneau replié est ignoré). Tous les dialogues plafonnent leur
295
+ hauteur à l'écran et gardent le focus : Tab et Maj+Tab en font le tour sans en sortir. Dans
296
+ `FormDialog`, `ConfirmDialog` et `DraftResumeDialog`, seul le corps défile : titre, croix et
297
+ pied restent visibles. Un dialogue composé à la main obtient la même chose en plaçant son
298
+ contenu dans `DialogBody` (aussi dans un `AlertDialogContent`) ; sans lui, tout le contenu
299
+ défile.
300
+
301
+ ```tsx
302
+ // Garde « modifications non enregistrées » avec react-router (routeur « data »).
303
+ useUnsavedChangesWarning(modifie)
304
+ const blocage = useBlocker(
305
+ ({ currentLocation, nextLocation }) =>
306
+ modifie && currentLocation.pathname !== nextLocation.pathname
307
+ )
308
+ <UnsavedChangesDialog blocage={blocage} />
309
+ ```
310
+
311
+ Une action qui fait disparaître le déclencheur (ligne supprimée) passe `finalFocus` (un ref
312
+ ou une fonction, comme le `finalFocus` de Base UI) : le focus va à la ligne suivante ou au
313
+ titre de la liste au lieu de tomber sur la page.
314
+
315
+ ```tsx
316
+ <DeleteButton
317
+ libelle="ce groupe"
318
+ confirmation={{ description: `Le groupe « ${groupe.nom} » sera supprimé définitivement.` }}
319
+ verrou={groupe.critique ? "Groupe critique : suppression impossible" : undefined}
320
+ finalFocus={titreListe}
321
+ onSupprimer={() => supprimer.mutateAsync(groupe.id)}
322
+ />
323
+
324
+ // Suppression en deux temps : le serveur répond 409 « confirmation requise ».
325
+ const [conflit, setConflit] = useState(false)
326
+ <ConfirmDialog
327
+ titre="Supprimer le groupe"
328
+ description={conflit ? "14 rattachements seront supprimés aussi." : "Le groupe sera supprimé."}
329
+ libelleConfirmer={conflit ? "Supprimer quand même" : "Supprimer"}
330
+ onOuvertChange={(ouvert) => !ouvert && setConflit(false)}
331
+ onConfirmer={async () => {
332
+ try {
333
+ await supprimer.mutateAsync({ id, confirmer: conflit })
334
+ } catch (erreur) {
335
+ if (conflit || !confirmationRequise(erreur)) throw erreur
336
+ setConflit(true)
337
+ return false
338
+ }
339
+ }}
340
+ declencheur={<Button variant="destructive">Supprimer</Button>}
341
+ />
342
+
343
+ <QueryBoundary requete={useQuery(...)} vide="Aucun groupe.">
344
+ {(groupes) => <TableGroupes groupes={groupes} />}
345
+ </QueryBoundary>
346
+ ```
347
+
348
+ Primitives shadcn ajoutées pour ces usages : `Alert` a, en plus de `destructive`, les variantes
349
+ `warning`, `info` et `success` (couleur `--info` dans le thème, contrastes vérifiés) ; `info` et
350
+ `success`, messages d'état, portent `role="status"` (annoncés sans interrompre), les autres
351
+ `role="alert"` comme dans shadcn. `Slider` (Base UI) se nomme par `aria-labelledby` ou
352
+ `aria-label` (relayé à chaque curseur) et prend une valeur simple (`value={1.5}`, un curseur)
353
+ ou un tableau (une plage, dont les curseurs s'annoncent « minimum » et « maximum »).
354
+
355
+ Utilitaires : `cn(...classes)` fusionne des classes Tailwind (la dernière l'emporte en cas de
356
+ conflit, comme `clsx` + `tailwind-merge`) ; `useIsMobile()` vaut vrai sous le seuil mobile de
357
+ la suite, `MOBILE_MEDIA_QUERY` (`(width < 1025px)`), dès le premier rendu.
358
+
359
+ Mouvement réduit : sous `prefers-reduced-motion: reduce`, `styles.css` neutralise animations
360
+ et transitions (squelettes, ouverture des dialogues et des menus, tiroir, repli de la barre) ;
361
+ seule la roue de chargement tourne encore.
362
+
363
+ ### Formulaires
364
+
365
+ Compositions des primitives `Field`, `Combobox`, `Popover` + `Calendar`, `ToggleGroup` et
366
+ `Checkbox` de shadcn. Les champs sont contrôlés : `valeur` et `onValeurChange`
367
+ (`valeurs` et `onValeursChange` pour `CheckboxList`) ; les fichiers n'ont pas de valeur, ils
368
+ arrivent à `onChoisir`. Désactiver : `disabled`, comme en HTML. Règle : toujours le
369
+ composant shadcn le plus adapté à l'usage plutôt qu'un contrôle natif ou minimal (une longue
370
+ liste prend un `Combobox` avec recherche).
371
+
372
+ Dans les composites (`DatePicker`, `PhoneInput`, `SearchSelect`), `className` va à
373
+ l'enveloppe (`InputGroup` ou `ButtonGroup`) et les autres attributs (`ref`, `onBlur`,
374
+ `autoComplete`, `data-*`…) au champ de saisie. Avec `name`, `DatePicker` et `PhoneInput`
375
+ soumettent leur valeur (date ISO `2026-03-05`, numéro E.164) par un champ caché, et non le
376
+ texte affiché ; `SearchSelect` soumet `idElement(valeur)`.
377
+
378
+ - `FormField` : libellé (astérisque si `obligatoire`), contrôle, `description` et `erreur`
379
+ (texte ou liste), reliés au contrôle par `htmlFor`, `aria-describedby` et `aria-invalid`.
380
+ L'erreur n'est pas une alerte (`role="alert"` de shadcn retiré) : cinq champs fautifs
381
+ feraient cinq annonces. Un astérisque implique un champ requis. Règle, sur le modèle du
382
+ `useFormField()` du Form de shadcn :
383
+ - l'enfant direct reçoit toujours `id`, `aria-describedby` et `aria-invalid` ; autour d'un
384
+ `InputGroup`, c'est son champ (`InputGroupInput`, `InputGroupTextarea`) qui les reçoit ;
385
+ - s'il est un champ natif ou une primitive shadcn de saisie (`Input`, `Textarea`,
386
+ `NativeSelect`, champ d'`InputGroup`), il reçoit `required` ; sinon `aria-required`
387
+ (déclencheur de `Select`, `ComboboxInput`…) ;
388
+ - un contrôle composite lit le contexte du champ, `useFormField()`, et pose lui-même ces
389
+ attributs et un vrai `required` sur son élément de saisie : c'est ce que font
390
+ `DatePicker`, `PhoneInput` et `SearchSelect`, et ce que doit faire un composant de
391
+ l'application ;
392
+ - un groupe (`CheckboxList`, `SegmentedControl`) n'a ni `required` natif ni droit à
393
+ `aria-required` (`role="group"`) : il cite le libellé du champ par
394
+ `aria-labelledby={champ.libelleId}` (un `<label for>` ne nomme pas un groupe) et, s'il
395
+ est obligatoire, une mention masquée, ce qui donne le nom « Groupes obligatoire ». Il
396
+ prend aussi `required` hors d'un `FormField`. La vérification reste à l'application.
397
+
398
+ `useFormField()` renvoie `{ id, libelleId, descriptionId, erreurId, describedBy,
399
+ obligatoire, invalide }`, ou `null` hors d'un `FormField`. `RequiredMark` existe seul.
400
+ `FormSection` regroupe des champs sous un titre (`FieldSet` + `FieldLegend`).
401
+
402
+ - `DatePicker` : le Date Picker de shadcn avec saisie au clavier (jj/mm/aaaa, ou les chiffres
403
+ seuls `05032026` pour le pavé numérique de l'iPhone ; lue en quittant le champ ou sur
404
+ Entrée), calendrier en français navigable aux flèches, bornes `dateMin`/`dateMax`, listes du
405
+ mois et de l'année (`listesMoisAnnee`, pour une date de naissance), bouton d'effacement.
406
+ Valeur : `Date`. Une saisie illisible ou hors bornes dit pourquoi sous le champ, bloque
407
+ l'envoi d'un formulaire natif, et `onValeurChange(undefined, { invalide: true })` prévient
408
+ l'application (à bloquer avant l'envoi). `moisInitial` : mois montré à l'ouverture tant
409
+ qu'aucune date n'est choisie (une date de naissance s'ouvre ainsi vingt ans plus tôt, pas
410
+ sur le mois courant), et où il revient quand la date est effacée. Fermé au clavier ou par
411
+ un jour choisi, le calendrier rend le focus au champ (un Échap de plus ferme le dialogue
412
+ englobant, sans infobulle à fermer d'abord) ; après un clic ailleurs, le focus reste où
413
+ l'on a cliqué.
414
+ - `PhoneInput` : sélecteur de pays (Combobox : drapeau et indicatif, recherche sur le nom du
415
+ pays ou l'indicatif) et numéro, lus et validés par
416
+ libphonenumber-js. `onValeurChange(valeur, { valide, pays })` reçoit l'E.164
417
+ (`+33612345678`) dès que la longueur est possible ; un numéro tapé avec « + » choisit le
418
+ pays. En erreur (`aria-invalid` du numéro), le groupe est traité comme un seul champ :
419
+ bordure rouge sur le sélecteur de pays comme sur le numéro, un seul halo autour des deux.
420
+ `formaterTelephone(numero, { paysParDefaut = "FR" })` écrit un numéro pour l'affichage
421
+ hors d'un champ (fiche, liste), sans drapeau : national pour le pays par défaut
422
+ (`06 55 18 92 45`), international pour tout autre, pour que son pays se lise
423
+ (`+44 20 7946 0958`), tel quel s'il est illisible. Le `PhoneInput`, lui, écrit toujours le
424
+ format national, le pays étant montré par son drapeau. Chaque appel relit le numéro :
425
+ dans une longue liste, mémoïser le résultat.
426
+ - `SearchSelect` : choix dans une longue liste cherchée par l'application.
427
+ `rechercher(texte, signal)` renvoie une promesse (texte vide : premières suggestions) ;
428
+ `libelleElement`, `idElement` et `rendreOption` décrivent un élément. Anti-rebond,
429
+ chargement (la liste reste vide tant que la réponse ne correspond pas à la saisie : un
430
+ ancien résultat ne se choisit pas), échec avec « Réessayer » (l'erreur va à `onErreur`, ou
431
+ à la console ; au clavier, Entrée dans le champ relance la recherche, même identique),
432
+ liste vide (`vide`) et effacement sont gérés. Sans élément choisi, le texte tapé reste
433
+ quand la liste se ferme (Entrée, Tab), et la recherche reprend à la réouverture. `form`
434
+ va, comme `name`, à l'entrée cachée qui porte la valeur. La liste s'aligne sur le cadre du
435
+ champ, loupe comprise (comme toute liste d'un `ComboboxInput`).
436
+ - `Select` (shadcn) : la liste s'ouvre sous le champ, alignée à gauche, sans jamais le
437
+ recouvrir (`alignItemWithTrigger` et `align` restent réglables sur `SelectContent`).
438
+ Les options vont dans un `SelectGroup`, comme chez shadcn ; posées directement dans
439
+ `SelectContent`, elles ont la même marge. Sans option (y compris un `SelectGroup` vide),
440
+ la liste dit « Aucune option. » (`vide` de `SelectContent`), dans une zone de statut
441
+ annoncée aux lecteurs d'écran. `SelectItem` prend une `description` sous son libellé,
442
+ reliée à l'option : la raison d'une option figée (`disabled`), qui reste lisible quand le
443
+ libellé s'estompe ; le libellé passe alors à la ligne plutôt que d'être coupé.
444
+ - `FileUploadButton` et `FileDropZone` : bouton, ou zone de glisser-déposer avec bouton, sur
445
+ react-dropzone. Types (`accepter={{ "text/csv": [".csv"] }}`) et taille (`tailleMax`, en
446
+ octets) vérifiés, refus en français : à `onRefuser` pour les deux, et affichés dans la zone
447
+ (après le bouton s'il n'y a pas d'`onRefuser`, en rouge, sur une ligne entière dans une
448
+ rangée `flex-wrap` ; sans refus, rien d'autre que le bouton n'occupe le flux, ce qui le
449
+ laisse dans une barre d'outils ou un `ButtonGroup`). Pendant `enCours`, le bouton reste
450
+ focalisé, indisponible, et l'envoi est annoncé. `FileUploadButton` relaie les props de
451
+ `Button` (`id`, `aria-*` : il fonctionne dans un `FormField`).
452
+ - `SegmentedControl` : choix exclusif en boutons joints (`ToggleGroup`), sans désélection ;
453
+ le segment choisi prend, en plus du fond `bg-muted`, un liseré intérieur, ou la couleur
454
+ du `ton` de son option (celle de l'état que produit le choix). L'`infobulle`
455
+ d'une option nomme un segment à icône seule, sans masquer un libellé texte.
456
+ - `CheckboxList` : plusieurs valeurs parmi une liste de cases (`CheckboxGroup` de Base UI) ;
457
+ la `description` d'une option est reliée à sa case. Une case figée n'estompe que sa ligne.
458
+ - `useDraftAutosave({ contenu, enregistrer })` : sauvegarde automatique d'un brouillon là où
459
+ l'application le range (API ou stockage du navigateur) — anti-rebond, sans doublon, une
460
+ écriture à la fois, version pour un verrou optimiste, `erreur` et `reessayer()`, alerte à la
461
+ fermeture de l'onglet ; `enregistrerMaintenant()` avant de quitter. Démonté (navigation
462
+ interne), il range aussitôt l'écriture en attente ; `annuler()` (avant de supprimer le
463
+ brouillon) l'abandonne, elle et celles en file. Un brouillon chargé (`versionInitiale` > 0)
464
+ n'est pas réécrit au montage ; `enregistrer` reçoit le contenu tel quel (sans passer par
465
+ JSON) ; l'objet renvoyé est stable. `marquerEnregistre(contenu)` : appelé dans le même
466
+ gestionnaire que la mise à jour du contenu, passer le nouveau.
467
+
468
+ ```tsx
469
+ <FormField libelle="Téléphone" obligatoire erreur={erreurs.telephone}>
470
+ <PhoneInput valeur={telephone} onValeurChange={setTelephone} />
471
+ </FormField>
472
+
473
+ <FormField libelle="Taille maximale">
474
+ <InputGroup>
475
+ <InputGroupInput inputMode="numeric" />
476
+ <InputGroupAddon align="inline-end">
477
+ <InputGroupText>Mo</InputGroupText>
478
+ </InputGroupAddon>
479
+ </InputGroup>
480
+ </FormField>
481
+ ```
482
+
483
+ ```tsx
484
+ // Contrôle de l'application dans un FormField
485
+ function ChampCode() {
486
+ const champ = useFormField()
487
+ return (
488
+ <input
489
+ id={champ?.id}
490
+ required={champ?.obligatoire}
491
+ aria-describedby={champ?.describedBy}
492
+ aria-invalid={champ?.invalide || undefined}
493
+ />
494
+ )
495
+ }
122
496
  ```
123
497
 
124
- `changer` peut renvoyer une promesse : rejetée, elle affiche « Thème non enregistré ». La
125
- déconnexion est toujours confirmée. La coquille fournit l'élément `<main>` : les pages n'en
126
- ajoutent pas. `ThemeMenu` existe aussi seul (page de connexion…).
498
+ ### Tableau de données
499
+
500
+ La famille `DataTable` suit le [guide Data Table de shadcn](https://ui.shadcn.com/docs/components/data-table)
501
+ sur [TanStack Table v9](https://tanstack.com/table/latest) : les colonnes se déclarent avec
502
+ l'assistant typé, `useDataTable` crée l'instance, les composants la reçoivent en `table`.
503
+
504
+ | Composant | Rôle |
505
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
506
+ | `useDataTable` | instance TanStack : tri, filtre et pagination (côté client, ou serveur avec `triManuel`), colonnes, sélection, dépliage |
507
+ | `DataTable` | la Table de shadcn ; état vide, lignes fantômes du chargement, bandeau d'erreur (`requete`), clic de ligne, détail déplié |
508
+ | `DataTableColumnHeader` | en-tête triable : un clic trie par ordre croissant, le suivant inverse le sens |
509
+ | `dataTableSelectionColumn` | colonne de cases ; Maj+clic sélectionne une plage ; raison d'une case verrouillée |
510
+ | `dataTableExpandColumn` | colonne du chevron qui déplie une ligne (`aria-expanded`, `aria-controls`) |
511
+ | `dataTableActionsColumn` | colonne des commandes d'une ligne : en-tête lu mais invisible, commandes à droite |
512
+ | `DataTableCellLink` | titre d'une ligne : vrai lien (`href`, routeur par `lien`) ou bouton |
513
+ | `DataTableRowActions` | menu « … » d'une ligne |
514
+ | `DataTableViewOptions` | bouton « Colonnes » : afficher, masquer, réordonner (glisser-déposer, clavier compris) |
515
+ | `DataTableToolbar` | recherche, filtres (`DataTableSelectFilter`), compteur (`DataTableCount`), commandes |
516
+ | `DataTablePagination` | pagination par décalage (offset/limit, total connu), ou celle du tableau (`table`) |
517
+ | `DataTableBulkActions` | barre d'actions groupées, collante en bas, avec la sélection ; Échap désélectionne |
518
+ | `useColumnPrefs` | colonnes affichées et leur ordre, gardés dans le navigateur par liste et par personne |
519
+ | `usePersistedState` | `useState` gardé dans le navigateur (filtre choisi…), sous la portée `PorteeStockageLocal` |
520
+
521
+ ```tsx
522
+ import { keepPreviousData, useQuery } from "@tanstack/react-query"
523
+ import {
524
+ DataTable,
525
+ DataTableColumnHeader,
526
+ DataTablePagination,
527
+ DataTableRowActions,
528
+ DataTableToolbar,
529
+ DataTableViewOptions,
530
+ createDataTableColumnHelper,
531
+ dataTableSelectionColumn,
532
+ useDataTable,
533
+ type SortingState,
534
+ } from "@etic-insa/ui"
535
+
536
+ const aide = createDataTableColumnHelper<Etude>()
537
+ // Hors du composant (ou mémorisées) : des colonnes recréées à chaque rendu recalculent tout.
538
+ const colonnes = aide.columns([
539
+ dataTableSelectionColumn<Etude>({
540
+ libelleLigne: (e) => `Sélectionner ${e.titre}`,
541
+ }),
542
+ aide.accessor("titre", {
543
+ header: ({ column }) => (
544
+ <DataTableColumnHeader column={column} libelle="Titre" />
545
+ ),
546
+ meta: { libelle: "Titre" }, // nom dans le sélecteur de colonnes et l'annonce du tri
547
+ }),
548
+ aide.display({
549
+ id: "actions",
550
+ enableHiding: false,
551
+ cell: ({ row }) => (
552
+ // Un nom propre à la ligne : sinon, une liste de boutons « Actions » indiscernables.
553
+ <DataTableRowActions libelle={`Actions pour ${row.original.titre}`}>
554
+ {/* DropdownMenuItem… */}
555
+ </DataTableRowActions>
556
+ ),
557
+ }),
558
+ ])
559
+
560
+ export function Etudes() {
561
+ const [tri, setTri] = useState<SortingState>([{ id: "titre", desc: false }])
562
+ const [decalage, setDecalage] = useState(0)
563
+ const [limite, setLimite] = useState(25)
564
+ const { data, isFetching } = useQuery({
565
+ queryKey: ["etudes", tri, decalage, limite], // le serveur trie et pagine
566
+ queryFn: () => api.etudes({ tri, decalage, limite }),
567
+ // Garde la page affichée pendant le chargement de la suivante : le compteur
568
+ // et la pagination ne retombent pas à 0, la hauteur ne saute pas.
569
+ placeholderData: keepPreviousData,
570
+ })
571
+ const table = useDataTable({
572
+ donnees: data?.items ?? AUCUNE, // référence stable, pas un nouveau [] à chaque rendu
573
+ colonnes,
574
+ idLigne: (e) => e.id,
575
+ tri,
576
+ onTriChange: setTri,
577
+ triManuel: true,
578
+ })
579
+ return (
580
+ <>
581
+ <DataTableToolbar
582
+ compteur={{
583
+ total: data?.total ?? 0,
584
+ decalage,
585
+ nombre: data?.items.length ?? 0,
586
+ }}
587
+ >
588
+ <DataTableViewOptions table={table} />
589
+ </DataTableToolbar>
590
+ <DataTable
591
+ table={table}
592
+ libelle="Études"
593
+ enChargement={isFetching}
594
+ lignesChargement={limite}
595
+ />
596
+ <DataTablePagination
597
+ total={data?.total ?? 0}
598
+ decalage={decalage}
599
+ limite={limite}
600
+ onDecalageChange={setDecalage}
601
+ onLimiteChange={setLimite}
602
+ />
603
+ </>
604
+ )
605
+ }
606
+ ```
607
+
608
+ Chaque partie de l'état (`tri`, `visibiliteColonnes`, `ordreColonnes`, `selection`,
609
+ `lignesDepliees`) est contrôlée si l'application la fournit avec son `on…Change` (pour la
610
+ garder, en `localStorage` par exemple), interne sinon ; `etatInitial` donne la valeur de départ
611
+ d'une partie interne. La sélection se limite par défaut aux lignes affichées (changer de page
612
+ ou de filtre la réduit) ; `conserverSelection` la garde ; `table.options.meta.deselectionner(ids)`
613
+ en retire quelques lignes (refus d'une action groupée pour certaines). Sur mobile, le tableau
614
+ garde ses colonnes et son cadre défile horizontalement. Une colonne se masque par « Colonnes »,
615
+ pas depuis son en-tête ; la dernière colonne de données affichée ne se masque pas.
616
+
617
+ `donnees` et `colonnes` doivent être des références stables. `idLigne` peut s'écrire en ligne :
618
+ il n'est relu que quand `donnees` change. Une ligne ne se redessine que si ses données, sa
619
+ sélection, son dépliage ou les colonnes changent (cocher une case ne redessine pas les 1 000
620
+ autres) : une cellule qui affiche un autre état le lit elle-même (hook, contexte).
621
+
622
+ Accessibilité : le tri choisi, le chargement et « tous sélectionnés » sont annoncés par le
623
+ tableau ; `DataTableCount` est une zone de statut (le nouveau compte après une recherche ou un
624
+ filtre est annoncé) ; `DataTablePagination` annonce la page atteinte. Quand un contrôle disparaît
625
+ sous le focus (« Réinitialiser », la croix de la recherche, le bandeau ou la barre de sélection),
626
+ le focus passe à un élément stable (champ de recherche, premier filtre, case d'en-tête). Le clic
627
+ de ligne (`onActiverLigne`) est un raccourci à la souris : une cellule doit aussi offrir un lien
628
+ ou un bouton pour le clavier (`DataTableCellLink`). Un bouton passé dans `vide` (« Réinitialiser
629
+ les filtres ») disparaît avec l'état vide : l'application rend d'abord le focus au champ de
630
+ recherche. Quand une ligne qui avait le focus disparaît (suppression par un `DeleteButton`, un
631
+ menu « … » ou un dialogue de l'application ouvert depuis elle, liste rechargée), `DataTable`
632
+ rend le focus à la même cellule de la ligne suivante (ou précédente), sinon au tableau ; pour un
633
+ tableau rendu à la main, `focaliserTableau(cadre)` donne la même cible. `size` règle la taille
634
+ du `DeleteButton` (`icon-lg`, ou `lg` avec `avecTexte`, dans un `DetailHeader`
635
+ `tailleActions="lg"`). La recherche de `DataTableToolbar` porte `NO_AUTOFILL` ;
636
+ `recherche.attributs` lui ajoute des attributs.
637
+
638
+ L'en-tête du tableau ne se surligne pas au survol (seules les lignes de données le font). Quand
639
+ le tableau se vide (filtre sans résultat, page suivante en chargement), ses colonnes gardent leur
640
+ largeur. La colonne de sélection a la largeur de la zone de ses cases (40 px) ; une case
641
+ verrouillée reste lisible (fond gris, ou gris foncé cochée) au lieu d'être estompée.
642
+
643
+ #### Sélectionner tous les éléments
644
+
645
+ La case d'en-tête (« Sélectionner la page ») coche les lignes de la page. Avec la pagination
646
+ côté serveur, le tableau ne connaît pas les identifiants des autres pages : pour tout
647
+ sélectionner, `useDataTable` reçoit `total` et un état `toutSelectionne` que l'application
648
+ interprète (en envoyant ses filtres au serveur au lieu d'une liste d'identifiants, par exemple).
649
+ Avec `ligneSelectionnable`, `total` ne compte que les éléments sélectionnables : c'est le nombre
650
+ annoncé et visé par l'action groupée (le tableau ne connaît pas les lignes des autres pages).
651
+
652
+ ```tsx
653
+ const [toutSelectionne, setToutSelectionne] = useState(false)
654
+ const table = useDataTable({
655
+ // …
656
+ total: data?.total,
657
+ toutSelectionne,
658
+ onToutSelectionneChange: setToutSelectionne,
659
+ })
660
+ // Filtres ou tri changés : la sélection ne vaut plus.
661
+ const changerFiltre = (valeur) => {
662
+ setFiltre(valeur)
663
+ setToutSelectionne(false)
664
+ }
665
+ // Action groupée
666
+ const supprimer = () =>
667
+ toutSelectionne
668
+ ? api.supprimerSelon(filtres)
669
+ : api.supprimer(table.getSelectedRowIds())
670
+ ```
671
+
672
+ Quand toute la page est cochée et que `total` compte d'autres éléments, `DataTable` affiche
673
+ au-dessus des lignes « Les 25 éléments de la page sont sélectionnés. Sélectionner les 137
674
+ éléments », puis « Les 137 éléments sont sélectionnés. Tout désélectionner » (`unite` et
675
+ `feminin` accordent le texte, comme pour `DataTableCount` et `DataTableBulkActions`).
676
+ `DataTableBulkActions` compte alors le total. L'état repasse à `false` dès qu'une ligne de la
677
+ page n'est plus cochée (par le tableau ou par l'application), quand la page change (même avec
678
+ `conserverSelection`) et par « Tout désélectionner »
679
+ (`table.options.meta.toutDeselectionner()` pour un bouton de l'application) ; l'application le
680
+ remet à `false` quand ses filtres ou le tri changent.
681
+
682
+ Une ligne non sélectionnable avec `verrouLigne` garde une case focalisable, en lecture seule, qui
683
+ dit sa raison (infobulle et description). Échap vide la sélection quand le focus est dans le
684
+ tableau ou dans la barre d'actions, pas ailleurs (navigation, dialogue, menu). Un tableau rendu à
685
+ la main avec les primitives `Table` et une instance `useDataTable` pose
686
+ `ref={table.options.meta.racine}` sur son conteneur pour en profiter.
687
+
688
+ #### Lignes dépliables
689
+
690
+ Sur le modèle de TanStack (`rowExpandingFeature`) et des exemples shadcn : `dataTableExpandColumn`
691
+ ajoute le chevron (bouton à icône seule, infobulle, `aria-expanded`, `aria-controls`), et
692
+ `rendreDetail` de `DataTable` rend le détail sous la ligne, sur toute la largeur. Sans
693
+ `onActiverLigne`, un clic sur la ligne la déplie aussi ; la sélection et les commandes de la
694
+ ligne restent indépendantes. Sur mobile, le détail suit la largeur visible du cadre : il reste
695
+ lisible pendant que les colonnes défilent.
696
+
697
+ ```tsx
698
+ const colonnes = aide.columns([
699
+ dataTableExpandColumn<Evenement>({
700
+ libelleLigne: (e) => `Détail de « ${e.action} » du ${e.date}`,
701
+ }),
702
+ aide.accessor("action", { header: "Action" }),
703
+ // …
704
+ ])
705
+
706
+ const table = useDataTable({
707
+ donnees,
708
+ colonnes,
709
+ idLigne: (e) => e.id,
710
+ ligneDepliable: (e) => e.avant !== null, // pas de chevron sans détail
711
+ uneSeuleLigneDepliee: true, // déplier une ligne replie l'autre
712
+ })
713
+ <DataTable
714
+ table={table}
715
+ libelle="Journal"
716
+ rendreDetail={(e) => <DetailEvenement evenement={e} />}
717
+ />
718
+ ```
719
+
720
+ Une requête rechargée ne referme pas le détail ouvert ; une ligne qui disparaît des données est
721
+ retirée des lignes dépliées.
722
+
723
+ #### Pagination
724
+
725
+ `DataTablePagination` ramène sur la dernière page un `decalage` passé au-delà de la fin
726
+ (dernière ligne de la dernière page supprimée), par `onDecalageChange`, mais seulement une fois
727
+ le total connu (`total > 0`) : un total à 0 pendant un chargement ne renvoie pas à la première
728
+ page. Avec TanStack Query, `placeholderData: keepPreviousData` garde la page précédente (et son
729
+ total) pendant le chargement de la suivante. « Précédente » et « Suivante » restent focalisables
730
+ en bout de liste.
731
+
732
+ #### Liste chargée d'un bloc : filtre, tri et pagination côté client
733
+
734
+ Comme dans le guide de shadcn (`getPaginationRowModel`, `getFilteredRowModel`), `useDataTable`
735
+ filtre, trie et découpe lui-même une liste reçue en entier. `paginationClient` l'active (25
736
+ lignes par page, `etatInitial.pagination` pour une autre taille) ; `DataTablePagination` et
737
+ `DataTableCount` reçoivent alors `table` au lieu de leurs nombres. `filtreGlobal` cherche dans
738
+ toutes les colonnes à accesseur, sans casse ni accents (« tresorerie » trouve « Trésorerie ») ;
739
+ `filtresColonnes` applique la fonction de chaque colonne (`filterFn`). Le tri nommé
740
+ `texteFr` (`sortFn: "texteFr"`) suit l'ordre alphabétique français de `comparerFr`, accents
741
+ compris, et « Poste 2 » avant « Poste 10 » ; le filtre nommé `texteFr` est celui de la
742
+ recherche (`normaliserRecherche`) ; une recherche vide ne filtre rien. Un changement de filtre
743
+ ou de tri ramène à la première page : le contenu est comparé, un `filtresColonnes` recréé à
744
+ l'identique à chaque rendu ne change pas la page. Supprimer une ligne garde la page courante (la
745
+ dernière page existante si elle disparaît) ; une page de départ (`etatInitial`, ou lue dans
746
+ l'URL) est gardée tant que les données ne sont pas arrivées. Changer le nombre de lignes par
747
+ page revient à la première page en une seule mise à jour (`setPagination`).
748
+ `DataTablePagination table={…}` sans `paginationClient` n'affiche rien et prévient dans la
749
+ console : la table ne découpe pas de pages.
750
+
751
+ ```tsx
752
+ const colonnes = aide.columns([
753
+ aide.accessor("nom", {
754
+ header: ({ column }) => <DataTableColumnHeader column={column} libelle="Poste" />,
755
+ sortFn: "texteFr",
756
+ cell: ({ row }) => (
757
+ <DataTableCellLink href={`/postes/${row.original.id}`} lien={RouterLink}>
758
+ {row.original.nom}
759
+ </DataTableCellLink>
760
+ ),
761
+ }),
762
+ aide.accessor("pole", { header: "Pôle", filterFn: "equalsString" }),
763
+ dataTableActionsColumn<Poste>({
764
+ actions: (p) => <DeleteButton libelle={`le poste ${p.nom}`} … />,
765
+ // enableHiding: true pour une colonne d'actions masquable et déplaçable.
766
+ }),
767
+ ])
768
+
769
+ const [recherche, setRecherche] = useState("")
770
+ const table = useDataTable({
771
+ donnees: data ?? AUCUN,
772
+ colonnes,
773
+ idLigne: (p) => p.id,
774
+ paginationClient: true,
775
+ filtreGlobal: recherche,
776
+ onFiltreGlobalChange: setRecherche,
777
+ filtresColonnes: useMemo(() => (pole ? [{ id: "pole", value: pole }] : []), [pole]),
778
+ })
779
+ <DataTableToolbar
780
+ recherche={{ valeur: recherche, onValeurChange: setRecherche }}
781
+ compteur={{ table, unite: { singulier: "poste", pluriel: "postes" } }}
782
+ />
783
+ <DataTable table={table} libelle="Postes" requete={requetePostes} />
784
+ <DataTablePagination table={table} />
785
+ ```
786
+
787
+ #### Erreur de la requête
788
+
789
+ `requete` (le résultat de `useQuery` convient tel quel) affiche en échec le `QueryErrorBanner`
790
+ (« Réessayer ») au-dessus du tableau, rendu dans le parent comme pour `QueryBoundary` (le parent
791
+ règle l'espacement : `flex flex-col gap-4`). L'état vide se tait alors : « Aucun résultat »
792
+ contredirait le bandeau. Sans `enChargement`, `isFetching` en tient lieu.
793
+
794
+ #### Colonnes gardées dans le navigateur
795
+
796
+ `useColumnPrefs` garde, pour chaque liste et chaque personne, les colonnes affichées et leur
797
+ ordre (`localStorage`, format `{ order, visible }`) ; `optionsTableau` s'étale dans
798
+ `useDataTable`. Une colonne apparue depuis l'enregistrement s'ajoute à la fin, affichée si elle
799
+ l'est par défaut ; une colonne non offerte ici (`disponibles` : droit manquant) garde son état et
800
+ sa place ; `fixesEnTete` reste hors préférences. `optionsTableau.colonnesReglables` (une option
801
+ de `useDataTable` et de `DataTableViewOptions`) limite le panneau « Colonnes » aux colonnes des
802
+ préférences : les fixes et les autres n'y sont ni masquables ni déplaçables. `reinitialiser()`
803
+ revient aux valeurs par
804
+ défaut. `usePersistedState(cle, defaut, { accepter })` garde de même un réglage simple (un filtre
805
+ choisi) ; rien n'est écrit tant que rien n'est choisi, et `accepter` écarte une valeur
806
+ enregistrée devenue invalide. La portée (la personne connectée) se fournit une fois :
807
+ `<PorteeStockageLocal portee={moi?.id}>` ; les clés écrites sont `<portée>:<clé>` (`anon:`
808
+ sans personne), comme celles d'ETIC Members.
809
+
810
+ ```tsx
811
+ const prefs = useColumnPrefs({
812
+ cle: "membres:personnes",
813
+ colonnes: ["email", "statut", "telephone"],
814
+ visiblesParDefaut: ["email", "statut"],
815
+ fixesEnTete: ["select", "nom"],
816
+ })
817
+ const table = useDataTable({
818
+ donnees,
819
+ colonnes,
820
+ idLigne,
821
+ ...prefs.optionsTableau,
822
+ })
823
+ ```
824
+
825
+ #### Tableau rendu à la main
826
+
827
+ Un tableau que `DataTable` ne sait pas rendre (deux rangées d'en-tête, cellules éditables)
828
+ garde le sélecteur de colonnes et la barre d'actions sans instance `useDataTable` :
829
+ `DataTableViewOptions` reçoit `colonnes` (`{ id, libelle, masquable? }`) et les options de
830
+ `useDataTable` qui règlent les colonnes (`visibiliteColonnes`, `onVisibiliteColonnesChange`,
831
+ `ordreColonnes`, `onOrdreColonnesChange` ; sans ce dernier, pas de glisser-déposer), donc
832
+ `prefs.optionsTableau` de `useColumnPrefs` tel quel ; `DataTableBulkActions` reçoit `nombre`,
833
+ `onToutDeselectionner` et `racine` (le cadre du tableau, où Échap vide la sélection et où le
834
+ focus revient).
835
+
836
+ ```tsx
837
+ <DataTableViewOptions colonnes={COLONNES} {...prefs.optionsTableau} />
838
+ <DataTableBulkActions
839
+ nombre={selection.size}
840
+ onToutDeselectionner={() => setSelection(new Set())}
841
+ racine={cadreRef}
842
+ >
843
+ …
844
+ </DataTableBulkActions>
845
+ ```
846
+
847
+ ### Utilitaires et hooks
848
+
849
+ Textes chiffrés en français : une valeur absente rend un repli (« — » par défaut, dernier
850
+ argument ou option `repli`), une date illisible est rendue telle quelle.
851
+
852
+ | Fonction | Rôle |
853
+ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
854
+ | `compte`, `accorde`, `nombreFr`, `uniteAccordee`, `participe` | « 1 234 lignes », « 0 doublon » (0 et 1 au singulier) ; le mot seul, pluriel irrégulier en option ; nombre au format français ; participe accordé en genre. |
855
+ | `formaterOctets` | « 512 o », « 1,5 Ko », « 120 Mo » (base 1 024, une décimale sous 100). |
856
+ | `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 »). |
857
+ | `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 ». |
858
+ | `lireDateIso`, `ecrireDateIso` | Date sans heure de l'API (`AAAA-MM-JJ`) ↔ `Date` du `DatePicker`, en heure locale ; un 31 février est refusé. |
859
+ | `normaliser`, `correspondance` | Texte sans accents ni casse ; filtre d'une recherche locale (`correspondance(recherche)(...textes)`, recherche vide : tout passe). |
860
+ | `NO_AUTOFILL` | Attributs à étaler sur un champ qui n'est pas un identifiant : les gestionnaires de mots de passe s'en écartent. |
861
+ | `useDebouncedValue`, `useDocumentTitle` | Valeur recopiée après un délai sans changement (300 ms par défaut) ; titre de l'onglet le temps que la page est montée. |
862
+
863
+ ```tsx
864
+ const [recherche, setRecherche] = useState("")
865
+ const rechercheDifferee = useDebouncedValue(recherche)
866
+ const correspond = correspondance(recherche)
867
+ const visibles = postes.filter((p) => correspond(p.nom, p.pole?.nom))
868
+
869
+ <DatePicker
870
+ valeur={lireDateIso(membre.date_naissance)}
871
+ onValeurChange={(date) => setDateNaissance(ecrireDateIso(date))}
872
+ />
873
+ <Input type="search" {...NO_AUTOFILL} />
874
+ ```
127
875
 
128
876
  ### Développer contre les sources locales
129
877
 
@@ -179,8 +927,145 @@ npm run build # dist/ : un module par composant, types, styles.css
179
927
  - seuil mobile à 1 024 px compris au lieu de 768 px : `hooks/use-mobile.ts` (réécrit avec
180
928
  `useSyncExternalStore`, juste dès le premier rendu) et les variantes `md:` de
181
929
  `components/ui/sidebar.tsx`, devenues `min-[1025px]:` ;
182
- - textes en français, lus par les lecteurs d'écran : `sidebar.tsx` (« Menu »,
183
- « Afficher ou masquer le menu »), `sheet.tsx` (« Fermer »).
930
+ - textes en français, visibles ou lus par les lecteurs d'écran : `sidebar.tsx` (« Menu »,
931
+ « Navigation de l'application. », « Afficher ou masquer le menu »), `sheet.tsx` et `dialog.tsx` (« Fermer »),
932
+ `pagination.tsx` (« Pagination », « Précédente », « Suivante », « Page précédente »,
933
+ « Page suivante », « Autres pages »), `breadcrumb.tsx` (« Fil d’Ariane »,
934
+ « Niveaux masqués »), `spinner.tsx` (« Chargement »), `combobox.tsx` (« Effacer » et
935
+ « Retirer », libellés ajoutés aux boutons à icône seule) ;
936
+ - calendrier en français : `calendar.tsx` prend par défaut la locale `fr` de
937
+ react-day-picker (mois, jours et libellés d'accessibilité) et `weekStartsOn={1}` ;
938
+ - jours du calendrier de 36 px sous le seuil mobile (cible tactile), 28 px au-delà comme
939
+ dans shadcn : `--cell-size` de `calendar.tsx` ;
940
+ - thème (`styles.css`) : `--muted-foreground` plus foncé en clair (≥ 4,5:1 sur `--muted` :
941
+ initiales d'`Avatar`, `Kbd`), `--destructive` plus foncé en clair et plus clair en sombre
942
+ (≥ 4,5:1 sur sa teinte : bouton et badge `destructive`, y compris dans un pied de
943
+ dialogue) ; contrastes vérifiés par `src/theme.test.ts` ;
944
+ - l'accent comme texte en `text-primary-text` au lieu de `text-primary` : variante `link` de
945
+ `button.tsx` et `badge.tsx`, liens survolés de `empty.tsx`, `field.tsx` et `item.tsx` ;
946
+ - import inutilisé de React retiré de `scroll-area.tsx` (sans quoi `tsc` échoue) ;
947
+ - `button.tsx` : un bouton `aria-disabled` (désactivé mais focalisable, `focusableWhenDisabled`)
948
+ est estompé comme un bouton `disabled`, curseur interdit (d'attente s'il est `enCours`), sans
949
+ enfoncement au clic ; pas de `pointer-events-none`, qui couperait l'infobulle de sa raison ;
950
+ - `button.tsx` : taille `inline` (`h-auto min-h-6 gap-1 px-0`), pour un lien `variant="link"`
951
+ dans une phrase ou une cellule, cible tactile de 24 px gardée ;
952
+ - `button.tsx` : `enCours` (roue muette à la place des icônes, `aria-busy`, `data-en-cours`,
953
+ pas de survol, clics ignorés, focus gardé par `focusableWhenDisabled`) et `libelleEnCours` ;
954
+ un `children` n'est passé que s'il est donné (les enfants d'un `render` restent) ; `spinner.tsx` :
955
+ `SpinnerDecoratif`, roue sans rôle ni nom, cachée aux lecteurs d'écran ;
956
+ - variantes `success` et `warning` ajoutées à `badge.tsx`, sur le modèle de `destructive`
957
+ (teinte à 10 %, 20 % en sombre, texte de la couleur) ;
958
+ - case à cocher partielle (`indeterminate`) : `checkbox.tsx` affiche un trait sur fond plein,
959
+ comme une case cochée, au lieu de la coche sur fond vide de shadcn (on croyait tout coché) ;
960
+ - bord d'une case à cocher vide en `--control-border` (`styles.css`) au lieu de `--input` :
961
+ `--muted-foreground` à 80 % en clair (≥ 3:1, le bord de Nova se voyait à peine), `--input`
962
+ en sombre ;
963
+ - même règle pour le contour d'une radio non cochée (`radio-group.tsx`, focus dans un
964
+ `field-label` compris) et le rail d'un switch éteint (`switch.tsx`, `--control-border` à la
965
+ place de `bg-input`) : ≥ 3:1 sur la page et sur une carte, en clair comme en sombre (le
966
+ registre restait à 1,6:1 et 1,3:1 en sombre) ; le pouce reste distinct du rail ;
967
+ - variantes `warning`, `info` et `success` ajoutées à `alert.tsx`, sur le modèle de
968
+ `destructive` (fond de carte, texte de la couleur, description à 90 %), et couleur `--info`
969
+ dans `styles.css` ;
970
+ - Ctrl+B (repli de la barre latérale) ignoré quand le focus est dans un champ de saisie
971
+ (`input`, `textarea`, `select`, `contenteditable`) : `sidebar.tsx`, pour ne pas voler le
972
+ gras d'un éditeur riche ;
973
+ - anneau de focus (`focus-visible:ring-3 ring-ring/50`) sur le panneau de `tabs.tsx`, arrêt
974
+ de tabulation qui n'en avait pas ;
975
+ - `slider.tsx` : une valeur simple (un nombre) dessine un seul curseur, au lieu de deux ;
976
+ anneau de focus clavier `has-focus-visible:ring-3` sur le curseur (le focus va à l'input
977
+ range caché qu'il contient) ; `aria-label` du slider relayé aux curseurs ; une plage
978
+ annonce « 20 (minimum) », « 80 (maximum) » au lieu de « start/end range » ;
979
+ - déclencheurs de `select.tsx` et `native-select.tsx` en `text-base md:text-sm`, comme
980
+ `Input` (en 14 px sur téléphone, iOS zoome à la sélection) ;
981
+ - bouton qui ouvre la liste de `combobox.tsx` nommé « Afficher les options » ;
982
+ - `select.tsx` : liste sous le champ et alignée à gauche par défaut
983
+ (`alignItemWithTrigger={false}`, `align="start"`) au lieu d'être posée sur le champ et
984
+ centrée (elle le masquait, et débordait des deux côtés d'un champ étroit) ; options
985
+ posées sans `SelectGroup` à la même marge que dans un groupe ; `vide` de `SelectContent`
986
+ (« Aucune option. » en `role="status"` au lieu d'une fenêtre vide) ; `description` de
987
+ `SelectItem`, sous le libellé, qui reste lisible quand l'option est figée, avec un
988
+ libellé qui passe à la ligne ;
989
+ - `checkbox.tsx` : la case s'estompe d'après son propre état (`data-disabled`,
990
+ `aria-disabled`, `fieldset` désactivé) et non par `group-has-disabled/field`, qui
991
+ estompait toutes les cases d'un champ dès qu'une seule y était figée ; variantes
992
+ `disabled:` retirées (la racine est un `<span>`, jamais `:disabled`). Dans un
993
+ `<fieldset disabled>`, la case est réellement inactive (Base UI la coche par son entrée
994
+ cachée, que le fieldset désactive) et en a l'air ;
995
+ - `combobox.tsx` : la liste s'ancre sur le cadre (`InputGroup`) du `ComboboxInput`, et
996
+ non sur le seul champ que décale un addon de tête. `Combobox` porte une ref vers ce
997
+ cadre, que `ComboboxInput` remplit et que `ComboboxContent` passe à `anchor` (juste dès
998
+ l'ouverture, `defaultOpen` compris) ; une `anchor` explicite (puces,
999
+ `useComboboxAnchor`) l'emporte ; sans `ComboboxInput` hors de la liste, l'ancre reste
1000
+ le déclencheur ; un `ComboboxInput` placé dans la liste (recherche d'un sélecteur
1001
+ ouvert par un bouton) ne s'enregistre pas. Largeur minimale : celle de l'ancre
1002
+ (`min-w-(--anchor-width)`), au lieu de l'ancre + 28 px de shadcn, qui couvraient
1003
+ l'addon d'un champ seul ;
1004
+ - imports par sous-chemin, imposés par la règle ESLint `no-restricted-imports`
1005
+ (`eslint.config.js`) : Base UI (`@base-ui/react/combobox` dans `combobox.tsx`, que
1006
+ shadcn importe par la racine), date-fns, et la seule locale `react-day-picker/locale/fr`
1007
+ dans `calendar.tsx`. Les racines chargent tous les composants, toutes les fonctions ou
1008
+ toutes les locales aux outils sans tree-shaking (vitest des applications) ;
1009
+ - `alert.tsx` : `role="status"` pour `info` et `success` (messages d'état, annoncés sans
1010
+ interrompre), `role="alert"` gardé pour les autres variantes ;
1011
+ - onglets `variant="line"` de `tabs.tsx` qui passent à la ligne sous 640 px (`max-sm:` :
1012
+ liste en `h-auto max-w-full flex-wrap justify-start`, déclencheurs en `h-7 flex-none`)
1013
+ au lieu de déborder ; un défilement couperait le trait de l'onglet actif. Au-delà, et pour
1014
+ la variante par défaut en pastille, rien ne change ;
1015
+ - `avatar.tsx` : `diametre` (px) au-delà des tailles `sm`, `default` et `lg` (24 à 40 px),
1016
+ qui pose largeur, hauteur et taille des initiales (36 % du diamètre), reprise par
1017
+ `AvatarFallback` (`group-data-diametre/avatar:text-[length:inherit]`) ;
1018
+ - `SidebarTrigger` de `sidebar.tsx` : `libelle`, le nom lu du bouton (« Afficher ou masquer
1019
+ le menu » par défaut), au lieu d'un `aria-label` qui masquerait ce texte ;
1020
+ - `badge.tsx` : variante `info` (sur le modèle de `success`) et taille `size="lg"` (28 px,
1021
+ la hauteur d'un badge qui porte un bouton « Retirer ») ;
1022
+ - `progress.tsx` : `ton` (piste à 15 % et remplissage de la couleur, `StatusTon`, classes
1023
+ dans `lib/ton.ts`) et `size="lg"` (piste de 8 px au lieu de 4), au lieu de recolorer la
1024
+ piste et le remplissage par sélecteurs `[data-slot=…]` ;
1025
+ - `dialog.tsx` et `alert-dialog.tsx` : hauteur plafonnée à l'écran
1026
+ (`max-h-[calc(100dvh-2rem)]`), sans quoi le bas d'un long dialogue (et ses boutons) sortait
1027
+ de l'écran sur téléphone. Le contenu est une colonne (`flex flex-col` au lieu de `grid`) ;
1028
+ `DialogBody`, ajouté à `dialog.tsx`, est la zone qui défile seule (`min-h-0
1029
+ overflow-y-auto`), en-tête, croix et pied restant visibles ; sans elle, tout le contenu
1030
+ défile (`overflow-y-auto`), jamais à l'horizontale (`overflow-x-hidden`) ;
1031
+ - `alert-dialog.tsx` : à la taille par défaut et sans `AlertDialogMedia`, titre et
1032
+ description alignés à gauche dès le téléphone (shadcn les centre sous `sm`), comme la liste
1033
+ et les champs du corps ; avec un média, la grille de shadcn reste telle quelle ;
1034
+ - `table.tsx` : la ligne d'en-tête ne se surligne pas au survol (`[&_tr:hover]:bg-transparent`
1035
+ sur `TableHeader`) ; les lignes de données gardent le survol de shadcn ;
1036
+ - `tooltip.tsx` : le focus qu'un popup (menu, calendrier, dialogue) rend à son
1037
+ déclencheur en se fermant, par Échap ou par un choix, n'ouvre plus l'infobulle de
1038
+ `TooltipTrigger` : elle absorbait l'Échap suivant, celui qui ferme le dialogue
1039
+ englobant (`ThemeMenu`, « Plus d'actions » de `DetailHeader`, tout `TooltipTrigger` posé
1040
+ sur un `DropdownMenuTrigger`). Reconnu par `lib/focus-rendu.ts` : le déclencheur a perdu
1041
+ le focus son popup ouvert (`aria-expanded`), ou le focus vient d'un popup qui ne le
1042
+ contient pas. Tout autre focus clavier l'ouvre comme avant (focus initial d'un dialogue
1043
+ ouvert par Entrée compris) ; le survol et l'`onFocus` de l'application ne changent pas.
1044
+ `CLASSES_BULLE` et `CLASSES_FLECHE` (internes) portent l'allure de la bulle, partagée
1045
+ avec `Toggletip` ;
1046
+ - `popover.tsx` : `PopoverContent` accepte `anchor` (celui du `Positioner` de Base UI),
1047
+ pour un popover sans `PopoverTrigger` (`Toggletip`, ancré sur l'élément qu'il explique).
1048
+
1049
+ Le thème ajoute aussi (`styles.css`, hors composants shadcn) la règle de mouvement réduit.
1050
+
1051
+ Thème : couleur de base `gray` de shadcn (registre `colors/gray.json`, `cssVarsV4`) au lieu
1052
+ de `neutral` ; jeton ajouté `--page` (`bg-page`, gray-50 en clair, `--background` en
1053
+ sombre), pris par le `body` au lieu de `bg-background`, `--background` restant celui du
1054
+ registre ; `--success` clair un cran plus foncé (≥ 4,5:1 sur sa teinte posée sur la page
1055
+ gray-50) ; `--muted-foreground` clair un
1056
+ peu plus foncé que gray-500 (≥ 4,5:1 sur `--muted`) ; `--control-border`
1057
+ (`--muted-foreground` à 80 %) en sombre aussi, au lieu de `--input` (sous 2:1) ; `--sidebar`
1058
+ clair = `--background` (barre latérale blanche, au lieu du gray-50 du registre) ;
1059
+ `color-scheme` dans `:root` et `.dark`. Les valeurs sont commentées dans `styles.css` ;
1060
+ `theme.test.ts` compare chaque jeton au registre, écarts (`ECARTS`) exceptés, et en vérifie
1061
+ les contrastes. Hors `ui/` : `CenteredScreen` est posé sur `bg-muted/40` au lieu du
1062
+ `bg-muted` des blocs de connexion de shadcn (fond moins appuyé, en sombre surtout) ; le
1063
+ contenu d'`AppShell` (`SidebarInset`) et sa barre mobile sont en `bg-page` ; le cadre de
1064
+ `DataTable` et la `Disclosure` `carte` sont en `bg-card`, blancs comme une carte.
1065
+
1066
+ Sans écart de code mais garanti par le même test : `Button` sans `type` rend
1067
+ `type="button"` (Base UI le fait pour un bouton natif) et ne soumet donc pas son formulaire.
1068
+
184
1069
  - `src/components/etic/` : composants ETIC qui importent ceux de `ui/` et ajoutent
185
1070
  comportement, composition ou variantes.
186
1071
  - `src/index.ts` : tout ce qu'une application peut importer. Un composant non exporté ici