@15gifts/back-office-kit 0.1.0-alpha.0 → 0.1.0-alpha.1

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 (304) hide show
  1. package/README.md +9 -6
  2. package/dist/browser/back-office-kit.js +6649 -5932
  3. package/dist/components/Alert/Alert.css.d.ts +1 -0
  4. package/dist/components/Alert/Alert.d.ts +12 -2
  5. package/dist/components/Alert/Alert.js +33 -29
  6. package/dist/components/Alert/Alert.js.map +1 -1
  7. package/dist/components/Alert/Alert.styles.js +2 -2
  8. package/dist/components/Alert/Alert.styles.js.map +1 -1
  9. package/dist/components/AppShell/AppShell.css.d.ts +2 -0
  10. package/dist/components/AppShell/AppShell.d.ts +3 -1
  11. package/dist/components/AppShell/AppShell.js +42 -26
  12. package/dist/components/AppShell/AppShell.js.map +1 -1
  13. package/dist/components/AppShell/AppShell.styles.js +3 -2
  14. package/dist/components/AppShell/AppShell.styles.js.map +1 -1
  15. package/dist/components/Avatar/Avatar.d.ts +1 -0
  16. package/dist/components/Avatar/Avatar.js.map +1 -1
  17. package/dist/components/Badge/Badge.css.d.ts +5 -0
  18. package/dist/components/Badge/Badge.d.ts +4 -1
  19. package/dist/components/Badge/Badge.js +6 -5
  20. package/dist/components/Badge/Badge.js.map +1 -1
  21. package/dist/components/Badge/Badge.styles.js +16 -15
  22. package/dist/components/Badge/Badge.styles.js.map +1 -1
  23. package/dist/components/Breadcrumbs/Breadcrumbs.css.d.ts +2 -0
  24. package/dist/components/Breadcrumbs/Breadcrumbs.d.ts +2 -0
  25. package/dist/components/Breadcrumbs/Breadcrumbs.js +27 -27
  26. package/dist/components/Breadcrumbs/Breadcrumbs.js.map +1 -1
  27. package/dist/components/Breadcrumbs/Breadcrumbs.styles.js +2 -2
  28. package/dist/components/Breadcrumbs/Breadcrumbs.styles.js.map +1 -1
  29. package/dist/components/Button/Button.css.d.ts +1 -1
  30. package/dist/components/Button/Button.d.ts +5 -4
  31. package/dist/components/Button/Button.js +21 -21
  32. package/dist/components/Button/Button.js.map +1 -1
  33. package/dist/components/Button/Button.styles.js.map +1 -1
  34. package/dist/components/Card/Card.css.d.ts +2 -0
  35. package/dist/components/Card/Card.d.ts +7 -1
  36. package/dist/components/Card/Card.js +33 -22
  37. package/dist/components/Card/Card.js.map +1 -1
  38. package/dist/components/Card/Card.styles.js +2 -2
  39. package/dist/components/Card/Card.styles.js.map +1 -1
  40. package/dist/components/ChatTranscript/ChatTranscript.d.ts +2 -2
  41. package/dist/components/ChatTranscript/ChatTranscript.js +74 -71
  42. package/dist/components/ChatTranscript/ChatTranscript.js.map +1 -1
  43. package/dist/components/Checkbox/Checkbox.d.ts +2 -1
  44. package/dist/components/Checkbox/Checkbox.js +30 -34
  45. package/dist/components/Checkbox/Checkbox.js.map +1 -1
  46. package/dist/components/Checkbox/Checkbox.styles.js.map +1 -1
  47. package/dist/components/CheckboxGroup/CheckboxGroup.css.d.ts +2 -0
  48. package/dist/components/CheckboxGroup/CheckboxGroup.d.ts +28 -0
  49. package/dist/components/CheckboxGroup/CheckboxGroup.js +66 -0
  50. package/dist/components/CheckboxGroup/CheckboxGroup.js.map +1 -0
  51. package/dist/components/CheckboxGroup/CheckboxGroup.styles.js +10 -0
  52. package/dist/components/CheckboxGroup/CheckboxGroup.styles.js.map +1 -0
  53. package/dist/components/CheckboxGroup/index.d.ts +2 -0
  54. package/dist/components/Chip/Chip.css.d.ts +2 -0
  55. package/dist/components/Chip/Chip.d.ts +15 -3
  56. package/dist/components/Chip/Chip.js +35 -16
  57. package/dist/components/Chip/Chip.js.map +1 -1
  58. package/dist/components/Chip/Chip.styles.js +2 -2
  59. package/dist/components/Chip/Chip.styles.js.map +1 -1
  60. package/dist/components/Chip/index.d.ts +1 -1
  61. package/dist/components/ColorPicker/ColorPicker.d.ts +3 -1
  62. package/dist/components/ColorPicker/ColorPicker.js +46 -47
  63. package/dist/components/ColorPicker/ColorPicker.js.map +1 -1
  64. package/dist/components/ColorPicker/ColorPicker.styles.js.map +1 -1
  65. package/dist/components/Combobox/Combobox.d.ts +28 -4
  66. package/dist/components/Combobox/Combobox.js +130 -109
  67. package/dist/components/Combobox/Combobox.js.map +1 -1
  68. package/dist/components/CopyButton/CopyButton.d.ts +11 -0
  69. package/dist/components/CopyButton/CopyButton.js +40 -0
  70. package/dist/components/CopyButton/CopyButton.js.map +1 -0
  71. package/dist/components/CopyButton/index.d.ts +2 -0
  72. package/dist/components/DateRangePicker/DateRangePicker.d.ts +10 -3
  73. package/dist/components/DateRangePicker/DateRangePicker.js +107 -110
  74. package/dist/components/DateRangePicker/DateRangePicker.js.map +1 -1
  75. package/dist/components/DateRangePicker/DateRangePicker.styles.js +2 -2
  76. package/dist/components/DateRangePicker/DateRangePicker.styles.js.map +1 -1
  77. package/dist/components/DateTimeInput/DateTimeInput.d.ts +1 -1
  78. package/dist/components/DateTimeInput/DateTimeInput.js +20 -28
  79. package/dist/components/DateTimeInput/DateTimeInput.js.map +1 -1
  80. package/dist/components/DateTimeInput/DateTimeInput.styles.js +1 -0
  81. package/dist/components/DescriptionList/DescriptionList.d.ts +8 -0
  82. package/dist/components/DescriptionList/DescriptionList.js +2 -1
  83. package/dist/components/DescriptionList/DescriptionList.js.map +1 -1
  84. package/dist/components/DetailsSummary/DetailsSummary.css.d.ts +1 -0
  85. package/dist/components/DetailsSummary/DetailsSummary.d.ts +5 -1
  86. package/dist/components/DetailsSummary/DetailsSummary.js +15 -15
  87. package/dist/components/DetailsSummary/DetailsSummary.js.map +1 -1
  88. package/dist/components/DetailsSummary/DetailsSummary.styles.js +10 -2
  89. package/dist/components/DetailsSummary/DetailsSummary.styles.js.map +1 -1
  90. package/dist/components/DetailsSummary/index.d.ts +1 -1
  91. package/dist/components/Drawer/Drawer.css.d.ts +3 -0
  92. package/dist/components/Drawer/Drawer.d.ts +24 -3
  93. package/dist/components/Drawer/Drawer.js +55 -46
  94. package/dist/components/Drawer/Drawer.js.map +1 -1
  95. package/dist/components/Drawer/Drawer.styles.js +7 -2
  96. package/dist/components/Drawer/Drawer.styles.js.map +1 -1
  97. package/dist/components/EmptyState/EmptyState.css.d.ts +16 -0
  98. package/dist/components/EmptyState/EmptyState.d.ts +15 -0
  99. package/dist/components/EmptyState/EmptyState.js +37 -0
  100. package/dist/components/EmptyState/EmptyState.js.map +1 -0
  101. package/dist/components/EmptyState/EmptyState.styles.js +15 -0
  102. package/dist/components/EmptyState/EmptyState.styles.js.map +1 -0
  103. package/dist/components/EmptyState/index.d.ts +2 -0
  104. package/dist/components/EnvironmentChip/EnvironmentChip.css.d.ts +5 -0
  105. package/dist/components/EnvironmentChip/EnvironmentChip.d.ts +13 -5
  106. package/dist/components/EnvironmentChip/EnvironmentChip.js +14 -3
  107. package/dist/components/EnvironmentChip/EnvironmentChip.js.map +1 -1
  108. package/dist/components/EnvironmentChip/EnvironmentChip.styles.js +3 -2
  109. package/dist/components/EnvironmentChip/EnvironmentChip.styles.js.map +1 -1
  110. package/dist/components/EnvironmentChip/index.d.ts +2 -2
  111. package/dist/components/Field/Field.css.d.ts +0 -1
  112. package/dist/components/Field/Field.d.ts +11 -28
  113. package/dist/components/Field/Field.js +25 -36
  114. package/dist/components/Field/Field.js.map +1 -1
  115. package/dist/components/Field/Field.styles.js +2 -2
  116. package/dist/components/Field/Field.styles.js.map +1 -1
  117. package/dist/components/Field/index.d.ts +1 -1
  118. package/dist/components/Fieldset/Fieldset.d.ts +1 -0
  119. package/dist/components/Fieldset/Fieldset.js.map +1 -1
  120. package/dist/components/Fieldset/Fieldset.styles.js.map +1 -1
  121. package/dist/components/Grid/Grid.css.d.ts +22 -0
  122. package/dist/components/Grid/Grid.d.ts +21 -0
  123. package/dist/components/Grid/Grid.js +23 -0
  124. package/dist/components/Grid/Grid.js.map +1 -0
  125. package/dist/components/Grid/Grid.styles.js +28 -0
  126. package/dist/components/Grid/Grid.styles.js.map +1 -0
  127. package/dist/components/Grid/index.d.ts +2 -0
  128. package/dist/components/List/List.d.ts +1 -0
  129. package/dist/components/List/List.js.map +1 -1
  130. package/dist/components/Loader/Loader.d.ts +1 -1
  131. package/dist/components/Loader/Loader.js +6 -2
  132. package/dist/components/Loader/Loader.js.map +1 -1
  133. package/dist/components/Menu/Menu.d.ts +25 -1
  134. package/dist/components/Menu/Menu.js +1 -1
  135. package/dist/components/Menu/Menu.js.map +1 -1
  136. package/dist/components/Menu/Menu.styles.js.map +1 -1
  137. package/dist/components/MetricBar/MetricBar.css.d.ts +5 -0
  138. package/dist/components/MetricBar/MetricBar.d.ts +9 -1
  139. package/dist/components/MetricBar/MetricBar.js +38 -22
  140. package/dist/components/MetricBar/MetricBar.js.map +1 -1
  141. package/dist/components/MetricBar/MetricBar.styles.js +15 -10
  142. package/dist/components/MetricBar/MetricBar.styles.js.map +1 -1
  143. package/dist/components/Modal/Modal.d.ts +6 -0
  144. package/dist/components/Modal/Modal.js +25 -28
  145. package/dist/components/Modal/Modal.js.map +1 -1
  146. package/dist/components/Modal/Modal.styles.js +2 -1
  147. package/dist/components/Modal/Modal.styles.js.map +1 -1
  148. package/dist/components/NavRail/NavRail.css.d.ts +2 -0
  149. package/dist/components/NavRail/NavRail.d.ts +22 -7
  150. package/dist/components/NavRail/NavRail.js +79 -58
  151. package/dist/components/NavRail/NavRail.js.map +1 -1
  152. package/dist/components/NavRail/NavRail.styles.js +3 -2
  153. package/dist/components/NavRail/NavRail.styles.js.map +1 -1
  154. package/dist/components/NavRail/index.d.ts +1 -1
  155. package/dist/components/NumberInput/NumberInput.d.ts +9 -1
  156. package/dist/components/NumberInput/NumberInput.js +37 -31
  157. package/dist/components/NumberInput/NumberInput.js.map +1 -1
  158. package/dist/components/PageHeader/PageHeader.css.d.ts +1 -1
  159. package/dist/components/PageHeader/PageHeader.d.ts +3 -1
  160. package/dist/components/PageHeader/PageHeader.js +21 -23
  161. package/dist/components/PageHeader/PageHeader.js.map +1 -1
  162. package/dist/components/PageHeader/PageHeader.styles.js +1 -1
  163. package/dist/components/PageHeader/PageHeader.styles.js.map +1 -1
  164. package/dist/components/Pagination/Pagination.d.ts +5 -0
  165. package/dist/components/Pagination/Pagination.js.map +1 -1
  166. package/dist/components/Popover/Popover.d.ts +9 -1
  167. package/dist/components/Popover/Popover.js +7 -6
  168. package/dist/components/Popover/Popover.js.map +1 -1
  169. package/dist/components/Popover/Popover.styles.js.map +1 -1
  170. package/dist/components/PortalContainer/PortalContainer.d.ts +1 -0
  171. package/dist/components/PortalContainer/PortalContainer.js.map +1 -1
  172. package/dist/components/ProgressBar/ProgressBar.css.d.ts +3 -0
  173. package/dist/components/ProgressBar/ProgressBar.d.ts +5 -1
  174. package/dist/components/ProgressBar/ProgressBar.js +21 -7
  175. package/dist/components/ProgressBar/ProgressBar.js.map +1 -1
  176. package/dist/components/ProgressBar/ProgressBar.styles.js +6 -6
  177. package/dist/components/ProgressBar/ProgressBar.styles.js.map +1 -1
  178. package/dist/components/RadioCards/RadioCards.d.ts +8 -2
  179. package/dist/components/RadioCards/RadioCards.js +40 -44
  180. package/dist/components/RadioCards/RadioCards.js.map +1 -1
  181. package/dist/components/SaveBar/SaveBar.d.ts +6 -1
  182. package/dist/components/SaveBar/SaveBar.js +1 -2
  183. package/dist/components/SaveBar/SaveBar.js.map +1 -1
  184. package/dist/components/SaveBar/SaveBar.styles.js.map +1 -1
  185. package/dist/components/Select/Select.css.d.ts +2 -0
  186. package/dist/components/Select/Select.d.ts +32 -5
  187. package/dist/components/Select/Select.js +91 -62
  188. package/dist/components/Select/Select.js.map +1 -1
  189. package/dist/components/Select/Select.styles.js +3 -2
  190. package/dist/components/Select/Select.styles.js.map +1 -1
  191. package/dist/components/Skeleton/Skeleton.d.ts +2 -0
  192. package/dist/components/Skeleton/Skeleton.js +20 -19
  193. package/dist/components/Skeleton/Skeleton.js.map +1 -1
  194. package/dist/components/Stack/Stack.css.d.ts +4 -1
  195. package/dist/components/Stack/Stack.d.ts +7 -3
  196. package/dist/components/Stack/Stack.js.map +1 -1
  197. package/dist/components/Stack/Stack.styles.js +16 -23
  198. package/dist/components/Stack/Stack.styles.js.map +1 -1
  199. package/dist/components/StatCard/StatCard.d.ts +3 -0
  200. package/dist/components/StatCard/StatCard.js.map +1 -1
  201. package/dist/components/StatCard/StatCard.styles.js.map +1 -1
  202. package/dist/components/StatsGrid/StatsGrid.d.ts +3 -6
  203. package/dist/components/StatsGrid/StatsGrid.js +3 -7
  204. package/dist/components/StatsGrid/StatsGrid.js.map +1 -1
  205. package/dist/components/StatusBadge/StatusBadge.d.ts +3 -2
  206. package/dist/components/StatusBadge/StatusBadge.js.map +1 -1
  207. package/dist/components/Switch/Switch.d.ts +2 -1
  208. package/dist/components/Switch/Switch.js +27 -31
  209. package/dist/components/Switch/Switch.js.map +1 -1
  210. package/dist/components/Switcher/Switcher.css.d.ts +0 -1
  211. package/dist/components/Switcher/Switcher.d.ts +13 -1
  212. package/dist/components/Switcher/Switcher.js +35 -35
  213. package/dist/components/Switcher/Switcher.js.map +1 -1
  214. package/dist/components/Switcher/Switcher.styles.js +2 -2
  215. package/dist/components/Switcher/Switcher.styles.js.map +1 -1
  216. package/dist/components/Table/Table.css.d.ts +16 -1
  217. package/dist/components/Table/Table.d.ts +110 -13
  218. package/dist/components/Table/Table.js +214 -102
  219. package/dist/components/Table/Table.js.map +1 -1
  220. package/dist/components/Table/Table.styles.js +7 -6
  221. package/dist/components/Table/Table.styles.js.map +1 -1
  222. package/dist/components/Table/index.d.ts +1 -1
  223. package/dist/components/Tabs/Tabs.d.ts +23 -8
  224. package/dist/components/Tabs/Tabs.js +1 -1
  225. package/dist/components/Tabs/Tabs.js.map +1 -1
  226. package/dist/components/Tabs/Tabs.styles.js.map +1 -1
  227. package/dist/components/Tabs/index.d.ts +1 -1
  228. package/dist/components/Tag/Tag.css.d.ts +33 -0
  229. package/dist/components/Tag/Tag.d.ts +5 -2
  230. package/dist/components/Tag/Tag.js +23 -6
  231. package/dist/components/Tag/Tag.js.map +1 -1
  232. package/dist/components/Tag/Tag.styles.js +12 -1
  233. package/dist/components/Tag/Tag.styles.js.map +1 -1
  234. package/dist/components/Tag/index.d.ts +1 -1
  235. package/dist/components/TextInput/TextInput.d.ts +13 -2
  236. package/dist/components/TextInput/TextInput.js +45 -48
  237. package/dist/components/TextInput/TextInput.js.map +1 -1
  238. package/dist/components/Textarea/Textarea.css.d.ts +2 -0
  239. package/dist/components/Textarea/Textarea.d.ts +5 -2
  240. package/dist/components/Textarea/Textarea.js +37 -37
  241. package/dist/components/Textarea/Textarea.js.map +1 -1
  242. package/dist/components/Textarea/Textarea.styles.js +3 -2
  243. package/dist/components/Textarea/Textarea.styles.js.map +1 -1
  244. package/dist/components/ThemeMenu/ThemeMenu.d.ts +13 -0
  245. package/dist/components/ThemeMenu/ThemeMenu.js +52 -0
  246. package/dist/components/ThemeMenu/ThemeMenu.js.map +1 -0
  247. package/dist/components/ThemeMenu/index.d.ts +2 -0
  248. package/dist/components/ThemePicker/ThemePicker.d.ts +9 -1
  249. package/dist/components/ThemePicker/ThemePicker.js +3 -1
  250. package/dist/components/ThemePicker/ThemePicker.js.map +1 -1
  251. package/dist/components/TimeInput/TimeInput.d.ts +10 -0
  252. package/dist/components/TimeInput/TimeInput.js +29 -0
  253. package/dist/components/TimeInput/TimeInput.js.map +1 -0
  254. package/dist/components/TimeInput/index.d.ts +2 -0
  255. package/dist/components/ToggleGroup/ToggleGroup.d.ts +30 -10
  256. package/dist/components/ToggleGroup/ToggleGroup.js +60 -59
  257. package/dist/components/ToggleGroup/ToggleGroup.js.map +1 -1
  258. package/dist/components/ToggleGroup/ToggleGroup.styles.js.map +1 -1
  259. package/dist/components/ToggleGroup/index.d.ts +1 -1
  260. package/dist/components/Tooltip/Tooltip.css.d.ts +0 -1
  261. package/dist/components/Tooltip/Tooltip.d.ts +9 -5
  262. package/dist/components/Tooltip/Tooltip.js +9 -9
  263. package/dist/components/Tooltip/Tooltip.js.map +1 -1
  264. package/dist/components/Tooltip/Tooltip.styles.js +2 -2
  265. package/dist/components/Tooltip/Tooltip.styles.js.map +1 -1
  266. package/dist/components/TopBar/TopBar.styles.js.map +1 -1
  267. package/dist/components/UserMenu/UserMenu.d.ts +4 -3
  268. package/dist/components/UserMenu/UserMenu.js.map +1 -1
  269. package/dist/examples/Crm.css.d.ts +3 -0
  270. package/dist/examples/ExampleShell.d.ts +28 -0
  271. package/dist/examples/Expenses.css.d.ts +2 -0
  272. package/dist/examples/HiringTracker.css.d.ts +13 -0
  273. package/dist/examples/SalesPipeline.css.d.ts +11 -0
  274. package/dist/foundations/Foundations.css.d.ts +1 -1
  275. package/dist/index.d.ts +6 -0
  276. package/dist/index.js +51 -45
  277. package/dist/styles/input.css.d.ts +8 -0
  278. package/dist/styles/input.styles.js +3 -2
  279. package/dist/styles/input.styles.js.map +1 -1
  280. package/dist/styles/shared.css.d.ts +5 -0
  281. package/dist/styles/shared.styles.js.map +1 -1
  282. package/dist/styles.css +1 -1
  283. package/dist/theme/fontSize.d.ts +4 -4
  284. package/dist/theme/fontSize.js +8 -23
  285. package/dist/theme/fontSize.js.map +1 -1
  286. package/dist/theme/htmlSetting.d.ts +14 -0
  287. package/dist/theme/htmlSetting.js +33 -0
  288. package/dist/theme/htmlSetting.js.map +1 -0
  289. package/dist/theme/theme.d.ts +4 -4
  290. package/dist/theme/theme.js +18 -33
  291. package/dist/theme/theme.js.map +1 -1
  292. package/dist/tokens/index.d.ts +0 -2
  293. package/dist/tokens.js +1 -2
  294. package/package.json +6 -2
  295. package/skills/back-office-kit/SKILL.md +27 -14
  296. package/skills/back-office-kit/references/artifact-template.html +1 -0
  297. package/skills/back-office-kit/references/components.md +482 -251
  298. package/skills/back-office-kit/references/install.md +27 -4
  299. package/skills/back-office-kit/references/migrate.md +58 -2
  300. package/skills/back-office-kit/references/patterns.md +129 -33
  301. package/skills/back-office-kit/references/testing.md +26 -22
  302. package/dist/tokens/sprinkles.css.d.ts +0 -38
  303. package/dist/tokens/sprinkles.styles.js +0 -349
  304. package/dist/tokens/sprinkles.styles.js.map +0 -1
@@ -6,11 +6,30 @@
6
6
  npm install --save-exact @15gifts/back-office-kit
7
7
  # Use the same lucide-react version as the library, so the app doesn't bundle two copies:
8
8
  npm install --save-exact lucide-react@$(npm view @15gifts/back-office-kit dependencies.lucide-react)
9
+ # If the app has forms (most do): react-hook-form, pinned exactly.
10
+ # Pick the newest 7.x release that's at least two weeks old (`npm view react-hook-form time`).
11
+ npm install --save-exact react-hook-form@<version>
9
12
  ```
10
13
 
11
- The package is public on npm. In Humara repos whose `.npmrc` routes the `@15gifts` scope to our private registry, it comes through that registry's npm upstream, so no extra setup is needed. `react` and `react-dom` 19 are peer dependencies. No Vanilla Extract or bundler plugin is needed, because the package ships compiled CSS.
14
+ The package is public on npm. In Humara repos whose `.npmrc` routes the `@15gifts` scope to our private registry, it comes through that registry's npm upstream, so no extra setup is needed. No Vanilla Extract or bundler plugin is needed, because the package ships compiled CSS.
12
15
 
13
- **index.html**: add the fonts to `<head>`:
16
+ - **Peer dependencies:** `react` and `react-dom` `^19.0.0`. The app installs them; the kit never bundles its own React.
17
+ - **lucide-react:** the kit pins an exact version (currently `1.68.0`). Install that same version in the app, then check `npm ls lucide-react` lists one version. A second copy bloats the bundle.
18
+
19
+ **Fonts.** The kit needs **Poppins** 400, 500 and 600, and **JetBrains Mono** 400 and 500. Its font stacks name the families `'Poppins'` and `'JetBrains Mono'`, so any source that registers those names works.
20
+
21
+ Self-hosted (no request to Google), with pinned `@fontsource/poppins` and `@fontsource/jetbrains-mono`:
22
+
23
+ ```ts
24
+ // src/main.tsx, before the kit's styles
25
+ import '@fontsource/poppins/400.css'
26
+ import '@fontsource/poppins/500.css'
27
+ import '@fontsource/poppins/600.css'
28
+ import '@fontsource/jetbrains-mono/400.css'
29
+ import '@fontsource/jetbrains-mono/500.css'
30
+ ```
31
+
32
+ Or from Google Fonts, in **index.html** `<head>`:
14
33
 
15
34
  ```html
16
35
  <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -34,7 +53,7 @@ applyStoredFontSize() // reads localStorage, defaults to 'md' (14px body text)
34
53
  createRoot(document.getElementById('root')!).render(<App />)
35
54
  ```
36
55
 
37
- The library CSS lives in the `bok` cascade layer, so **unlayered** app CSS always wins without specificity battles. Delete any CSS reset or global body styles that fight it (the library sets `body` background, colour and font).
56
+ The library CSS lives in the `bok` cascade layer, so **unlayered** app CSS always wins without specificity battles. That includes the app's resets: an unlayered `button { color: inherit }` beats the kit's button colours. Move resets into a layer before `bok` ([migrate.md](migrate.md#keep-app-resets-below-the-kit)); delete global `body` styles (the library sets `body` background, colour and font).
38
57
 
39
58
  **If the app uses cascade layers** (Mantine's layered CSS, Tailwind v4, its own `@layer`), declare the order once, before any other CSS, with `bok` after resets and other UI libraries and before the app:
40
59
 
@@ -50,7 +69,7 @@ Otherwise another library's element styles (e.g. Mantine's `button { font: inher
50
69
 
51
70
  - Themes: `light`, `dark`, `sand`, and `system` (follows the OS).
52
71
  - `setTheme('dark')` sets `<html data-theme="dark">` and remembers it. `useTheme()` returns `[theme, setTheme]` for UI such as `ThemePicker`.
53
- - To force a theme for a section, put `data-theme="dark"` on any wrapper element.
72
+ - To force a theme for a section, put `data-theme="light"`, `"dark"` or `"sand"` on any wrapper element. `system` only works on `<html>`.
54
73
  - `getColorScheme()` / `useColorScheme()` return the resolved `'light' | 'dark'` (`system` follows the OS and `sand` is light). Use them to drive another library's dark mode while both coexist, e.g. Mantine: `<MantineProvider forceColorScheme={useColorScheme()}>`.
55
74
  - The choice is saved under `THEME_STORAGE_KEY` (`bok-theme`). To keep users' choices from an older theme setting, pass `migrate`: `applyStoredTheme({ migrate: () => readOldSetting() })`. It runs only when nothing is saved yet, and the result is saved.
56
75
 
@@ -77,6 +96,7 @@ export const ViewRuns = () => <Button render={<Link to="/runs" />}>View runs</Bu
77
96
  ## Your own styles
78
97
 
79
98
  - **Colours, fonts, shadows:** CSS variables only, never raw values: `--bok-bg`, `--bok-surface`, `--bok-surface-sunken`, `--bok-border`, `--bok-ink`, `--bok-ink-muted`, `--bok-primary`, `--bok-accent`, `--bok-accent-ink`, `--bok-success`, `--bok-warning`, `--bok-danger`, `--bok-font-sans`, `--bok-font-mono`, `--bok-shadow-md`, and so on. The base tones (`--bok-accent`, `--bok-success`, …) are fills; text uses the `-ink` variants.
99
+ - **Scale:** the kit's sizes are CSS variables too: `--bok-space-*`, `--bok-radius-*`, `--bok-font-size-*`, `--bok-font-weight-*`, `--bok-line-height-*` (list in [migrate.md](migrate.md#scale-variables)).
80
100
  - **Sizes:** rem for layout (spacing on a 0.25rem grid: `0.5rem`, `0.75rem`, `1rem`, `1.5rem`, `2rem`; radius `0.5rem` for controls, `0.75rem`–`1rem` for cards), and em for things that should follow their own text (icon sizes `1em`, gaps inside a button). No px except 1px borders. This keeps the global text-size setting working.
81
101
 
82
102
  Vanilla Extract apps can import typed tokens instead:
@@ -168,6 +188,7 @@ Artifacts are single HTML pages with no bundler. They can load scripts only from
168
188
  "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@19.3.1/+esm",
169
189
  "react-dom/client": "https://cdn.jsdelivr.net/npm/react-dom@19.3.1/client/+esm",
170
190
  "htm": "https://cdn.jsdelivr.net/npm/htm@3.1.1/+esm",
191
+ "react-hook-form": "https://cdn.jsdelivr.net/npm/react-hook-form@7.91.0/+esm",
171
192
  "lucide-react": "https://cdn.jsdelivr.net/npm/lucide-react@<library's lucide version>/+esm",
172
193
  "@15gifts/back-office-kit": "https://cdn.jsdelivr.net/npm/@15gifts/back-office-kit@<version>/dist/browser/back-office-kit.js"
173
194
  }
@@ -177,6 +198,8 @@ Artifacts are single HTML pages with no bundler. They can load scripts only from
177
198
 
178
199
  Use the lucide-react version from `npm view @15gifts/back-office-kit@<version> dependencies.lucide-react`. jsdelivr resolves its React to the same URL as above, so there's still one React.
179
200
 
201
+ `react-hook-form` is for forms, as in apps (checked: it shares the page's React). Drop the line if the artifact has no form.
202
+
180
203
  4. **Write the UI with `htm`, not JSX.** There's no compiler. `htm` gives JSX-like templates: `` html`<${Button} variant="secondary">Cancel</${Button}>` `` (bind it with `htm.bind(createElement)`). Components, props, `render` links and theming all work exactly as in an app.
181
204
  5. **Theme:** set `<html data-theme="light">` (or `dark`, `sand`, `system`), or call `setTheme`. Text size works too, via `data-font-size` or `setFontSize`.
182
205
 
@@ -5,13 +5,68 @@ Work page by page. Keep each step shippable.
5
5
  ## Steps
6
6
 
7
7
  1. **Install and wire up** ([install.md](install.md)). Import `@15gifts/back-office-kit/styles.css` once and add the fonts.
8
- 2. **Remove the conflicting globals:** CSS resets, `body` font/colour/background, and Tailwind preflight (`corePlugins: { preflight: false }`) if Tailwind stays for layout.
8
+ 2. **Tame the conflicting globals:** move CSS resets into a layer below the kit ([below](#keep-app-resets-below-the-kit)), delete `body` font/colour/background, and turn off Tailwind preflight (`corePlugins: { preflight: false }`) if Tailwind stays for layout.
9
9
  3. **Swap the shell first** (`AppShell`, `NavRail`, `TopBar`, `PageHeader`). It gives the biggest visual win.
10
10
  4. **Swap leaf components** using the table below, one page at a time.
11
11
  5. **Replace colours.** Search for hex/rgb literals and colour utility classes, and map them to tokens (below).
12
12
  6. **Delete dead CSS**, and uninstall the old UI library once nothing imports it.
13
13
  7. **Check** each migrated page in light and dark (`setTheme('dark')`), and tab through it with the keyboard.
14
14
 
15
+ ## Keep app resets below the kit
16
+
17
+ The kit's CSS is in `@layer bok`, and unlayered CSS beats any layer. So an app reset such as `button { color: inherit }` or a global `:focus-visible { box-shadow: … }` overrides kit components. Don't delete the resets: layer them.
18
+
19
+ 1. A file imported **before** the kit's CSS declares the order:
20
+
21
+ ```css
22
+ /* src/layers.css */
23
+ @layer reset, bok;
24
+ ```
25
+
26
+ ```ts
27
+ // src/main.tsx
28
+ import './layers.css'
29
+ import '@15gifts/back-office-kit/styles.css'
30
+ ```
31
+
32
+ 2. Wrap the app's resets in that layer:
33
+
34
+ ```css
35
+ @layer reset {
36
+ button {
37
+ color: inherit;
38
+ font: inherit;
39
+ }
40
+ :focus-visible {
41
+ box-shadow: 0 0 0 2px var(--bok-focus-ring);
42
+ }
43
+ }
44
+ ```
45
+
46
+ `bok` now beats the resets, while the app's other, unlayered CSS still beats `bok`. With more libraries, list every layer once, e.g. `@layer reset, mantine, bok, app;`.
47
+
48
+ ## Scale variables
49
+
50
+ For plain CSS (CSS modules, Sass, Tailwind arbitrary values), the kit's scale is on `:root` as CSS variables, from the same source as the components:
51
+
52
+ | Group | Variables |
53
+ | ----------- | ------------------------------------------------------------------------------------------------- |
54
+ | Spacing | `--bok-space-0` … `--bok-space-12` (4px steps; `--bok-space-0-5` is 2px, `--bok-space-4` is 1rem) |
55
+ | Radius | `--bok-radius-sm`, `-md`, `-lg`, `-xl`, `-2xl`, `-full` |
56
+ | Font size | `--bok-font-size-xs`, `-sm`, `-md` (body), `-lg`, `-xl`, `-2xl`, `-3xl` |
57
+ | Font weight | `--bok-font-weight-normal`, `-medium`, `-semibold` |
58
+ | Line height | `--bok-line-height-tight`, `-normal` |
59
+
60
+ Half steps use a dash: `--bok-space-0-5`, `--bok-space-1-5`, `--bok-space-2-5`. Sizes are rem, so they follow the text-size setting.
61
+
62
+ ```css
63
+ .panel {
64
+ padding: var(--bok-space-4);
65
+ border-radius: var(--bok-radius-xl);
66
+ font-size: var(--bok-font-size-sm);
67
+ }
68
+ ```
69
+
15
70
  ## Component mapping
16
71
 
17
72
  | From (shadcn / MUI / Mantine / hand-rolled) | To |
@@ -25,6 +80,7 @@ Work page by page. Keep each step shippable.
25
80
  | `Textarea`, `TextField multiline` | `Textarea` |
26
81
  | `Select`, native `<select>`, `Autocomplete` | `Select` (fixed list), `Combobox` (filterable), `Autocomplete` (free text + suggestions) |
27
82
  | `Switch`, `Checkbox`, `RadioGroup` | `Switch`, `Checkbox`, `RadioCards` (or `ToggleGroup` for 2–4 short options) |
83
+ | Date range pickers | `DateRangePicker` (quick ranges built in) |
28
84
  | `Tabs` | `Tabs items=[…]` (supports `count`) |
29
85
  | `Dialog`, `Modal` | `Modal` (centred, blocking) or `Drawer` (side panel) |
30
86
  | `DropdownMenu`, `Menu` | `Menu` (`items`, `'separator'`) |
@@ -73,7 +129,7 @@ Library components follow ARIA patterns closely, so tests written against older
73
129
  | Component | Library behaviour | Update tests to |
74
130
  | ----------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
75
131
  | Alert | `info`/`success` are `role="status"`; `warning`/`danger` are `role="alert"` | query by the role for the tone |
76
- | Loader | `role="status"`, named "Loading" (or `label`) | `getByRole('status')`, not `progressbar` |
132
+ | Loader | `role="status"` with visually hidden text "Loading" (or `label`) | `getByRole('status')`, not `progressbar` |
77
133
  | Button `loading` | `aria-disabled="true"` + `aria-busy`, not native `disabled` (keeps focus) | `toHaveAttribute('aria-disabled', 'true')` |
78
134
  | Switch | `role="switch"` plus a hidden native checkbox for forms | `getByRole('switch', { name })`, not `getByLabelText` |
79
135
  | TextInput `maxLength` + `showCount` | hard limit: typing stops at the limit | for "allow over, show red" use `countLimit` (soft limit, sets `data-over`) |
@@ -29,9 +29,9 @@ export function Layout({
29
29
  }) {
30
30
  const { pathname } = useLocation()
31
31
  const nav = [
32
- { label: 'Dashboard', to: '/', icon: <LayoutDashboard size="1.43em" aria-hidden /> },
33
- { label: 'Runs', to: '/runs', icon: <Activity size="1.43em" aria-hidden /> },
34
- { label: 'Settings', to: '/settings', icon: <Settings size="1.43em" aria-hidden /> },
32
+ { label: 'Dashboard', to: '/', icon: <LayoutDashboard size="1.25rem" aria-hidden /> },
33
+ { label: 'Runs', to: '/runs', icon: <Activity size="1.25rem" aria-hidden /> },
34
+ { label: 'Settings', to: '/settings', icon: <Settings size="1.25rem" aria-hidden /> },
35
35
  ]
36
36
  return (
37
37
  <AppShell
@@ -58,6 +58,14 @@ export function Layout({
58
58
  }
59
59
  ```
60
60
 
61
+ **More than about six sections?** Group them: an `items` entry can be `{ group: 'Set up', items: [...] }`. Groups show their heading when the rail is expanded and a divider when it's collapsed. Use groups for every item or none.
62
+
63
+ **Rail footer.** `footer` sits at the bottom (pass a function to vary it with `expanded`): the `UserMenu`, and optionally small app-wide controls such as a `ThemeMenu` (an icon button that opens a theme menu, fits the collapsed rail) or service-status lines. A ghost `Button` in the rail takes the rail's colours. Return less (or nothing) when collapsed, since the rail is only icon-wide.
64
+
65
+ **Skip link.** `AppShell` renders a "Skip to content" link as the first Tab stop, which moves focus to `<main>` (`skipLinkLabel` changes the text). Don't add your own.
66
+
67
+ **Environment.** `EnvironmentChip` picks its colour from the name (production/live red, staging/UAT/QA/test amber-lime, dev/ephemeral/preview blue, anything else grey). Pass the real environment name; there's no colour prop.
68
+
61
69
  The rail starts collapsed and remembers the user's choice in localStorage (`persistKey`, default `'bok-rail-expanded'`; `null` turns it off). Pass `expanded` and `onExpandedChange` to control it yourself; nothing is stored then.
62
70
 
63
71
  **Switchers in the trail.** A crumb's `label` can be any control. For a customer or branch switcher, pass a `Switcher` (`size="sm"`) as the label with `current: false`: `{ label: <Switcher label="Customer" size="sm" value={id} items={customers} onSelect={…} />, current: false }`.
@@ -68,7 +76,7 @@ The rail starts collapsed and remembers the user's choice in localStorage (`pers
68
76
 
69
77
  **No router?** Use `href` instead of `render`: `items={[{ label: 'Runs', href: '/runs', icon, active: true }]}`, `brandHref="/"`, and `{ label: 'Home', href: '/' }` in `Breadcrumbs`.
70
78
 
71
- `AppShell` already spaces its direct children (24px gap) and caps the content width. Put page sections straight inside it, without a wrapping `Stack`. Pass `contained={false}` for full-width content.
79
+ `AppShell` already spaces its direct children (1.5rem gap) and caps the content width. Put page sections straight inside it, without a wrapping `Stack`. Pass `contained={false}` for full-width content.
72
80
 
73
81
  Each page then starts with a `PageHeader` (one h1, an optional facts line, and the page's primary action at the top right).
74
82
 
@@ -76,8 +84,12 @@ Each page then starts with a `PageHeader` (one h1, an optional facts line, and t
76
84
 
77
85
  ```tsx
78
86
  <PageHeader title="Runs" facts={[`${runs.length} runs`]} actions={<Button icon={<Play size="1em" aria-hidden />}>Start run</Button>} />
79
- <Stack direction="row" gap="4">{/* filters: Select / TextInput with labels */}</Stack>
87
+ <Stack direction="row" gap="4" wrap>
88
+ {/* filters, each with a label: Select, TextInput, Combobox */}
89
+ <DateRangePicker label="Started" value={range} onValueChange={setRange} />
90
+ </Stack>
80
91
  <Table
92
+ aria-label="Runs"
81
93
  columns={[
82
94
  { key: 'run', header: 'Run', render: (r) => <>{r.startedAt}<Table.Secondary>{r.id}</Table.Secondary></> },
83
95
  { key: 'status', header: 'Status', render: (r) => <StatusBadge status={r.status} /> },
@@ -95,6 +107,8 @@ Each page then starts with a `PageHeader` (one h1, an optional facts line, and t
95
107
 
96
108
  - Status always goes through `StatusBadge`. IDs and codes go in `Table.Secondary` (mono).
97
109
  - Use `loading` for skeleton rows, never a spinner over the table.
110
+ - Wide tables scroll horizontally inside themselves. Don't wrap `Table` in your own overflow container.
111
+ - `DateRangePicker` passes the chosen quick range as `{ preset }`, so a preset like "Past hour" can switch on a live mode. Build custom quick ranges with `lastDuration`, `today`, `yesterday`, `thisMonth` or `getDefaultPresets`.
98
112
 
99
113
  ## 3. Dashboard
100
114
 
@@ -120,40 +134,118 @@ Each page then starts with a `PageHeader` (one h1, an optional facts line, and t
120
134
 
121
135
  ## 5. Settings form
122
136
 
137
+ Build every form with **react-hook-form**: it owns values, dirty state and validation; library fields render them. This recipe is tested in the library's Storybook (`Recipes/React Hook Form`).
138
+
123
139
  ```tsx
124
- <PageHeader title="Recommendation settings" />
125
- <Fieldset legend="Matching" description="How products are picked for a shopper.">
126
- <Select
127
- label="Strategy"
128
- options={[{ value: 'best', label: 'Best match' }, { value: 'cheapest', label: 'Cheapest' }]}
129
- value={strategy}
130
- onValueChange={setStrategy}
131
- />
132
- <NumberInput label="Results to show" min={1} max={10} />
133
- <Switch label="Include out-of-stock products" />
134
- <RadioCards
135
- label="Tone"
136
- options={[
137
- { value: 'friendly', label: 'Friendly', description: 'Warm, casual phrasing' },
138
- { value: 'expert', label: 'Expert', description: 'Precise and technical' },
139
- ]}
140
- />
141
- </Fieldset>
142
- <Fieldset legend="Copy">
143
- <TextInput label="Greeting" maxLength={80} showCount error={errors.greeting?.message} />
144
- <Textarea label="Disclaimer" description="Shown under every recommendation." />
145
- </Fieldset>
146
- <SaveBar changes={dirtyCount} onSave={save} onDiscard={reset} saving={isSaving} />
140
+ import { Controller, useForm } from 'react-hook-form'
141
+ import {
142
+ Fieldset,
143
+ NumberInput,
144
+ PageHeader,
145
+ SaveBar,
146
+ Select,
147
+ Switch,
148
+ TextInput,
149
+ } from '@15gifts/back-office-kit'
150
+
151
+ interface Settings {
152
+ greeting: string
153
+ strategy: string | null
154
+ results: number | null
155
+ outOfStock: boolean
156
+ }
157
+
158
+ export function RecommendationSettings({ settings, save }: Props) {
159
+ const { register, control, handleSubmit, reset, formState } = useForm<Settings>({
160
+ defaultValues: settings,
161
+ })
162
+ const { errors, dirtyFields, isSubmitting } = formState
163
+ // handleSubmit validates, then calls save. `void` because it returns a promise (lint rule).
164
+ const submit = () => void handleSubmit((values) => save(values))()
165
+
166
+ return (
167
+ <form
168
+ noValidate
169
+ onSubmit={(event) => {
170
+ event.preventDefault()
171
+ submit()
172
+ }}
173
+ >
174
+ <PageHeader title="Recommendation settings" />
175
+ <Fieldset legend="Matching" description="How products are picked for a shopper.">
176
+ <TextInput
177
+ label="Greeting"
178
+ required
179
+ error={errors.greeting?.message}
180
+ {...register('greeting', { required: 'Enter a greeting' })}
181
+ />
182
+ <Controller
183
+ name="strategy"
184
+ control={control}
185
+ render={({ field }) => (
186
+ <Select
187
+ label="Strategy"
188
+ options={[
189
+ { value: 'best', label: 'Best match' },
190
+ { value: 'cheapest', label: 'Cheapest' },
191
+ ]}
192
+ value={field.value}
193
+ onValueChange={field.onChange}
194
+ />
195
+ )}
196
+ />
197
+ <Controller
198
+ name="results"
199
+ control={control}
200
+ render={({ field }) => (
201
+ <NumberInput
202
+ label="Results to show"
203
+ min={1}
204
+ max={10}
205
+ value={field.value}
206
+ onValueChange={(value) => field.onChange(value)}
207
+ />
208
+ )}
209
+ />
210
+ <Controller
211
+ name="outOfStock"
212
+ control={control}
213
+ render={({ field }) => (
214
+ <Switch
215
+ label="Include out-of-stock products"
216
+ checked={field.value}
217
+ onCheckedChange={(checked) => field.onChange(checked)}
218
+ />
219
+ )}
220
+ />
221
+ </Fieldset>
222
+ <SaveBar
223
+ changes={Object.keys(dirtyFields).length}
224
+ onSave={submit}
225
+ onDiscard={() => reset()}
226
+ saving={isSubmitting}
227
+ />
228
+ </form>
229
+ )
230
+ }
147
231
  ```
148
232
 
149
233
  - Every input takes `label`, `description`, `error`, `required` and `disabled` directly. Don't wrap it in your own label.
150
- - react-hook-form: `register` works on TextInput, Textarea, DateTimeInput and ColorPicker. Use `<Controller>` for the rest: `value`/`onValueChange` on Select, Combobox, RadioCards, NumberInput and ToggleGroup, and `checked`/`onCheckedChange` on Switch and Checkbox.
151
- - `ToggleGroup` suits 2–4 short mutually exclusive options. Use `Select` for longer lists, and `Combobox` when the list needs filtering.
234
+ - `register` works on TextInput, Textarea, DateTimeInput and ColorPicker (they forward `ref`, `name`, `onChange` and `onBlur`). Use `<Controller>` for the rest: `value`/`onValueChange` on Select, Combobox, Autocomplete, RadioCards, NumberInput, ToggleGroup and DateRangePicker, and `checked`/`onCheckedChange` on Switch and Checkbox.
235
+ - Show validation messages through each field's `error` prop (`errors.x?.message`). Use a `Alert` above the form only for errors that aren't about one field (e.g. the save request failed).
236
+ - Don't keep form values in `useState`, and don't add another form library.
237
+ - Required fields: put `required` on the field (it adds the asterisk, `aria-required` and browser validation). Required fields are always marked with `*`; optional fields have no mark. react-hook-form does the validation, so keep `required` on the fields (for the asterisk and `aria-required`), put the rule in `register`/`rules`, and add `noValidate` to the `<form>`.
238
+ - **Don't nest cards.** A top-level `Fieldset` is already a card, so don't put Fieldsets inside a `Card` (or Cards inside a Fieldset). A `Drawer` is not a card: Cards and Fieldsets inside it are fine.
239
+ - **Forms in a Drawer:** pass `onSubmit` to `Drawer`. It wraps the body and footer in one `<form>`, so a `type="submit"` footer button submits it: `<Drawer onSubmit={handleSubmit(save)} footer={<Button type="submit">Save</Button>}>`. Or put your own `<form id="edit-run">` in the body and give the footer button `form="edit-run"`.
240
+ - **Labelling from outside:** every input takes `label`; use it. When the label must live elsewhere (a table header, a sentence), pass `id` to the kit input, leave out `label`, and point a native `<label htmlFor={id}>` at it.
241
+ - **Layout wrappers:** `Stack` passes native `div` props through (`id`, `aria-*`, `data-*`, `style`, event handlers), so use it instead of a styled `div`.
242
+ - `ToggleGroup` suits 2–4 short mutually exclusive options (`size="sm"` in toolbars and filter rows). Use `Select` for longer lists, and `Combobox` when the list needs filtering.
152
243
  - **Where does Save go?**
153
244
  - `SaveBar`: settings pages with many fields, where edits accumulate and Save/Discard must stay reachable while scrolling. Show the change count.
154
245
  - A primary `Button` in `PageHeader` `actions`: short pages where Save is the page's one main action and is always visible.
155
246
  - Footer buttons: forms inside a `Modal` or `Drawer`.
156
247
  - Use one of these per page, never both.
248
+ - Appearance settings: `ThemePicker` (it drives the app theme by itself), and a `ToggleGroup` of `sm`/`md`/`lg` over `useFontSize()` for text size.
157
249
 
158
250
  ## 6. Conversation view
159
251
 
@@ -193,6 +285,10 @@ const messages: ChatMessage[] = turns.map((turn) => ({
193
285
  ## Feedback and empty states
194
286
 
195
287
  - Page-level messages: `Alert` (`tone` info, success, warning or danger). Danger and warning are announced.
196
- - Inline empty lists: `EmptyLine`, or the `empty` prop of `Table`/`List`.
197
- - Loading: `Skeleton` for content placeholders, `Loader` inside buttons and small regions, and `Button loading` while saving.
198
- - Labels and filters: `Chip` for toggleable filters, `Tag` for small mono labels, and `Badge` for neutral or tone counts.
288
+ - Inline empty lists: `EmptyLine`, `Table`'s `empty` prop, or `List`'s `emptyState`.
289
+ - Loading: `Skeleton` for content placeholders, `Loader` inside buttons and small regions, and `Button loading` while saving. Numeric `width`/`height`/`size` are px at the 16px base, converted to rem; prefer rem/em strings.
290
+ - Labels and filters: `Chip` for toggleable filters (`static` for a display-only chip showing a choice, `pressed` ticks it), `Tag` for small mono labels (`tone` for meaning), and `Badge` for neutral or tone counts (`mono` for IDs and versions).
291
+
292
+ ## App CSS next to the kit
293
+
294
+ The kit's CSS is in `@layer bok`, so unlayered app CSS wins. Keep app resets in a lower layer (`@layer reset, bok;` imported before the kit's CSS), and use the `--bok-*` colour and scale variables in your own CSS. Recipe: [migrate.md](migrate.md#keep-app-resets-below-the-kit).
@@ -16,7 +16,7 @@ if (typeof window !== 'undefined' && !window.PointerEvent) {
16
16
  }
17
17
  ```
18
18
 
19
- This was checked against jsdom 26.1, where every component in the library worked with only this shim, including Select, Combobox, Menu, Tabs, Modal, Drawer, Switcher and Tooltip. `useTheme` and `ThemePicker` work without `matchMedia`, because the library checks for it first. If an older jsdom, or another library, reports a missing `ResizeObserver`, `matchMedia` or `scrollIntoView`, stub that API in the same file.
19
+ This was checked against jsdom 26.1, where every component in the library worked with only this shim, including Select, Combobox, Menu, Tabs, Modal, Drawer, Switcher and Tooltip. `useTheme`, `ThemePicker` and `DateRangePicker` work without `matchMedia`, and `Table` without `ResizeObserver`, because the library checks for them first. If an older jsdom, or another library, reports a missing `ResizeObserver`, `matchMedia` or `scrollIntoView`, stub that API in the same file.
20
20
 
21
21
  Animations don't run in jsdom, so popups open and close straight away. You still need `findBy…` or `waitFor`, because Base UI updates the DOM after the event.
22
22
 
@@ -31,7 +31,7 @@ await waitFor(() => expect(screen.queryByRole('listbox')).not.toBeInTheDocument(
31
31
 
32
32
  ## Portals
33
33
 
34
- Select, Combobox, Autocomplete, Menu (and submenus), Switcher, Popover, Tooltip, Modal and Drawer render their popups into `document.body`, or into the nearest `PortalContainer` (Modal and Drawer are one for popups opened inside them). That means `within(container)` and Storybook's `canvas` won't find them.
34
+ Select, Combobox, Autocomplete, DateRangePicker, Menu (and submenus), Switcher, Popover, Tooltip, Modal and Drawer render their popups into `document.body`, or into the nearest `PortalContainer` (Modal and Drawer are one for popups opened inside them). That means `within(container)` and Storybook's `canvas` won't find them.
35
35
 
36
36
  - Testing Library: `screen.getByRole(...)`, or `within(document.body)`.
37
37
  - Storybook: `screen` from `storybook/test`.
@@ -56,27 +56,28 @@ With `loadingLabel`, that text is announced while loading. `<Button disabled>` i
56
56
 
57
57
  ## Roles and queries
58
58
 
59
- `name` is the accessible name. Labels with a required marker have `*` hidden from assistive tech, so the name is just the label. `requiredIndicator="optional-note"` adds the note to the name, e.g. `'Objective (Optional)'`. `hideLabel` hides the label visually but keeps the name.
59
+ `name` is the accessible name. Labels with a required marker have `*` hidden from assistive tech, so the name is just the label. `hideLabel` hides the label visually but keeps the name.
60
60
 
61
61
  ### Inputs
62
62
 
63
- | Component | Query | Notes |
64
- | ------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65
- | TextInput | `getByRole('textbox', { name: label })` | |
66
- | Textarea | `getByRole('textbox', { name: label })` | |
67
- | NumberInput | `getByRole('textbox', { name: label })` | A `textbox`, not a `spinbutton`. Its step buttons are `button` "Decrease" and "Increase". |
68
- | DateTimeInput | `getByLabelText(/^Schedule for/)` | A native `datetime-local` input has no ARIA role. Use a regex, because the label text includes the `*` marker. |
69
- | ColorPicker | `getByRole('textbox', { name: label })` | The swatch is `getByLabelText(pickerLabel)` (default "Choose colour", so give each picker on a page its own name). An invalid colour shows the text "Not a colour". |
70
- | Select | `getByRole('combobox', { name: label })` | Open it, then `screen.getByRole('listbox')` and `screen.getByRole('option', { name })`. |
71
- | Combobox | `getByRole('combobox', { name: label })` | Type into it, then `screen.findByRole('option', { name })`. The Clear button is `button` "Clear", and the chevron is a `button` named by the label. |
72
- | Autocomplete | `getByRole('combobox', { name: label })` | Suggestions are `option`s. With `clearable`, it has a `button` named `clearLabel` ("Clear"). |
73
- | Checkbox | `getByRole('checkbox', { name: label })` | Use `aria-checked`, or `toBeChecked()`. A hidden native input is there for forms, so don't use `getByLabelText`. |
74
- | Switch | `getByRole('switch', { name: label })` | As for Checkbox. |
75
- | RadioCards | `getByRole('radiogroup', { name: label })` | Each card is `radio` named by its `label`. Its `description` is the radio's accessible description. |
76
- | ToggleGroup | `getByRole('group', { name: label })` | Options are `button`s with `aria-pressed`. |
77
- | Field | the control inside it, by its own role | The label names the control. `description` and `error` are its accessible description, and `error` also sets `aria-invalid="true"`. |
78
- | Fieldset | `getByRole('group', { name: legend })` | A native `<fieldset>`, but the legend is a `<div>` (Base UI's `Fieldset.Legend`) linked with `aria-labelledby`. Don't assert `tagName === 'LEGEND'`. `description` is the group's accessible description. |
79
- | ThemePicker | `getByRole('group', { name: 'Theme' })` | Native `radio`s: Light, Sand, Dark, System. |
63
+ | Component | Query | Notes |
64
+ | --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65
+ | TextInput | `getByRole('textbox', { name: label })` | |
66
+ | Textarea | `getByRole('textbox', { name: label })` | |
67
+ | NumberInput | `getByRole('textbox', { name: label })` | A `textbox`, not a `spinbutton`. Its step buttons are `button` "Decrease" and "Increase". |
68
+ | DateTimeInput | `getByLabelText(/^Schedule for/)` | A native `datetime-local` input has no ARIA role. Use a regex, because the label text includes the `*` marker. |
69
+ | ColorPicker | `getByRole('textbox', { name: label })` | The swatch is `getByLabelText(pickerLabel)` (default "Choose colour", so give each picker on a page its own name). An invalid colour shows the text "Not a colour". |
70
+ | Select | `getByRole('combobox', { name: label })` | Open it, then `screen.getByRole('listbox')` and `screen.getByRole('option', { name })`. |
71
+ | Combobox | `getByRole('combobox', { name: label })` | Type into it, then `screen.findByRole('option', { name })`. The Clear button is `button` "Clear", and the chevron is a `button` named by the label. |
72
+ | Autocomplete | `getByRole('combobox', { name: label })` | Suggestions are `option`s. With `clearable`, it has a `button` named `clearLabel` ("Clear"). |
73
+ | Checkbox | `getByRole('checkbox', { name: label })` | Use `aria-checked`, or `toBeChecked()`. A hidden native input is there for forms, so don't use `getByLabelText`. |
74
+ | Switch | `getByRole('switch', { name: label })` | As for Checkbox. |
75
+ | RadioCards | `getByRole('radiogroup', { name: label })` | Each card is `radio` named by its `label`. Its `description` is the radio's accessible description. |
76
+ | ToggleGroup | `getByRole('radiogroup', { name: label })` | Options are `radio`s named by their label. Use `toBeChecked()`. |
77
+ | DateRangePicker | `getByRole('button', { name: /^Date range/ })` | The trigger's name starts with the label. It opens a `dialog` with the calendar, a `list` named "Quick ranges" (`presetsLabel`) of preset `button`s, and "Apply" / "Cancel" buttons. `onValueChange` gets `(range, { preset })`. |
78
+ | Field | the control inside it, by its own role | The label names the control. `description` and `error` are its accessible description, and `error` also sets `aria-invalid="true"`. |
79
+ | Fieldset | `getByRole('group', { name: legend })` | A native `<fieldset>`, but the legend is a `<div>` (Base UI's `Fieldset.Legend`) linked with `aria-labelledby`. Don't assert `tagName === 'LEGEND'`. `description` is the group's accessible description. |
80
+ | ThemePicker | `getByRole('group', { name: 'Theme' })` | Native `radio`s: Light, Sand, Dark, System. |
80
81
 
81
82
  ### Overlays and menus
82
83
 
@@ -112,7 +113,7 @@ With `loadingLabel`, that text is announced while loading. `<Button disabled>` i
112
113
  | Component | Query | Notes |
113
114
  | -------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
114
115
  | Alert | `info`/`success`: `getByRole('status')`. `warning`/`danger`: `getByRole('alert')` | Use the role that matches the tone. The dismiss button is named `dismissLabel` ("Dismiss"). |
115
- | Loader | `getByRole('status', { name: 'Loading' })` | Not `progressbar`. With `label={null}` it's hidden from assistive tech. |
116
+ | Loader | `getByRole('status')`, then `toHaveTextContent('Loading')` | Not `progressbar`. The `label` is visually hidden text, not a name. With `label={null}` it's hidden from assistive tech. |
116
117
  | ProgressBar | `getByRole('progressbar')` | `aria-valuetext` gives the breakdown ("2 of 5: …"). |
117
118
  | MetricBar | `getByRole('meter')` | |
118
119
  | SaveBar | `getByRole('region', { name: 'Unsaved changes' })` | The count is `status` ("2 unsaved changes"). Buttons are "Discard" and "Save changes". Nothing renders when `changes` is 0. |
@@ -132,16 +133,19 @@ Library components have no `testId` prop. Pass `data-testid` (or any `data-*` /
132
133
  | ----------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
133
134
  | TextInput, Textarea, DateTimeInput, ColorPicker | the `<input>` / `<textarea>` | `fieldProps` for the field wrapper |
134
135
  | Checkbox, Switch | the `checkbox` / `switch` element | `fieldProps` |
135
- | RadioCards, ToggleGroup | the `radiogroup` / `group` | `fieldProps` |
136
+ | RadioCards, ToggleGroup | the `radiogroup` | `fieldProps` |
136
137
  | NumberInput | the wrapper `group` around the input and buttons | `fieldProps` |
137
138
  | Select | **dropped**, so use part props | `triggerProps` (the `combobox`), `popupProps` (the popup around the `listbox`), `fieldProps` |
138
139
  | Combobox, Autocomplete | **dropped**, so use part props | `inputProps` (the `combobox`), `popupProps`, `fieldProps` |
140
+ | DateRangePicker | **dropped**, so use part props | `triggerProps` (the `button`), `popupProps` (the `dialog`), `fieldProps` |
139
141
  | Menu | **dropped**, so use part props | `popupProps` (the `menu`). Each item takes `itemProps`, and so does each radio option. A submenu takes `itemProps` (its trigger) and `popupProps`. Put IDs for the trigger on the element you pass as `trigger`. |
140
142
  | UserMenu | the Menu (as above) | `triggerProps` (the button), `signOutProps` (the Sign out item) |
141
143
  | Switcher | n/a | `triggerProps` (the `combobox` trigger), `popupProps` (the `dialog`), `itemProps` on each item (the `option`) |
142
144
  | Tabs | the root `<div>` | `listProps` (the `tablist`). Each item takes `tabProps` (the `tab`) and `panelProps` (the `tabpanel`). |
143
145
  | Table | the `<table>` | `getRowProps={(row) => ({ 'data-testid': … })}` for each `<tr>`. `scrollRef` gives you the scrolling wrapper. |
144
146
  | Modal | the `dialog` | |
147
+ | Popover | **dropped**, so use part props | `popupProps` (the `dialog`). Put IDs for the trigger on the element you pass as `trigger`. |
148
+ | Tooltip | **dropped** | Tooltips are visual only: test the trigger (by its own accessible name), not the tooltip. |
145
149
  | Drawer | **dropped**, so use part props | `popupProps` (the `dialog`) |
146
150
  | NavRail, Breadcrumbs, Pagination | the `<nav>` | `itemProps` on each NavRail or Breadcrumbs item (the link, or the current crumb's span) |
147
151
  | AppShell | the root `<div>` | `mainProps`, `bodyProps` |
@@ -1,38 +0,0 @@
1
- /** Atomic utility classes. Compose into a style: `style([sprinkles({ gap: '2' }), { ... }])`. */
2
- export declare const sprinkles: ((props: {
3
- display?: "flex" | "grid" | "none" | "block" | "inline-block" | "inline-flex" | undefined;
4
- flexDirection?: "column" | "row" | undefined;
5
- flexWrap?: "nowrap" | "wrap" | undefined;
6
- alignItems?: "stretch" | "center" | "flex-end" | "flex-start" | "baseline" | undefined;
7
- justifyContent?: "space-between" | "center" | "flex-end" | "flex-start" | undefined;
8
- flex?: "none" | "1" | undefined;
9
- minWidth?: number | undefined;
10
- width?: "full" | undefined;
11
- textAlign?: "left" | "right" | "center" | undefined;
12
- whiteSpace?: "nowrap" | undefined;
13
- overflow?: "auto" | "hidden" | undefined;
14
- gap?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
15
- paddingTop?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
16
- paddingBottom?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
17
- paddingLeft?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
18
- paddingRight?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
19
- marginTop?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
20
- marginBottom?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
21
- marginLeft?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
22
- marginRight?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
23
- color?: "bg" | "canvas" | "surface" | "surfaceSunken" | "surfaceHover" | "border" | "borderSubtle" | "borderStrong" | "ink" | "inkMuted" | "inkSubtle" | "primary" | "primaryHover" | "onPrimary" | "accent" | "accentSubtle" | "accentInk" | "success" | "successSubtle" | "successInk" | "warning" | "warningSubtle" | "warningInk" | "warningFill" | "danger" | "dangerSubtle" | "dangerInk" | "dangerFill" | "info" | "infoSubtle" | "infoInk" | "infoBorder" | "neutral" | "neutralSubtle" | "neutralInk" | "highlight" | "highlightSubtle" | "highlightInk" | "highlightBorder" | "userBubble" | "focusRing" | "codeBg" | "codeInk" | "overlay" | "railBg" | "railBorder" | "railInk" | "railInkMuted" | "railHover" | "railActiveBg" | "railActiveInk" | "inherit" | "transparent" | "currentColor" | undefined;
24
- backgroundColor?: "bg" | "canvas" | "surface" | "surfaceSunken" | "surfaceHover" | "border" | "borderSubtle" | "borderStrong" | "ink" | "inkMuted" | "inkSubtle" | "primary" | "primaryHover" | "onPrimary" | "accent" | "accentSubtle" | "accentInk" | "success" | "successSubtle" | "successInk" | "warning" | "warningSubtle" | "warningInk" | "warningFill" | "danger" | "dangerSubtle" | "dangerInk" | "dangerFill" | "info" | "infoSubtle" | "infoInk" | "infoBorder" | "neutral" | "neutralSubtle" | "neutralInk" | "highlight" | "highlightSubtle" | "highlightInk" | "highlightBorder" | "userBubble" | "focusRing" | "codeBg" | "codeInk" | "overlay" | "railBg" | "railBorder" | "railInk" | "railInkMuted" | "railHover" | "railActiveBg" | "railActiveInk" | "inherit" | "transparent" | "currentColor" | undefined;
25
- borderRadius?: "sm" | "md" | "lg" | "2xl" | "xl" | "full" | undefined;
26
- fontSize?: "sm" | "md" | "lg" | "xs" | "2xl" | "xl" | "3xl" | undefined;
27
- fontWeight?: "normal" | "medium" | "semibold" | undefined;
28
- fontFamily?: "sans" | "mono" | undefined;
29
- padding?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
30
- paddingX?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
31
- paddingY?: "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
32
- margin?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
33
- marginX?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
34
- marginY?: "auto" | "0" | "1" | "2" | "3" | "5" | "1.5" | "4" | "6" | "8" | "2.5" | "0.5" | "10" | "12" | undefined;
35
- }) => string) & {
36
- properties: Set<"color" | "alignItems" | "backgroundColor" | "display" | "flexDirection" | "flexWrap" | "fontFamily" | "fontSize" | "fontWeight" | "justifyContent" | "marginBottom" | "marginLeft" | "marginRight" | "marginTop" | "minWidth" | "paddingBottom" | "paddingLeft" | "paddingRight" | "paddingTop" | "textAlign" | "whiteSpace" | "width" | "borderRadius" | "flex" | "gap" | "margin" | "overflow" | "padding" | "paddingX" | "paddingY" | "marginX" | "marginY">;
37
- };
38
- export type Sprinkles = Parameters<typeof sprinkles>[0];