@15gifts/back-office-kit 0.1.0-alpha.0 → 0.1.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 (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 +8 -3
  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
@@ -4,7 +4,7 @@
4
4
  Every component is a named export of `@15gifts/back-office-kit`: `import { Button } from '@15gifts/back-office-kit'`.
5
5
  Props marked * are required. All components also accept `className` and the native props of their root element.
6
6
 
7
- Components: Alert, AppShell, Autocomplete, Avatar, Badge, Breadcrumbs, Button, Card, ChatTranscript, Checkbox, Chip, ColorPicker, Combobox, DateRangePicker, DateTimeInput, DescriptionList, DetailsSummary, Drawer, EmptyLine, EnvironmentChip, Field, Fieldset, Heading, Icon, List, Loader, Menu, MetricBar, Modal, NavRail, NumberInput, PageHeader, Pagination, Popover, PortalContainer, ProgressBar, RadioCards, SaveBar, Select, Skeleton, Stack, StatCard, StatsGrid, StatusBadge, Switch, Switcher, Table, TableAction, Tabs, Tag, Textarea, TextInput, ThemePicker, ToggleGroup, Tooltip, TopBar, usePortalContainer, UserMenu.
7
+ Components: Alert, AppShell, Autocomplete, Avatar, Badge, Breadcrumbs, Button, Card, ChatTranscript, Checkbox, CheckboxGroup, Chip, ColorPicker, Combobox, CopyButton, DateRangePicker, DateTimeInput, DescriptionList, DetailsSummary, Drawer, EmptyLine, EmptyState, EnvironmentChip, environmentTone, Field, Fieldset, Grid, Heading, Icon, List, Loader, Menu, MetricBar, Modal, NavRail, NumberInput, PageHeader, Pagination, Popover, PortalContainer, ProgressBar, RadioCards, SaveBar, Select, Skeleton, Stack, StatCard, StatsGrid, StatusBadge, Switch, Switcher, Table, TableAction, Tabs, Tag, Textarea, TextInput, ThemeMenu, ThemePicker, TimeInput, ToggleGroup, Tooltip, TopBar, usePortalContainer, UserMenu.
8
8
 
9
9
  ### Alert
10
10
 
@@ -13,9 +13,11 @@ Page or section message. `info`/`success` are polite status updates; `warning`/`
13
13
  | Prop | Type | Default | Description |
14
14
  | --- | --- | --- | --- |
15
15
  | `action` | `ReactNode` | | Optional control under the body, e.g. a Button. |
16
- | `dismissLabel` | `string` | `Dismiss` | |
16
+ | `detail` | `ReactNode` | | Detail lines in monospace under the body, e.g. IDs or error codes. |
17
+ | `dismissLabel` | `string` | `Dismiss` | Accessible name of the dismiss button. |
18
+ | `live` | `boolean` | `true` | Announce the alert to screen readers (default). Set `false` for static content, such as a validation summary that re-renders on every keystroke: it drops `role="alert"`/`"status"`. An explicit `role` prop always wins. |
17
19
  | `onDismiss` | `(() => void)` | | Shows a dismiss button when set. |
18
- | `title` * | `ReactNode` | | |
20
+ | `title` | `ReactNode` | | The message, in bold. Optional, e.g. for a plain list of problems in `children`. |
19
21
  | `tone` | `AlertTone` | `info` | `warning` and `danger` interrupt screen readers (`role="alert"`); the others are polite (`role="status"`). |
20
22
 
21
23
  ### AppShell
@@ -30,6 +32,7 @@ Page frame for internal apps: icon rail on the left, top bar, optional side pane
30
32
  | `rail` | `ReactNode` | | Left navigation, usually a `NavRail`. |
31
33
  | `sidePanel` | `ReactNode` | | Optional secondary panel between the rail and the content (e.g. section nav or filters). |
32
34
  | `sidePanelLabel` | `string` | `Sidebar` | Accessible name for `sidePanel`. |
35
+ | `skipLinkLabel` | `string` | `Skip to content` | Text of the "skip to content" link, the first thing keyboard users reach. |
33
36
  | `topBar` | `ReactNode` | | Sticky bar above the content, usually a `TopBar`. |
34
37
 
35
38
  ### Autocomplete
@@ -38,13 +41,13 @@ Free-text input with suggestions. The value is whatever is typed or picked.
38
41
 
39
42
  | Prop | Type | Default | Description |
40
43
  | --- | --- | --- | --- |
41
- | `className` | `string` | | |
44
+ | `className` | `string` | | Goes on the field's root element. |
42
45
  | `clearable` | `boolean` | `false` | Shows a Clear button while there's text. |
43
46
  | `clearLabel` | `string` | `Clear` | Accessible name of the Clear button. |
44
47
  | `defaultOpen` | `boolean` | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead. |
45
- | `defaultValue` | `string` | | |
48
+ | `defaultValue` | `string` | | The initial text, when uncontrolled. |
46
49
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
47
- | `disabled` | `boolean` | | |
50
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
48
51
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
49
52
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
50
53
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
@@ -56,16 +59,13 @@ Free-text input with suggestions. The value is whatever is typed or picked.
56
59
  | `onOpenChange` | `((open: boolean, eventDetails: AutocompleteRootOpenChangeEventDetails) => void)` | | Event handler called when the popup is opened or closed. |
57
60
  | `onValueChange` | `((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void)` | | Event handler called when the input value of the autocomplete changes. |
58
61
  | `open` | `boolean` | | Whether the popup is currently open. Use when controlled. |
59
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
60
- | `placeholder` | `string` | | |
62
+ | `placeholder` | `string` | | Shown in the empty input. |
61
63
  | `popupProps` | `PartProps<ComboboxPopupProps>` | | Props for the suggestions popup. |
62
64
  | `portalContainer` | `PortalContainerTarget` | | Where the suggestions render. Defaults to the nearest `PortalContainer`, else `document.body`. |
63
- | `ref` | `Ref<HTMLInputElement>` | | |
64
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
65
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
66
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
65
+ | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the text input. |
66
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
67
67
  | `suggestions` * | `string[]` | | Suggestions shown while typing. Any text is allowed. |
68
- | `value` | `string` | | |
68
+ | `value` | `string` | | The text. Use with `onValueChange` to control it. |
69
69
 
70
70
  ### Avatar
71
71
 
@@ -77,7 +77,7 @@ Person's image with an initials fallback. Named from `name` for assistive tech.
77
77
  | `initials` | `string` | | Initials shown when there is no image. Derived from `name` when omitted. |
78
78
  | `name` | `string` | | Person's name or email. Used as the accessible name and to derive initials. |
79
79
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarRootState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
80
- | `size` | `"sm" \| "md" \| "lg"` | `md` | |
80
+ | `size` | `"sm" \| "md" \| "lg"` | `md` | `sm` 24px (inline, e.g. menus), `md` 40px (default), `lg` 56px (profile headers). |
81
81
  | `src` | `string` | | Image URL. Falls back to initials while loading or if it fails. |
82
82
  | `style` | `CSSProperties \| ((state: AvatarRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
83
83
 
@@ -88,7 +88,8 @@ A small pill label. Use `tone`, not `color`.
88
88
  | Prop | Type | Default | Description |
89
89
  | --- | --- | --- | --- |
90
90
  | `icon` | `ReactNode` | | Decorative icon shown before the label (mark it `aria-hidden`). |
91
- | `tone` | `BadgeTone` | `neutral` | |
91
+ | `mono` | `boolean` | `false` | Monospace text, for IDs, codes and versions. |
92
+ | `tone` | `BadgeTone` | `neutral` | Colour. `neutral` (default) for plain labels; the others carry meaning, e.g. `danger` for errors. |
92
93
  | `variant` | `"subtle" \| "solid"` | `subtle` | `subtle` (default) is a tinted pill; `solid` is a filled pill for stronger emphasis. |
93
94
 
94
95
  ### Breadcrumbs
@@ -105,15 +106,14 @@ Action button. Use `primary` for the one main action per view, `secondary` for o
105
106
 
106
107
  | Prop | Type | Default | Description |
107
108
  | --- | --- | --- | --- |
108
- | `fullWidth` | `boolean` | `false` | |
109
+ | `fullWidth` | `boolean` | `false` | Stretches the button to fill its container. |
109
110
  | `icon` | `ReactNode` | | Icon element (e.g. a lucide-react icon) shown before the label. |
110
- | `iconOnly` | `boolean` | `false` | Square button showing only the icon. Requires `aria-label`. |
111
+ | `iconOnly` | `boolean` | `false` | Square button showing only the icon. `children` (or `aria-label`) still names it for screen readers. |
111
112
  | `loading` | `boolean` | `false` | Shows a spinner and blocks clicks, keeping the button's width and focus. A loading button is `aria-disabled="true"` and `aria-busy="true"`, not native `disabled`, so it stays focusable (assert `aria-disabled` in tests, not `toBeDisabled()`). |
112
113
  | `loadingLabel` | `string` | | Text announced to assistive tech while `loading`, e.g. "Saving". It becomes the button's accessible name and is read out through a polite live region, a visually hidden `role="status"` span rendered next to the button. |
113
114
  | `render` | `RenderProp<Record<string, unknown>>` | | Render a different element, e.g. `render={<a href="/runs" />}` or a router `<Link to="/runs" />`. |
114
- | `showLoadingLabel` | `boolean` | `false` | Shows `loadingLabel` next to the spinner instead of the content (the width may change). |
115
- | `size` | `"sm" \| "md"` | `md` | |
116
- | `variant` | `"danger" \| "primary" \| "secondary" \| "ghost"` | `primary` | |
115
+ | `size` | `"sm" \| "md"` | `md` | `sm` for dense places such as table rows and toolbars. |
116
+ | `variant` | `"danger" \| "primary" \| "secondary" \| "ghost"` | `primary` | `primary` for the one main action per view, `secondary` for others, `ghost` in toolbars and tables, `danger` for destructive actions. |
117
117
 
118
118
  ### Card
119
119
 
@@ -122,9 +122,11 @@ Surface that groups related content, with an optional heading and actions. Use `
122
122
  | Prop | Type | Default | Description |
123
123
  | --- | --- | --- | --- |
124
124
  | `actions` | `ReactNode` | | Controls shown at the end of the header, e.g. buttons. |
125
+ | `description` | `ReactNode` | | Muted subtitle under the heading. |
125
126
  | `flush` | `boolean` | `false` | Remove the padding, e.g. for a table that fills the card. |
126
127
  | `heading` | `ReactNode` | | Header content. A string is rendered as an `h2`; pass your own element to pick the level. |
127
- | `size` | `"sm" \| "md"` | `md` | |
128
+ | `render` | `RenderProp<Record<string, unknown>>` | | Render a different element instead of `<section>`, e.g. `render={<aside />}`. |
129
+ | `size` | `"sm" \| "md"` | `md` | `sm` has tighter padding, e.g. for cards inside other content. |
128
130
 
129
131
  ### ChatTranscript
130
132
 
@@ -135,7 +137,7 @@ layouts. Consecutive messages from the same speaker group together.
135
137
  | Prop | Type | Default | Description |
136
138
  | --- | --- | --- | --- |
137
139
  | `assistantAvatar` | `ReactNode` | | Assistant avatar, e.g. `<Avatar size="sm" name="Humara" />`. |
138
- | `assistantName` | `ReactNode` | | Visible assistant name, e.g. "Humara". |
140
+ | `assistantName` | `ReactNode` | | Visible assistant name, e.g. "Humara". Defaults to the `labels.assistant` name ("Assistant"), so replies are always marked. |
139
141
  | `empty` | `ReactNode` | | Shown when there are no messages. |
140
142
  | `label` | `string` | | Accessible name of the log. |
141
143
  | `labels` | `ChatTranscriptLabels` | | Speaker names for screen readers. Defaults: "You" and "Assistant". |
@@ -151,35 +153,57 @@ A checkbox with its label beside it.
151
153
  | Prop | Type | Default | Description |
152
154
  | --- | --- | --- | --- |
153
155
  | `checked` | `boolean` | `undefined` | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead. |
154
- | `className` | `string` | | |
156
+ | `className` | `string` | | Class for the field's root element. |
155
157
  | `defaultChecked` | `boolean` | `false` | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead. |
156
158
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
157
- | `disabled` | `boolean` | | |
159
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
158
160
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
159
161
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
160
162
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
161
163
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
162
164
  | `name` | `string` | `undefined` | Identifies the field when a form is submitted. |
163
165
  | `onCheckedChange` | `((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void)` | | Event handler called when the checkbox is ticked or unticked. |
164
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
165
166
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the hidden checkbox input (for form libraries). |
166
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
167
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
168
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
167
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
169
168
  | `style` | `CSSProperties \| ((state: CheckboxRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
170
169
  | `value` | `string` | | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |
171
170
 
171
+ ### CheckboxGroup
172
+
173
+ A labelled set of checkboxes: pick any number. `required` only adds the asterisk, since browsers
174
+ can't require "at least one"; validate that yourself and pass `error`.
175
+
176
+ | Prop | Type | Default | Description |
177
+ | --- | --- | --- | --- |
178
+ | `className` | `string` | | Class for the field's root element. |
179
+ | `defaultValue` | `string[]` | | Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the `value` prop instead. |
180
+ | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
181
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
182
+ | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
183
+ | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
184
+ | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
185
+ | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
186
+ | `name` | `string` | | Submitted once per ticked option. |
187
+ | `onValueChange` | `((value: string[]) => void)` | | Called with the values of the ticked options. |
188
+ | `options` * | `CheckboxGroupOption[]` | | The checkboxes, in order. |
189
+ | `orientation` | `"horizontal" \| "vertical"` | `vertical` | `horizontal` lines short options up in a row, wrapping when needed. |
190
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
191
+ | `style` | `CSSProperties \| ((state: CheckboxGroupState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
192
+ | `value` | `string[]` | | Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the `defaultValue` prop instead. |
193
+
172
194
  ### Chip
173
195
 
174
- A selectable pill built on Base UI Toggle. Selected chips show a leading check.
196
+ A selectable pill built on Base UI Toggle. Selected chips show a leading check. Pass `static`
197
+ for a non-interactive chip that only displays a choice.
175
198
 
176
199
  | Prop | Type | Default | Description |
177
200
  | --- | --- | --- | --- |
178
201
  | `className` | `string` | | |
179
202
  | `defaultPressed` | `boolean` | `false` | Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`. |
180
203
  | `onPressedChange` | `((pressed: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void)` | | Callback fired when the pressed state is changed. |
181
- | `pressed` | `boolean` | | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`. |
204
+ | `pressed` | `boolean` | | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`. Shows the leading check, and "(selected)" to screen readers. |
182
205
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ToggleState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
206
+ | `static` | `boolean` | | Display only: a `<span>` that looks like a chip, e.g. to show what was chosen. |
183
207
  | `style` | `CSSProperties \| ((state: ToggleState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
184
208
  | `value` | `string` | | A unique string that identifies the toggle when used inside a toggle group. |
185
209
 
@@ -190,23 +214,20 @@ colour picker. Values not written as hex show their hex alongside.
190
214
 
191
215
  | Prop | Type | Default | Description |
192
216
  | --- | --- | --- | --- |
193
- | `defaultValue` | `string` | `` | |
217
+ | `defaultValue` | `string` | `` | The initial colour text, when uncontrolled. |
194
218
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
195
- | `disabled` | `boolean` | | |
219
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
196
220
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
197
221
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
198
222
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
199
223
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
200
224
  | `name` | `string` | | |
201
225
  | `onValueChange` | `((value: string) => void)` | | Called with the text as typed or picked, e.g. `#0B6B4F` or `rgb(0 0 0)`. |
202
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
203
226
  | `pickerLabel` | `string` | `Choose colour` | Accessible name of the swatch that opens the browser's colour picker. |
204
227
  | `placeholder` | `string` | | |
205
228
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the text input. |
206
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
207
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
208
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
209
- | `value` | `string` | | |
229
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
230
+ | `value` | `string` | | The colour text. Use with `onValueChange` to control it. |
210
231
 
211
232
  ### Combobox
212
233
 
@@ -217,37 +238,46 @@ Filterable single-choice dropdown: type to narrow the options, then pick one.
217
238
  | `actionsRef` | `RefObject<Actions \| null>` | | A ref to imperative actions. - `unmount`: Ends the closing phase of the combobox after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the combobox completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the combobox imperatively when called. |
218
239
  | `autoComplete` | `string` | | Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete |
219
240
  | `autoHighlight` | `boolean` | `false` | Whether the first matching item is highlighted automatically while filtering. |
220
- | `className` | `string` | | |
241
+ | `className` | `string` | | Goes on the field's root element. |
242
+ | `clearLabel` | `string` | `Clear` | Accessible name of the Clear button. |
221
243
  | `defaultOpen` | `boolean` | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead. |
222
- | `defaultValue` | `string \| null` | | |
244
+ | `defaultValue` | `string \| null` | | The initially picked option's `value`, when uncontrolled. |
223
245
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
224
- | `disabled` | `boolean` | | |
246
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
225
247
  | `emptyMessage` | `ReactNode` | `No matches` | Shown when nothing matches the typed text. |
226
248
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
227
249
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
228
250
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
229
251
  | `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
230
252
  | `inputProps` | `PartProps<ComboboxInputProps>` | | Props for the text input (role `combobox`), e.g. `{ 'data-testid': 'retailer' }`. |
231
- | `isItemEqualToValue` | `((itemValue: string, value: string) => boolean)` | | Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. With a `createItems()` collection, both arguments are derived values. Defaults to `Object.is` comparison. |
232
- | `itemToStringLabel` | `((itemValue: string) => string)` | | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. With a `createItems()` collection, this receives the derived value, and the collection's `getLabel` takes precedence for values it can resolve. |
233
- | `itemToStringValue` | `((itemValue: string) => string)` | | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop. With a `createItems()` collection, this receives the derived value. |
234
253
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
235
254
  | `name` | `string` | | Identifies the field when a form is submitted. |
236
255
  | `onInputValueChange` | `((inputValue: string, eventDetails: ChangeEventDetails) => void)` | | Event handler called when the input value changes. |
237
256
  | `onItemHighlighted` | `((highlightedValue: string, eventDetails: HighlightEventDetails) => void)` | | Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent` rather than a `PointerEvent`. - `'none'`: the highlight changed for another reason, such as typing, `autoHighlight`, the item list changing, or the popup opening or closing. |
238
257
  | `onOpenChange` | `((open: boolean, eventDetails: OpenChangeEventDetails) => void)` | | Event handler called when the popup is opened or closed. |
239
- | `onValueChange` | `((value: string \| null) => void)` | | |
258
+ | `onValueChange` | `((value: string \| null) => void)` | | Called with the picked option's `value`, or `null` when cleared (Clear button, or a form reset). |
240
259
  | `open` | `boolean` | | Whether the popup is currently open. Use when controlled. |
241
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
242
- | `options` * | `ComboboxOption[]` | | |
243
- | `placeholder` | `string` | | |
260
+ | `options` * | `ComboboxOption[]` | | The choices, in order. |
261
+ | `placeholder` | `string` | | Shown in the empty input. |
244
262
  | `popupProps` | `PartProps<ComboboxPopupProps>` | | Props for the dropdown, e.g. `{ 'data-testid': 'retailer-options' }`. |
263
+ | `popupWidth` | `string` | | Width of the dropdown when it should be wider than the field, e.g. `'24rem'`. Never narrower than the field. |
245
264
  | `portalContainer` | `PortalContainerTarget` | | Where the dropdown renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
246
265
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the visible text input. |
247
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
248
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
249
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
250
- | `value` | `string \| null` | | |
266
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
267
+ | `value` | `string \| null` | | The picked option's `value`, or `null` for none. Use with `onValueChange` to control it. |
268
+
269
+ ### CopyButton
270
+
271
+ Icon button that copies `value` to the clipboard, shows a check briefly and announces it.
272
+
273
+ | Prop | Type | Default | Description |
274
+ | --- | --- | --- | --- |
275
+ | `copiedLabel` | `string` | `Copied` | Announced after copying. Default "Copied". |
276
+ | `fullWidth` | `boolean` | | Stretches the button to fill its container. |
277
+ | `label` | `string` | `Copy` | Accessible name. Default "Copy"; say what's copied, e.g. "Copy run ID". |
278
+ | `size` | `"sm" \| "md"` | `sm` | `sm` for dense places such as table rows and toolbars. |
279
+ | `value` * | `string` | | The text copied to the clipboard. |
280
+ | `variant` | `"danger" \| "primary" \| "secondary" \| "ghost"` | `ghost` | `primary` for the one main action per view, `secondary` for others, `ghost` in toolbars and tables, `danger` for destructive actions. |
251
281
 
252
282
  ### DateRangePicker
253
283
 
@@ -257,34 +287,31 @@ Escape or Cancel discards the draft.
257
287
 
258
288
  | Prop | Type | Default | Description |
259
289
  | --- | --- | --- | --- |
260
- | `applyLabel` | `string` | `Apply` | |
261
- | `cancelLabel` | `string` | `Cancel` | |
290
+ | `applyLabel` | `string` | `Apply` | Text of the button that applies the picked range. |
291
+ | `cancelLabel` | `string` | `Cancel` | Text of the button that discards the picked range. |
262
292
  | `className` | `string` | | Goes on the field root. |
263
- | `defaultValue` | `DateRange` | `{ start: null, end: null }` | |
293
+ | `defaultValue` | `DateRange` | `{ start: null, end: null }` | The initial range, for an uncontrolled picker. |
264
294
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
265
- | `disabled` | `boolean` | | |
266
- | `endTimeLabel` | `string` | `End time` | |
295
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
296
+ | `endTimeLabel` | `string` | `End time` | Label of the end time input (with `withTime`). |
267
297
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
268
298
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
269
299
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
270
300
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
271
301
  | `locale` | `Partial<DayPickerLocale>` | | Calendar locale, e.g. `enGB` from `react-day-picker/locale`. Its `code` also formats the trigger. |
272
- | `maxDate` | `Date` | | Latest selectable day. |
273
- | `minDate` | `Date` | | Earliest selectable day. |
302
+ | `maxDate` | `Date` | | Latest selectable day. Ranges, including quick ranges, are clamped to end by the end of it. |
303
+ | `minDate` | `Date` | | Earliest selectable day. Ranges, including quick ranges, are clamped to start no earlier. |
274
304
  | `onValueChange` | `((range: DateRange, details: { preset?: DateRangePreset; }) => void)` | | Called with the new range on Apply or when a quick range is chosen. `details.preset` is the chosen quick range, so a preset can trigger extra behaviour (e.g. a live mode). |
275
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
276
305
  | `placeholder` | `string` | `Select a date range` | Trigger text while no range is set. |
277
306
  | `popupProps` | `PartProps<PopoverPopupProps>` | | Props for the popup (role `dialog`). |
278
307
  | `portalContainer` | `PortalContainerTarget` | | Where the popup renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
279
308
  | `presets` | `DateRangePreset[]` | | Quick ranges beside the calendar. Replaces the defaults; `[]` hides the list. |
280
- | `presetsLabel` | `string` | `Quick ranges` | |
281
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
282
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
283
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
284
- | `startTimeLabel` | `string` | `Start time` | |
309
+ | `presetsLabel` | `string` | `Quick ranges` | Accessible name of the quick ranges list. |
310
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
311
+ | `startTimeLabel` | `string` | `Start time` | Label of the start time input (with `withTime`). |
285
312
  | `timeZone` | `string` | | IANA zone (e.g. `'UTC'`) that days and times are shown and picked in. Defaults to local time. |
286
313
  | `triggerProps` | `PartProps<Props<unknown>>` | | Props for the trigger button, e.g. `{ 'data-testid': 'range' }`. |
287
- | `value` | `DateRange` | | |
314
+ | `value` | `DateRange` | | The applied range, for a controlled picker. Use with `onValueChange`. |
288
315
  | `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First day of the week (0 is Sunday). |
289
316
  | `withTime` | `boolean` | `false` | Adds start and end time inputs. Without it, a range runs from the start of its first day to the end of its last. |
290
317
 
@@ -296,19 +323,16 @@ Date and time picker using the browser's native `datetime-local` input.
296
323
  | --- | --- | --- | --- |
297
324
  | `defaultValue` | `string \| number \| readonly string[]` | | |
298
325
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
299
- | `disabled` | `boolean` | | |
326
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
300
327
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
301
328
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
302
329
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
303
330
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
304
331
  | `name` | `string` | | |
305
332
  | `onValueChange` | `((value: string) => void)` | | Called with the local date-time string, e.g. `2026-11-10T09:21`, or `''` when cleared. |
306
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
307
333
  | `placeholder` | `string` | | |
308
334
  | `ref` | `Ref<HTMLInputElement>` | | |
309
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
310
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
311
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
335
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
312
336
  | `value` | `string \| number \| readonly string[]` | | |
313
337
 
314
338
  ### DescriptionList
@@ -317,9 +341,9 @@ Key/value facts as a semantic `<dl>`. Terms are muted, values use the main ink c
317
341
 
318
342
  | Prop | Type | Default | Description |
319
343
  | --- | --- | --- | --- |
320
- | `items` * | `DescriptionListItem[]` | | |
344
+ | `items` * | `DescriptionListItem[]` | | Term/description pairs, in order. |
321
345
  | `layout` | `"grid" \| "inline" \| "stacked"` | `stacked` | `stacked`: term above value, one pair per row. `inline`: term and value side by side, terms aligned. `grid`: stacked pairs in responsive columns. |
322
- | `size` | `"sm" \| "md"` | `md` | |
346
+ | `size` | `"sm" \| "md"` | `md` | `sm` for dense panels such as drawers. |
323
347
 
324
348
  ### DetailsSummary
325
349
 
@@ -329,6 +353,7 @@ A styled native `<details>`/`<summary>` disclosure.
329
353
  | --- | --- | --- | --- |
330
354
  | `heading` * | `ReactNode` | | Always-visible summary that toggles the content. |
331
355
  | `open` | `boolean` | | |
356
+ | `tone` | `BadgeTone` | `neutral` | Tints the panel and colours the summary, e.g. `danger` for a block of errors. `neutral` (default) is untinted. |
332
357
 
333
358
  ### Drawer
334
359
 
@@ -336,16 +361,22 @@ A modal side panel. Closes on Escape, the close button, an overlay click or a sw
336
361
 
337
362
  | Prop | Type | Default | Description |
338
363
  | --- | --- | --- | --- |
364
+ | `actions` | `ReactNode` | | Controls in the header, before the close button, e.g. a Menu or an Edit button. |
365
+ | `children` | `ReactNode` | | Scrolling body content. |
339
366
  | `className` | `string` | | Goes on the popup (role `dialog`). |
340
367
  | `closeLabel` | `string` | `Close` | Accessible label of the close button. |
341
368
  | `defaultOpen` | `boolean` | `false` | Whether the drawer is initially open. To render a controlled drawer, use the `open` prop instead. |
342
- | `description` | `ReactNode` | | |
343
- | `footer` | `ReactNode` | | Actions pinned to the bottom, e.g. Cancel and Save buttons. |
369
+ | `description` | `ReactNode` | | Muted text under the title, linked as the dialog's description. |
370
+ | `footer` | `ReactNode` | | Actions pinned to the bottom right, e.g. Cancel and Save. The footer sits outside the body, so a submit button there only submits a `<form>` in the body if you give it `form="<form id>"`, or set `onSubmit` instead. |
371
+ | `footerStart` | `ReactNode` | | Secondary actions pinned to the bottom left, e.g. Archive or Copy link. |
372
+ | `onClose` | `(() => void)` | | Called when the drawer asks to close (Escape, close button, overlay click, swipe). Shorthand for `onOpenChange(false)`. |
344
373
  | `onOpenChange` | `((open: boolean, eventDetails: DrawerRootChangeEventDetails) => void)` | | Event handler called when the drawer is opened or closed. |
374
+ | `onSubmit` | `FormEventHandler<HTMLFormElement>` | | Wraps the body and footer in a `<form>` with this handler, so a `type="submit"` button in the footer submits it. Call `event.preventDefault()` yourself (react-hook-form's `handleSubmit` does). |
345
375
  | `open` | `boolean` | | Whether the drawer is currently open. |
346
376
  | `popupProps` | `PartProps<DrawerPopupProps>` | | Props for the popup (role `dialog`), e.g. `{ 'data-testid': 'run-drawer' }`. |
347
- | `side` | `"right" \| "left"` | `right` | |
348
- | `title` * | `ReactNode` | | |
377
+ | `side` | `"right" \| "left"` | `right` | Screen edge the drawer slides in from (and is swiped back to). |
378
+ | `size` | `"sm" \| "md" \| "lg"` | `sm` | Width: `sm` 28rem (default), `md` 36rem, `lg` 60rem. Always capped to the viewport. |
379
+ | `title` * | `ReactNode` | | Heading, also the dialog's accessible name. |
349
380
  | `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | | The element that opens the drawer, e.g. `<Button>`. Omit when controlling `open` yourself. |
350
381
 
351
382
  ### EmptyLine
@@ -356,34 +387,50 @@ A one-line empty state, e.g. "No prompt chips yet."
356
387
  | --- | --- | --- | --- |
357
388
  | `bare` | `boolean` | `false` | Without its own border, for use inside something that already has one (e.g. a table cell). |
358
389
 
390
+ ### EmptyState
391
+
392
+ A centred placeholder for an empty list, table or card, or a load error. Use `EmptyLine` for a one-liner.
393
+
394
+ | Prop | Type | Default | Description |
395
+ | --- | --- | --- | --- |
396
+ | `action` | `ReactNode` | | Optional button or link, e.g. "Start a run" or "Retry". |
397
+ | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | | Renders the title as `h2`–`h6`. Default is a `<p>`, which suits cards and table cells. |
398
+ | `icon` | `ReactNode` | | Shown in a tile above the title. Defaults to an inbox (or an alert for `danger`); `null` hides it. |
399
+ | `title` * | `ReactNode` | | One short line, e.g. "No runs yet". |
400
+ | `tone` | `"danger" \| "neutral"` | `neutral` | `danger` is the error variant ("Couldn't load runs"), announced with `role="alert"`. |
401
+
359
402
  ### EnvironmentChip
360
403
 
361
- Shows which environment the app is pointed at. Put it in the TopBar `end` slot.
404
+ Shows which environment the app is pointed at, coloured by its name so production always stands
405
+ out. Put it in the TopBar `end` slot.
362
406
 
363
407
  | Prop | Type | Default | Description |
364
408
  | --- | --- | --- | --- |
365
- | `environment` * | `string` | | Environment name, e.g. "staging". |
366
- | `tone` | `"danger" \| "neutral" \| "highlight"` | `highlight` | `danger` for production-like environments, so they stand out. |
409
+ | `environment` * | `string` | | Environment name, shown as given, e.g. "Staging". Its colour comes from the name (see `environmentTone`). |
410
+
411
+ ### environmentTone
412
+
413
+ The colour an environment name gets: production and live are `danger`; staging, UAT, QA, test
414
+ and pre-prod are `highlight`; dev, ephemeral, preview, sandbox and demo are `info`; anything
415
+ else (e.g. local) is `neutral`.
367
416
 
368
417
  ### Field
369
418
 
370
419
  Wraps a form control with a label, description and error message. Base UI wires up the label,
371
420
  `aria-describedby` and invalid state for any Base UI control (or `Field.Control`) inside it.
421
+ Here `required` only adds the asterisk, so put `required` on the control too.
372
422
 
373
423
  | Prop | Type | Default | Description |
374
424
  | --- | --- | --- | --- |
375
425
  | `className` | `string` | | |
376
426
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
377
- | `disabled` | `boolean` | | |
427
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
378
428
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
379
429
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
380
430
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
381
431
  | `name` | `string` | | Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component. |
382
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
383
432
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldRootState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
384
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
385
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
386
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
433
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
387
434
  | `style` | `CSSProperties \| ((state: FieldRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
388
435
 
389
436
  ### Fieldset
@@ -393,11 +440,22 @@ A titled card of related fields. Nested fieldsets render as an indented group in
393
440
  | Prop | Type | Default | Description |
394
441
  | --- | --- | --- | --- |
395
442
  | `className` | `string` | | |
396
- | `description` | `ReactNode` | | |
443
+ | `description` | `ReactNode` | | Help text under the legend, linked with `aria-describedby`. A `<div>`, so it can hold block content. |
397
444
  | `legend` * | `ReactNode` | | The card's title. |
398
445
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldsetRootState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
399
446
  | `style` | `CSSProperties \| ((state: FieldsetRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
400
447
 
448
+ ### Grid
449
+
450
+ Grid layout, e.g. form fields in rows or cards in a responsive grid.
451
+
452
+ | Prop | Type | Default | Description |
453
+ | --- | --- | --- | --- |
454
+ | `align` | `"center" \| "start" \| "end" \| "stretch"` | `start` | Vertical alignment in each row. `start` (default) keeps fields top-aligned when one has a description. |
455
+ | `columns` | `string \| number` | | A number gives that many equal columns. A string is a `grid-template-columns` value, e.g. `'1fr 20rem'` for content beside a sidebar. Default `1`. |
456
+ | `gap` | `"1" \| "2" \| "3" \| "4" \| "6" \| "8"` | `4` | Space between cells: `'1'` 4px, `'2'` 8px, `'3'` 12px, `'4'` 16px (default), `'6'` 24px, `'8'` 32px. |
457
+ | `minColumnWidth` | `string` | | Responsive: columns are at least this wide (e.g. `'16rem'`), so the grid drops to fewer columns as it narrows, down to one. With a number of `columns` it never goes above that number; on its own it fits as many as there's room for. Ignored when `columns` is a string. |
458
+
401
459
  ### Heading
402
460
 
403
461
  Section heading. `level` sets the semantic h1–h6; `size` sets the look independently. Pages get their h1 from `PageHeader`.
@@ -426,7 +484,7 @@ Simple list with a built-in empty state.
426
484
  | --- | --- | --- | --- |
427
485
  | `emptyState` | `ReactNode` | `No items` | Shown when there are no items. |
428
486
  | `getKey` | `((item: T, index: number) => Key)` | `(item: unknown): Key => (typeof item === 'string' ? item : JSON.stringify(item))` | Row key. Defaults to the item if it's a string, else its JSON. |
429
- | `items` | `readonly T[] \| null` | | |
487
+ | `items` | `readonly T[] \| null` | | The items. `null` or empty shows `emptyState`. |
430
488
  | `renderItem` | `((item: T, index: number) => ReactNode)` | `(item) => item as ReactNode` | Row content. Defaults to the item itself, so strings need no template. |
431
489
 
432
490
  ### Loader
@@ -435,7 +493,7 @@ Indeterminate spinner. Inherits the current text colour.
435
493
 
436
494
  | Prop | Type | Default | Description |
437
495
  | --- | --- | --- | --- |
438
- | `label` | `string \| null` | `Loading` | Accessible label. Pass `null` when a visible label sits next to it. |
496
+ | `label` | `string \| null` | `Loading` | Text announced to screen readers. Pass `null` when a visible label sits next to it. |
439
497
  | `size` | `string \| number` | `1rem` | Diameter as a CSS length, e.g. `'1em'` to match the surrounding text. Numbers are px at the 16px base, converted to rem so they scale with the text-size setting. |
440
498
 
441
499
  ### Menu
@@ -444,7 +502,7 @@ A dropdown list of actions, links, settings and submenus.
444
502
 
445
503
  | Prop | Type | Default | Description |
446
504
  | --- | --- | --- | --- |
447
- | `align` | `Align` | `start` | |
505
+ | `align` | `Align` | `start` | How the menu lines up with the trigger along that side. |
448
506
  | `className` | `string` | | Goes on the popup (role `menu`). |
449
507
  | `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
450
508
  | `footer` | `ReactNode` | | Content below the items, e.g. a version number. |
@@ -454,7 +512,7 @@ A dropdown list of actions, links, settings and submenus.
454
512
  | `open` | `boolean` | | Whether the menu is currently open. |
455
513
  | `popupProps` | `PartProps<MenuPopupProps>` | | Props for the popup (role `menu`), e.g. `{ 'data-testid': 'account-menu' }`. |
456
514
  | `portalContainer` | `PortalContainerTarget` | | Where the menu renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
457
- | `side` | `Side` | `bottom` | |
515
+ | `side` | `Side` | `bottom` | Which side of the trigger the menu opens on. It flips if there isn't room. |
458
516
  | `trigger` * | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | | The element that opens the menu, e.g. `<Button>`. It must accept a ref and props. |
459
517
 
460
518
  ### MetricBar
@@ -464,9 +522,11 @@ A labelled percentage with a stacked bar, e.g. "Achieved 83%".
464
522
  | Prop | Type | Default | Description |
465
523
  | --- | --- | --- | --- |
466
524
  | `className` | `string` | | |
467
- | `label` * | `ReactNode` | | |
525
+ | `formatValue` | `((value: number) => ReactNode)` | `(value: number) => `${Math.round(value)}%`` | Formats `value` and the legend's segment values. Defaults to a rounded percentage, e.g. "83%". |
526
+ | `label` * | `ReactNode` | | Names the meter, e.g. "Achieved". |
468
527
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, MeterRootState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
469
528
  | `segments` | `MetricBarSegment[]` | `[{ value, tone }]` | Stacked bar segments, left to right. Defaults to one segment of `value` in the label's tone. |
529
+ | `size` | `"sm" \| "md"` | `md` | `sm` for dense rows and cards: smaller text and a thinner bar. |
470
530
  | `style` | `CSSProperties \| ((state: MeterRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
471
531
  | `tone` | `"success" \| "danger" \| "neutral"` | `neutral` | Colour of the label. |
472
532
  | `value` * | `number` | | The percentage shown next to the label (0 to 100). |
@@ -477,34 +537,34 @@ Controlled modal dialog. Closes on Escape, backdrop click and the close buttons
477
537
 
478
538
  | Prop | Type | Default | Description |
479
539
  | --- | --- | --- | --- |
480
- | `className` | `string` | | |
481
- | `closeLabel` | `string` | `Close` | |
482
- | `description` | `ReactNode` | | |
540
+ | `className` | `string` | | Goes on the popup (role `dialog`). |
541
+ | `closeLabel` | `string` | `Close` | Accessible label of the close buttons, and the default footer button's text. |
542
+ | `description` | `ReactNode` | | Muted text under the title, linked as the dialog's description. |
483
543
  | `footer` | `ReactNode` | | Footer actions. Defaults to a single Close button; pass `null` for no footer. |
484
- | `onOpenChange` * | `(open: boolean, eventDetails: DialogRootChangeEventDetails) => void` | | |
485
- | `open` * | `boolean` | | |
544
+ | `onOpenChange` * | `(open: boolean, eventDetails: DialogRootChangeEventDetails) => void` | | Called with `false` when the user closes it (Escape, backdrop click, close buttons). |
545
+ | `open` * | `boolean` | | Whether the modal is open. The modal is always controlled. |
486
546
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, DialogPopupState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
487
547
  | `size` | `"sm" \| "md" \| "lg"` | `md` | Max width: `sm` 37.5rem, `md` 47rem (default), `lg` 78rem. It's always capped to the viewport. |
488
548
  | `style` | `CSSProperties \| ((state: DialogPopupState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
489
- | `title` * | `ReactNode` | | |
549
+ | `title` * | `ReactNode` | | Heading, also the dialog's accessible name. |
490
550
 
491
551
  ### NavRail
492
552
 
493
553
  Primary app navigation: a slim icon rail that can expand to show labels. Collapsed by default;
494
- uncontrolled rails remember the user's choice in localStorage.
554
+ uncontrolled rails remember the user's choice in localStorage. In a narrow window an uncontrolled
555
+ rail collapses; expanding it there lasts until the window widens and isn't stored.
495
556
 
496
557
  | Prop | Type | Default | Description |
497
558
  | --- | --- | --- | --- |
498
559
  | `appName` | `string` | | The app's name, shown under the Humara wordmark when the rail is expanded, e.g. "Back Office". The logo itself is built in: the wordmark when expanded, the fan mark when collapsed. |
499
- | `brandHref` | `string` | `/` | |
560
+ | `brandHref` | `string` | `/` | Where the logo links to. Use `brandRender` instead for a router link. |
500
561
  | `brandLabel` | `string` | `appName ? `${appName} home` : 'Home'` | Accessible name of the logo link. Defaults to "<appName> home", or "Home". |
501
562
  | `brandRender` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | | Router link element for the logo, e.g. `<Link to="/" />`. |
502
- | `collapsible` | `boolean` | `true` | Show the expand/collapse toggle. |
503
563
  | `defaultExpanded` | `boolean` | `false` | Starting state when uncontrolled and nothing is stored. |
504
- | `expanded` | `boolean` | | Shows labels next to icons. When collapsed, each item's label shows in a `Tooltip`. Pass it to control the rail yourself (nothing is stored); omit it and the rail manages its own state. A controlled rail without `onExpandedChange` hides the toggle. |
564
+ | `expanded` | `boolean` | | Shows labels next to icons. When collapsed, each item's label shows in a `Tooltip`. Pass it to control the rail yourself (nothing is stored); omit it and the rail manages its own state, collapsing in windows narrower than 48em. Without `onExpandedChange` the toggle is hidden, so `expanded={false}` gives a fixed icon rail. |
505
565
  | `footer` | `ReactNode \| ((expanded: boolean) => ReactNode)` | | Pinned to the bottom, e.g. a `UserMenu`. Pass a function to vary it with `expanded`, e.g. `(expanded) => <UserMenu name={name} showName={expanded} />`. |
506
- | `items` * | `NavRailItem[]` | | |
507
- | `onExpandedChange` | `((expanded: boolean) => void)` | | |
566
+ | `items` * | `(NavRailItem \| NavRailGroup)[]` | | Top-level sections, in order. Use groups (`{ group: 'Set up', items: [...] }`) when there are more than about six; don't mix groups and loose items. |
567
+ | `onExpandedChange` | `((expanded: boolean) => void)` | | Called with the new state when the user toggles the rail. |
508
568
  | `persistKey` | `string \| null` | `bok-rail-expanded` | localStorage key that remembers the user's choice when uncontrolled. `null` disables it. Use different keys for rails in different apps on one origin. |
509
569
 
510
570
  ### NumberInput
@@ -513,25 +573,23 @@ Numeric input with step buttons. Arrow keys step by `step`, Shift+Arrow by `larg
513
573
 
514
574
  | Prop | Type | Default | Description |
515
575
  | --- | --- | --- | --- |
516
- | `className` | `string` | | |
576
+ | `className` | `string` | | Class for the field's root element. |
517
577
  | `defaultValue` | `number` | | The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the `value` prop instead. |
518
578
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
519
- | `disabled` | `boolean` | | |
579
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
520
580
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
521
581
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
522
582
  | `hideControls` | `boolean` | `false` | Hides the − and + buttons. |
523
583
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
584
+ | `integer` | `boolean` | `false` | Whole numbers only: typed decimals round (on blur, and in `onValueChange` straight away), and Alt+Arrow steps by 1. Emptying the field reverts it to the last value on blur, so once it has a value `onValueChange` never gets `null`. |
524
585
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
525
586
  | `max` | `number` | | The maximum value of the input element. |
526
587
  | `min` | `number` | | The minimum value of the input element. |
527
588
  | `name` | `string` | | Identifies the field when a form is submitted. |
528
589
  | `onValueChange` | `((value: number \| null, eventDetails: NumberFieldRootChangeEventDetails) => void)` | | Callback fired when the number value changes. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` for parseable typing or programmatic text updates - `'input-clear'` when the field becomes empty - `'input-blur'` when formatting (and clamping, if enabled) occurs on blur - `'input-paste'` for paste interactions - `'keyboard'` for arrow-key/Home/End stepping (typing digits uses `'input-change'`/`'input-clear'`) - `'increment-press'` / `'decrement-press'` for button presses on the increment and decrement controls - `'wheel'` for wheel-based scrubbing - `'scrub'` for scrub area drags |
529
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
530
- | `placeholder` | `string` | | |
590
+ | `placeholder` | `string` | | Shown in the empty input. |
531
591
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the visible text input. |
532
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
533
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
534
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
592
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
535
593
  | `step` | `number \| "any"` | `1` | Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop. Specify `step="any"` to always disable step validation; interactive stepping then uses a base amount of `1`, while the alt and shift keys still step by `smallStep` and `largeStep`. |
536
594
  | `style` | `CSSProperties \| ((state: NumberFieldRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
537
595
  | `value` | `number \| null` | | The raw numeric value of the field. |
@@ -543,10 +601,10 @@ The page's h1, with an optional facts line, description, and actions at the top
543
601
  | Prop | Type | Default | Description |
544
602
  | --- | --- | --- | --- |
545
603
  | `actions` | `ReactNode` | | Controls at the top right, e.g. the page's primary Button. |
546
- | `description` | `ReactNode` | | |
547
- | `facts` | `ReactNode[]` | `[]` | Short facts on one line under the title, separated by dots. Empty ones are skipped. |
604
+ | `description` | `ReactNode` | | A sentence or two under the title. |
605
+ | `facts` | `ReactNode[]` | `[]` | Short facts on one line under the title. Put the one people act on first: it leads and the rest are muted. `null`, `undefined`, `false` and `''` are skipped (`0` is kept). |
548
606
  | `logo` | `ReactNode` | | Shown before the title, e.g. a logo or avatar. |
549
- | `title` * | `ReactNode` | | |
607
+ | `title` * | `ReactNode` | | The page's `<h1>`. |
550
608
 
551
609
  ### Pagination
552
610
 
@@ -554,12 +612,12 @@ Page navigation for long tables and lists. Controlled via `page` and `onPageChan
554
612
 
555
613
  | Prop | Type | Default | Description |
556
614
  | --- | --- | --- | --- |
557
- | `label` | `string` | `Pagination` | |
558
- | `nextLabel` | `string` | `Next page` | |
559
- | `onPageChange` * | `(page: number) => void` | | |
615
+ | `label` | `string` | `Pagination` | Accessible name of the `<nav>`. |
616
+ | `nextLabel` | `string` | `Next page` | Accessible name of the next button. |
617
+ | `onPageChange` * | `(page: number) => void` | | Called with the requested page (1-based). |
560
618
  | `page` * | `number` | | Current page, 1-based. |
561
- | `pageCount` * | `number` | | |
562
- | `previousLabel` | `string` | `Previous page` | |
619
+ | `pageCount` * | `number` | | Total number of pages. |
620
+ | `previousLabel` | `string` | `Previous page` | Accessible name of the previous button. |
563
621
  | `siblings` | `number` | `1` | Pages shown either side of the current one before collapsing into "…". |
564
622
 
565
623
  ### Popover
@@ -568,14 +626,16 @@ Floating content anchored to a trigger. Closes on Escape and outside click.
568
626
 
569
627
  | Prop | Type | Default | Description |
570
628
  | --- | --- | --- | --- |
571
- | `align` | `Align` | `start` | |
572
- | `className` | `string` | | |
629
+ | `align` | `Align` | `start` | Alignment against the trigger along `side`. |
630
+ | `children` | `ReactNode` | | Popup content, e.g. details or actions. |
631
+ | `className` | `string` | | Goes on the popup (role `dialog`). |
573
632
  | `defaultOpen` | `boolean` | `false` | Whether the popover is initially open. To render a controlled popover, use the `open` prop instead. |
574
- | `description` | `ReactNode` | | |
633
+ | `description` | `ReactNode` | | Muted text under the title, linked as the dialog's description. |
575
634
  | `onOpenChange` | `((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)` | | Event handler called when the popover is opened or closed. |
576
635
  | `open` | `boolean` | | Whether the popover is currently open. |
636
+ | `popupProps` | `PartProps<PopoverPopupProps>` | | Props for the popup (role `dialog`), e.g. `{ 'data-testid': 'run-popover' }`. |
577
637
  | `portalContainer` | `PortalContainerTarget` | | Where the popup renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
578
- | `side` | `Side` | `bottom` | |
638
+ | `side` | `Side` | `bottom` | Side of the trigger the popup opens on. |
579
639
  | `title` | `ReactNode` | | Names the popover dialog. Recommended for accessibility. |
580
640
  | `trigger` * | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | | The element that toggles the popover, e.g. `<Button>`. It must accept a ref and props. |
581
641
 
@@ -588,6 +648,7 @@ Modal and Drawer already do this for their content.
588
648
 
589
649
  | Prop | Type | Default | Description |
590
650
  | --- | --- | --- | --- |
651
+ | `children` | `ReactNode` | | Content whose popups render into `container`. |
591
652
  | `container` * | `PortalContainerTarget` | | The element popups render into, e.g. a native `<dialog>` opened with `showModal()`. |
592
653
 
593
654
  ### ProgressBar
@@ -598,14 +659,14 @@ The count and `aria-valuenow` are the finished runs (done + failed).
598
659
  | Prop | Type | Default | Description |
599
660
  | --- | --- | --- | --- |
600
661
  | `className` | `string` | | |
601
- | `done` * | `number` | | |
602
- | `failed` | `number` | `0` | |
603
- | `hideCount` | `boolean` | `false` | Hides the "n/total" count. |
662
+ | `done` * | `number` | | Runs that finished successfully. |
663
+ | `failed` | `number` | `0` | Runs that finished with an error. |
664
+ | `hideCount` | `boolean` | `false` | Hides the "n/total" count and the failed and running counts beside it. |
604
665
  | `label` | `ReactNode` | | Shown above the bar. Without it, pass `aria-label`. |
605
666
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ProgressRootState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
606
- | `running` | `number` | `0` | |
667
+ | `running` | `number` | `0` | Runs in progress (pulsing segment). |
607
668
  | `style` | `CSSProperties \| ((state: ProgressRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
608
- | `total` * | `number` | | |
669
+ | `total` * | `number` | | All runs in the batch. The rest are waiting. |
609
670
 
610
671
  ### RadioCards
611
672
 
@@ -613,25 +674,22 @@ A radio group drawn as selectable cards, each with a title and optional descript
613
674
 
614
675
  | Prop | Type | Default | Description |
615
676
  | --- | --- | --- | --- |
616
- | `className` | `string` | | |
617
- | `defaultValue` | `string` | | The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
677
+ | `className` | `string` | | Class for the field's root element. |
678
+ | `defaultValue` | `string \| null` | | The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
618
679
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
619
- | `disabled` | `boolean` | | |
680
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
620
681
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
621
682
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
622
683
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
623
684
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
624
685
  | `name` | `string` | | Identifies the field when a form is submitted. |
625
- | `onValueChange` | `((value: string) => void)` | | |
626
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
627
- | `options` * | `RadioCardOption[]` | | |
686
+ | `onValueChange` | `((value: string) => void)` | | Called with the chosen option's `value`. |
687
+ | `options` * | `RadioCardOption[]` | | The cards, in order. |
628
688
  | `orientation` | `"horizontal" \| "vertical"` | `vertical` | Lay the cards out in a row (wrapping) instead of a column. |
629
689
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the group's hidden input (for form libraries). |
630
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
631
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
632
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
690
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
633
691
  | `style` | `CSSProperties \| ((state: RadioGroupState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
634
- | `value` | `string` | | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |
692
+ | `value` | `string \| null` | | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |
635
693
 
636
694
  ### SaveBar
637
695
 
@@ -641,11 +699,11 @@ Sticky bar at the bottom of an editable page, shown while there are unsaved chan
641
699
  | --- | --- | --- | --- |
642
700
  | `changes` * | `number` | | Number of unsaved changes. The bar renders nothing when this is 0. |
643
701
  | `context` | `ReactNode` | | Extra context, e.g. "on branch main". |
644
- | `discardLabel` | `string` | `Discard` | |
645
- | `onDiscard` | `(() => void)` | | |
646
- | `onSave` * | `() => void` | | |
647
- | `saveLabel` | `string` | `Save changes` | |
648
- | `saving` | `boolean` | `false` | |
702
+ | `discardLabel` | `string` | `Discard` | Discard button text. |
703
+ | `onDiscard` | `(() => void)` | | Adds a Discard button when given. |
704
+ | `onSave` * | `() => void` | | Called by the Save button. |
705
+ | `saveLabel` | `string` | `Save changes` | Save button text. |
706
+ | `saving` | `boolean` | `false` | Shows a spinner on Save and disables Discard while saving. |
649
707
 
650
708
  ### Select
651
709
 
@@ -653,30 +711,30 @@ Single-choice dropdown with a label.
653
711
 
654
712
  | Prop | Type | Default | Description |
655
713
  | --- | --- | --- | --- |
656
- | `className` | `string` | | |
714
+ | `className` | `string` | | Goes on the field's root element. |
657
715
  | `defaultOpen` | `boolean` | `false` | Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead. |
658
- | `defaultValue` | `string \| null` | | |
716
+ | `defaultValue` | `string \| null` | | The initially picked option's `value`, when uncontrolled. |
659
717
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
660
- | `disabled` | `boolean` | | |
718
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
661
719
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
662
720
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
663
721
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
722
+ | `id` | `string` | | Goes on the trigger button, so `<label htmlFor>` and `getElementById(id).focus()` work. |
664
723
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
665
724
  | `name` | `string` | | Identifies the field when a form is submitted. |
666
725
  | `onOpenChange` | `((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)` | | Event handler called when the select popup is opened or closed. |
667
- | `onValueChange` | `((value: string \| null) => void)` | | Called when the value changes. Re-picking the current option doesn't call it. |
726
+ | `onValueChange` | `((value: string \| null) => void)` | | Called when the value changes. Re-picking the current option doesn't call it. Picking from the list always gives an option's `value`; `null` only comes from a form reset back to an empty initial value, so with a picked initial value it's safe to treat it as a `string`. |
668
727
  | `open` | `boolean` | | Whether the select popup is currently open. |
669
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
670
- | `options` * | `SelectOption[]` | | |
671
- | `placeholder` | `string` | `Select an option` | Shown while nothing is selected. |
728
+ | `options` * | `SelectOption[]` | | The choices, in order. |
729
+ | `placeholder` | `string` | `Select an option` | Shown while nothing is selected, or when `value` matches no option. |
672
730
  | `popupProps` | `PartProps<SelectPopupProps>` | | Props for the dropdown (role `listbox`), e.g. `{ 'data-testid': 'plan-options' }`. |
731
+ | `popupWidth` | `string` | | Width of the dropdown when it should be wider than the field, e.g. `'24rem'`. Never narrower than the field. |
673
732
  | `portalContainer` | `PortalContainerTarget` | | Where the dropdown renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
674
733
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the hidden input that holds the value (for form libraries). |
675
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
676
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
677
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
734
+ | `renderValue` | `((option: SelectOption \| null) => ReactNode)` | | What the trigger shows for the picked option (`null` when none matches). Defaults to its `label`, else the placeholder. |
735
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
678
736
  | `triggerProps` | `PartProps<SelectTriggerProps>` | | Props for the trigger button (role `combobox`), e.g. `{ 'data-testid': 'plan-select' }`. |
679
- | `value` | `string \| null` | | |
737
+ | `value` | `string \| null` | | The picked option's `value`, or `null` for none. Use with `onValueChange` to control it. A value that matches no option shows the placeholder. |
680
738
 
681
739
  ### Skeleton
682
740
 
@@ -685,10 +743,10 @@ mark the loading region with `aria-busy` instead.
685
743
 
686
744
  | Prop | Type | Default | Description |
687
745
  | --- | --- | --- | --- |
688
- | `height` | `Height<string \| number>` | | |
746
+ | `height` | `Height<string \| number>` | | A CSS length. Numbers are px at the 16px base, converted to rem (like `width`). |
689
747
  | `lines` | `number` | `1` | For `text`, renders this many lines, the last one shorter. |
690
748
  | `variant` | `"circle" \| "text" \| "block"` | `block` | `text` is a line of text, `circle` is an avatar (sized by `height`). |
691
- | `width` | `Width<string \| number>` | | |
749
+ | `width` | `Width<string \| number>` | | A CSS length. Numbers are px at the 16px base, converted to rem so they scale with the text-size setting. |
692
750
 
693
751
  ### Stack
694
752
 
@@ -696,11 +754,11 @@ Flex layout that spaces its children. Renders nothing when it has no children.
696
754
 
697
755
  | Prop | Type | Default | Description |
698
756
  | --- | --- | --- | --- |
699
- | `align` | `"center" \| "end" \| "baseline" \| "start" \| "stretch"` | | |
700
- | `direction` | `"row" \| "column"` | `column` | |
701
- | `gap` | `"0" \| "0.5" \| "1" \| "1.5" \| "2" \| "2.5" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12"` | `4` | Space between children, from the `space` scale (`'4'` is 16px). |
702
- | `justify` | `"center" \| "end" \| "start" \| "between"` | | |
703
- | `wrap` | `boolean` | `false` | |
757
+ | `align` | `"center" \| "start" \| "end" \| "stretch" \| "baseline"` | | Cross-axis alignment (`align-items`). |
758
+ | `direction` | `"row" \| "column"` | `column` | `column` (default) stacks children; `row` lines them up. |
759
+ | `gap` | `"1" \| "2" \| "3" \| "4" \| "6" \| "8"` | `4` | Space between children: `'1'` 4px, `'2'` 8px, `'3'` 12px, `'4'` 16px (default), `'6'` 24px, `'8'` 32px. |
760
+ | `justify` | `"center" \| "start" \| "end" \| "between"` | | Main-axis distribution (`justify-content`). |
761
+ | `wrap` | `boolean` | `false` | Let children wrap onto new lines, e.g. a row of filters. |
704
762
 
705
763
  ### StatCard
706
764
 
@@ -708,17 +766,13 @@ A headline number on a card, e.g. "Objective achieved 64%".
708
766
 
709
767
  | Prop | Type | Default | Description |
710
768
  | --- | --- | --- | --- |
711
- | `caption` | `ReactNode` | | |
712
- | `label` * | `ReactNode` | | |
713
- | `value` * | `ReactNode` | | |
769
+ | `caption` | `ReactNode` | | Small muted context under the value, e.g. "7 of 11 judged". |
770
+ | `label` * | `ReactNode` | | What the number is, e.g. "Objective achieved". |
771
+ | `value` * | `ReactNode` | | The headline number, formatted, e.g. "64%". |
714
772
 
715
773
  ### StatsGrid
716
774
 
717
- Responsive grid for stat tiles. Columns fill the row and wrap below `minColumnWidth`.
718
-
719
- | Prop | Type | Default | Description |
720
- | --- | --- | --- | --- |
721
- | `minColumnWidth` | `string` | | Narrowest a column may get before the grid wraps, as a CSS length. Default `14rem`. |
775
+ Responsive grid for stat tiles. Columns fill the row and wrap when narrower than 14rem.
722
776
 
723
777
  ### StatusBadge
724
778
 
@@ -727,7 +781,7 @@ A pill showing a run's status as a coloured dot and label.
727
781
  | Prop | Type | Default | Description |
728
782
  | --- | --- | --- | --- |
729
783
  | `children` | `ReactNode` | | Overrides the default label (the capitalised status). |
730
- | `status` * | `Status` | | |
784
+ | `status` * | `Status` | | Sets the colour and the default label. |
731
785
 
732
786
  ### Switch
733
787
 
@@ -736,21 +790,18 @@ On/off toggle with its label beside it. Toggle with Space or Enter.
736
790
  | Prop | Type | Default | Description |
737
791
  | --- | --- | --- | --- |
738
792
  | `checked` | `boolean` | | Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead. |
739
- | `className` | `string` | | |
793
+ | `className` | `string` | | Class for the field's root element. |
740
794
  | `defaultChecked` | `boolean` | `false` | Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead. |
741
795
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
742
- | `disabled` | `boolean` | | |
796
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
743
797
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
744
798
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
745
799
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
746
800
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
747
801
  | `name` | `string` | | Identifies the field when a form is submitted. |
748
802
  | `onCheckedChange` | `((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void)` | | Event handler called when the switch is activated or deactivated. |
749
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
750
803
  | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the hidden checkbox input (for form libraries). |
751
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
752
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
753
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
804
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
754
805
  | `style` | `CSSProperties \| ((state: SwitchRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
755
806
  | `value` | `string` | | The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior. |
756
807
 
@@ -761,17 +812,17 @@ Searchable switcher, e.g. "pick a customer or branch" in a breadcrumb or top bar
761
812
  | Prop | Type | Default | Description |
762
813
  | --- | --- | --- | --- |
763
814
  | `className` | `string` | | Goes on the trigger. |
764
- | `defaultOpen` | `boolean` | `false` | |
765
- | `disabled` | `boolean` | | |
766
- | `emptyMessage` | `ReactNode` | `No matches` | |
815
+ | `defaultOpen` | `boolean` | `false` | Whether the popup starts open, when uncontrolled. |
816
+ | `disabled` | `boolean` | | The trigger can't be used. |
817
+ | `emptyMessage` | `ReactNode` | `No matches` | Shown when nothing matches the filter. |
767
818
  | `footer` | `SwitcherFooter` | | A link or action under the list, e.g. "View all customers". |
768
- | `items` * | `SwitcherItem[]` | | |
819
+ | `items` * | `SwitcherItem[]` | | The rows to pick from. |
769
820
  | `label` * | `string` | | What is being switched, e.g. "Customer". Names the trigger ("Customer: O2") and the popup. |
770
- | `loading` | `boolean` | `false` | |
771
- | `loadingLabel` | `string` | `Loading…` | |
772
- | `onOpenChange` | `((open: boolean) => void)` | | |
821
+ | `loading` | `boolean` | `false` | Shows `loadingLabel` with a spinner instead of the rows, e.g. while they're fetched. |
822
+ | `loadingLabel` | `string` | `Loading…` | Text shown (and announced) while `loading`. |
823
+ | `onOpenChange` | `((open: boolean) => void)` | | Called when the popup opens or closes. |
773
824
  | `onSelect` | `((item: SwitcherItem) => void)` | | Called when a different item is picked (by click or Enter). Link items navigate as well. |
774
- | `open` | `boolean` | | |
825
+ | `open` | `boolean` | | Whether the popup is open. Use with `onOpenChange` to control it. |
775
826
  | `placeholder` | `string` | `Select…` | Trigger text when there is no current item. |
776
827
  | `popupProps` | `PartProps<ComboboxPopupProps>` | | Props for the popup (role `dialog`, named by `label`). |
777
828
  | `portalContainer` | `PortalContainerTarget` | | Where the popup renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
@@ -784,20 +835,31 @@ Searchable switcher, e.g. "pick a customer or branch" in a breadcrumb or top bar
784
835
  ### Table
785
836
 
786
837
  A data table. Pass `columns` and `rows`, or compose `Table.Root`, `Table.Head`, `Table.Body`,
787
- `Table.Row`, `Table.HeaderCell` and `Table.Cell` for custom layouts.
838
+ `Table.Row`, `Table.GroupRow`, `Table.HeaderCell` and `Table.Cell` for custom layouts.
788
839
 
789
840
  | Prop | Type | Default | Description |
790
841
  | --- | --- | --- | --- |
791
- | `columns` * | `TableColumn<Row>[]` | | |
792
- | `density` | `"default" \| "compact"` | | |
793
- | `empty` | `ReactNode` | | Shown when there are no rows. |
794
- | `getRowKey` * | `(row: Row) => Key` | | |
842
+ | `caption` | `ReactNode` | | The table's `<caption>`, which names it. Visually hidden unless `captionVisible`. |
843
+ | `captionVisible` | `boolean` | | Shows the caption above the table. |
844
+ | `columns` * | `TableColumn<Row>[]` | | Column definitions, left to right. |
845
+ | `defaultSort` | `SortState` | | Initially sorted column (uncontrolled). |
846
+ | `density` | `"default" \| "compact"` | | `compact` tightens cell padding for dense data. |
847
+ | `empty` | `ReactNode` | | Shown when there are no rows, across all columns. Can be a block such as an empty state. |
848
+ | `footer` | `ReactNode` | | Shown under the table, inside the frame, e.g. `Table.LoadMore` or `Pagination`. Doesn't scroll sideways. |
849
+ | `getRowHref` | `((row: Row) => string)` | | Makes each row a link: the primary column's content becomes an `<a href>` (so middle-click and "open in new tab" work), and a click anywhere else on the row follows it. `onRowClick`, if set, is also called. |
850
+ | `getRowKey` * | `(row: Row) => Key` | | A stable, unique key for each row, e.g. `(row) => row.id`. |
795
851
  | `getRowProps` | `((row: Row) => ClassAttributes<HTMLTableRowElement> & HTMLAttributes<HTMLTableRowElement> & DataAttributes)` | | Props for each row's `<tr>`, e.g. `(row) => ({ 'data-testid': `run-${row.id}` })`. |
852
+ | `groupBy` | `((row: Row) => Key)` | | Groups rows under full-width headings. Groups appear in first-seen order. |
796
853
  | `loading` | `boolean` | | Shows skeleton rows while there are no rows yet. Existing rows stay during a refetch. |
797
- | `onRowClick` | `((row: Row) => void)` | | Makes each row clickable. The primary column's cell becomes a button (so keyboard and screen reader users reach it with Tab and press Enter or Space), and a click anywhere else on the row clicks it too. Clicks on other buttons, links or inputs in the row are left alone. Don't put interactive content in the primary column. |
798
- | `primaryColumn` | `string` | | `key` of the column that holds the row's button. Defaults to the first column. |
799
- | `rows` * | `Row[]` | | |
800
- | `scrollRef` | `Ref<HTMLDivElement>` | | Ref to the card-framed `<div>` that scrolls the table sideways, e.g. for scroll hints. |
854
+ | `onRowClick` | `((row: Row) => void)` | | Makes each row clickable. The primary column's cell becomes a button (so keyboard and screen reader users reach it with Tab and press Enter or Space), and a click anywhere else on the row clicks it too. Clicks on other buttons, links or inputs in the row are left alone. Don't put interactive content in the primary column; use the column's `extra` for tags and the like. |
855
+ | `onSortChange` | `((sort: SortState) => void)` | | Called when a sortable header is clicked. A new column sorts descending first; clicking the sorted column flips its direction. Without the column's `compare`, sort the rows yourself. |
856
+ | `primaryColumn` | `string` | | `key` of the column that holds the row's button or link. Defaults to the first column. |
857
+ | `renderGroup` | `((key: Key, rows: Row[]) => ReactNode)` | | The group heading. Defaults to the key. |
858
+ | `rowLinkRender` | `((row: Row) => ReactElement<unknown, string \| JSXElementConstructor<any>>)` | | A router link per row instead of `getRowHref`, e.g. `(run) => <Link to={`/runs/${run.id}`} />`. |
859
+ | `rows` * | `Row[]` | | The data, one row each. |
860
+ | `scrollRef` | `Ref<HTMLDivElement>` | | Ref to the `<div>` that scrolls the table sideways, e.g. for scroll hints. |
861
+ | `sort` | `SortState` | | Sorted column (controlled). |
862
+ | `stale` | `boolean` | | Rows are out of date, e.g. while new filters load. The table is `aria-busy`, and after 300ms (so quick loads don't flicker) a progress bar slides along its top edge. |
801
863
 
802
864
  ### TableAction
803
865
 
@@ -806,13 +868,12 @@ An icon-only ghost button for table rows, labelled by a tooltip.
806
868
  | Prop | Type | Default | Description |
807
869
  | --- | --- | --- | --- |
808
870
  | `aria-label` * | `string` | | Names the button and is shown as its tooltip. |
809
- | `fullWidth` | `boolean` | | |
871
+ | `fullWidth` | `boolean` | | Stretches the button to fill its container. |
810
872
  | `icon` * | `ReactNode` | | A decorative icon, e.g. `<Pencil size="1.38em" aria-hidden />`. |
811
873
  | `loading` | `boolean` | | Shows a spinner and blocks clicks, keeping the button's width and focus. A loading button is `aria-disabled="true"` and `aria-busy="true"`, not native `disabled`, so it stays focusable (assert `aria-disabled` in tests, not `toBeDisabled()`). |
812
874
  | `loadingLabel` | `string` | | Text announced to assistive tech while `loading`, e.g. "Saving". It becomes the button's accessible name and is read out through a polite live region, a visually hidden `role="status"` span rendered next to the button. |
813
875
  | `render` | `RenderProp<Record<string, unknown>>` | | Render a different element, e.g. `render={<a href="/runs" />}` or a router `<Link to="/runs" />`. |
814
- | `showLoadingLabel` | `boolean` | | Shows `loadingLabel` next to the spinner instead of the content (the width may change). |
815
- | `size` | `"sm" \| "md"` | `sm` | |
876
+ | `size` | `"sm" \| "md"` | `sm` | `sm` for dense places such as table rows and toolbars. |
816
877
 
817
878
  ### Tabs
818
879
 
@@ -821,14 +882,14 @@ Underline tabs with optional counts ("Conversation 13"). Pass `items`, or compos
821
882
  | Prop | Type | Default | Description |
822
883
  | --- | --- | --- | --- |
823
884
  | `className` | `string` | | |
824
- | `defaultValue` | `any` | `0` | The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active. |
825
- | `items` * | `TabItem[]` | | |
885
+ | `defaultValue` | `string` | | The tab active at first (uncontrolled). |
886
+ | `items` * | `TabItem<Value>[]` | | The tabs, in order. The first enabled one is selected unless `value`/`defaultValue` says otherwise. |
826
887
  | `keepMounted` | `boolean` | | Keeps hidden panels in the DOM, so form fields in other tabs stay registered and keep their state. Panels unmount while hidden by default. |
827
888
  | `listProps` | `PartProps<TabsListProps>` | | Props for the tab row (role `tablist`). |
828
- | `onValueChange` | `((value: any, eventDetails: TabsRootChangeEventDetails) => void)` | | Callback invoked when new value is being set. The event `reason` is `'none'` for user-initiated changes, such as a click or keyboard navigation; `'initial'` for the first automatic selection or fallback in uncontrolled roots when `defaultValue` is omitted or `undefined`, including when the implicit initial value is disabled or missing; `'disabled'` for automatic fallback when the selected tab becomes disabled in uncontrolled roots; or `'missing'` for automatic fallback when the selected tab is removed, or when an explicit `defaultValue` never matches a mounted tab in uncontrolled roots. For automatic changes, the selected value can be `null` when no enabled Tab is available as a fallback. Automatic changes cannot be canceled; calling `eventDetails.cancel()` for `'initial'`, `'disabled'`, or `'missing'` has no effect. |
889
+ | `onValueChange` | `((value: Value, eventDetails: TabsRootChangeEventDetails) => void)` | | Called with the newly active tab's value. |
829
890
  | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsRootState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
830
891
  | `style` | `CSSProperties \| ((state: TabsRootState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
831
- | `value` | `any` | | The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active. |
892
+ | `value` | `string` | | The active tab's value (controlled). |
832
893
 
833
894
  ### Tag
834
895
 
@@ -836,31 +897,30 @@ A small rectangular mono label, e.g. an input method or event type.
836
897
 
837
898
  | Prop | Type | Default | Description |
838
899
  | --- | --- | --- | --- |
839
- | `selected` | `boolean` | `false` | Accent-tinted, e.g. the active value in a group of tags. |
900
+ | `selected` | `boolean` | `false` | Accent-tinted with a leading check, e.g. the active value in a group of tags. |
901
+ | `tone` | `TagTone` | `neutral` | Colour. `neutral` (default) is plain; the others carry meaning, as in `Badge`. |
840
902
 
841
903
  ### Textarea
842
904
 
843
- Multi-line text input with a label.
905
+ Multi-line text input with a label. Grows to fit its content (CSS `field-sizing`; browsers without it get a resize handle).
844
906
 
845
907
  | Prop | Type | Default | Description |
846
908
  | --- | --- | --- | --- |
847
909
  | `countLimit` | `number` | | Soft limit: shows "count/countLimit" without setting native `maxLength`, so people can type past it. Over the limit the count turns red and gets `data-over="true"`; show an `error` too. |
848
910
  | `defaultValue` | `string \| number \| readonly string[]` | | |
849
911
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
850
- | `disabled` | `boolean` | | |
912
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
851
913
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
852
914
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
853
915
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
854
916
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
855
917
  | `name` | `string` | | |
856
918
  | `onValueChange` | `((value: string) => void)` | | Called with the new string value on every change. |
857
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
858
919
  | `placeholder` | `string` | | |
859
- | `ref` | `Ref<HTMLTextAreaElement>` | | |
860
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
861
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
920
+ | `ref` | `Ref<HTMLTextAreaElement>` | | Forwarded to the `<textarea>` (for form libraries). |
921
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
922
+ | `rows` | `number` | `3` | Lines shown when empty (default 3). It then grows with its content, up to 15 lines, and scrolls after that. |
862
923
  | `showCount` | `boolean` | `false` | Shows "count/maxLength" under the textarea. Needs `maxLength`, which stops typing at the limit. |
863
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
864
924
  | `value` | `string \| number \| readonly string[]` | | |
865
925
 
866
926
  ### TextInput
@@ -869,80 +929,116 @@ Single-line text input with a label. Spread `register('name')` from react-hook-f
869
929
 
870
930
  | Prop | Type | Default | Description |
871
931
  | --- | --- | --- | --- |
932
+ | `className` | `string` | | Goes on the field's root element, not the `<input>`. Use `inputProps.className` for that. |
872
933
  | `countLimit` | `number` | | Soft limit: shows "count/countLimit" without setting native `maxLength`, so people can type past it. Over the limit the count turns red and gets `data-over="true"`; show an `error` too. |
873
934
  | `defaultValue` | `string \| number \| readonly string[]` | | |
874
935
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
875
- | `disabled` | `boolean` | | |
936
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
876
937
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
877
938
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
878
939
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
940
+ | `id` | `string` | | Goes on the `<input>`, so `<label htmlFor>` and `getElementById(id).focus()` work. |
941
+ | `inputProps` | `PartProps<Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">>` | | Extra props for the `<input>`, e.g. `{ className, 'data-testid': 'name' }`. |
879
942
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
880
943
  | `name` | `string` | | |
881
944
  | `onValueChange` | `((value: string) => void)` | | Called with the new string value on every change. |
882
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
883
945
  | `placeholder` | `string` | | |
884
- | `ref` | `Ref<HTMLInputElement>` | | |
885
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
886
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
946
+ | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the `<input>` (for form libraries, and to focus it). |
947
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
887
948
  | `showCount` | `boolean` | `false` | Shows "count/maxLength" inside the input. Needs `maxLength`, which stops typing at the limit. |
888
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
889
949
  | `value` | `string \| number \| readonly string[]` | | |
890
950
 
951
+ ### ThemeMenu
952
+
953
+ A compact theme switch: an icon button showing the current theme that opens a menu of themes.
954
+ Made for the `NavRail` footer, so it opens to the right by default.
955
+
956
+ | Prop | Type | Default | Description |
957
+ | --- | --- | --- | --- |
958
+ | `align` | `Align` | `end` | How the menu lines up with the trigger along that side. |
959
+ | `className` | `string` | | Goes on the popup (role `menu`). |
960
+ | `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
961
+ | `label` | `string` | `Theme` | Accessible name of the trigger, and the heading above the options. |
962
+ | `onOpenChange` | `((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)` | | Event handler called when the menu is opened or closed. |
963
+ | `open` | `boolean` | | Whether the menu is currently open. |
964
+ | `popupProps` | `PartProps<MenuPopupProps>` | | Props for the popup (role `menu`), e.g. `{ 'data-testid': 'account-menu' }`. |
965
+ | `portalContainer` | `PortalContainerTarget` | | Where the menu renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
966
+ | `side` | `Side` | `right` | Which side of the trigger the menu opens on. It flips if there isn't room. |
967
+ | `themes` | `readonly ("light" \| "dark" \| "sand" \| "system")[]` | `['light', 'dark', 'sand', 'system'] as const` | The themes offered, in order. Defaults to all of them. |
968
+
891
969
  ### ThemePicker
892
970
 
893
971
  Lets the user pick a theme. Each option previews itself in its own colours.
894
972
 
895
973
  | Prop | Type | Default | Description |
896
974
  | --- | --- | --- | --- |
897
- | `label` | `string` | `Theme` | |
898
- | `onChange` | `((theme: "light" \| "dark" \| "sand" \| "system") => void)` | | |
899
- | `options` | `ThemeOption[]` | `[ { value: 'light', label: 'Light', palettes: ['light'] }, { value: 'sand', label: 'Sand', palettes: ['sand'] }, { value: 'dark', label: 'Dark', palettes: ['dark'] }, { value: 'system', label: 'System', palettes: ['light', 'dark'] }, ]` | |
900
- | `value` | `"light" \| "dark" \| "sand" \| "system"` | | Controlled value. Omit `value` and `onChange` to drive the app theme via `useTheme`. |
975
+ | `label` | `string` | `Theme` | Visible group label (the `<legend>`). |
976
+ | `onChange` | `((theme: "light" \| "dark" \| "sand" \| "system") => void)` | | Called with the picked theme. |
977
+ | `options` | `ThemeOption[]` | `[ { value: 'light', label: 'Light', palettes: ['light'] }, { value: 'sand', label: 'Sand', palettes: ['sand'] }, { value: 'dark', label: 'Dark', palettes: ['dark'] }, { value: 'system', label: 'System', palettes: ['light', 'dark'] }, ]` | The themes offered, in order. Defaults to `defaultThemeOptions` (light, sand, dark, system). |
978
+ | `value` | `"light" \| "dark" \| "sand" \| "system"` | | Controlled value: the picker shows it and only calls `onChange`. Omit it to drive the app theme (`useTheme`); `onChange` is then still called, e.g. to save the choice to a profile. |
979
+
980
+ ### TimeInput
981
+
982
+ Time picker using the browser's native time input. The value is `HH:MM` (24-hour).
983
+
984
+ | Prop | Type | Default | Description |
985
+ | --- | --- | --- | --- |
986
+ | `defaultValue` | `string \| number \| readonly string[]` | | |
987
+ | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
988
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
989
+ | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
990
+ | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
991
+ | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
992
+ | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
993
+ | `name` | `string` | | |
994
+ | `onValueChange` | `((value: string) => void)` | | Called with the 24-hour time, e.g. `'09:30'`, or `''` when cleared. |
995
+ | `placeholder` | `string` | | |
996
+ | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the `<input>` (for form libraries). |
997
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
998
+ | `value` | `string \| number \| readonly string[]` | | |
901
999
 
902
1000
  ### ToggleGroup
903
1001
 
904
- Segmented control: pick one of a few options. Arrow keys move between options.
1002
+ Segmented control: pick one of a few options. It's a radio group, so it submits `name` with a
1003
+ form, supports `required`, and arrow keys move the selection. With `multiple` it's a group of
1004
+ checkboxes: any number can be on, `value` is a `string[]`, and `required` only adds the asterisk.
905
1005
 
906
1006
  | Prop | Type | Default | Description |
907
1007
  | --- | --- | --- | --- |
908
- | `className` | `string` | | |
909
- | `defaultValue` | `string \| null` | `null` | |
1008
+ | `className` | `string` | | Class for the field's root element. |
1009
+ | `defaultValue` | `string \| null` | | The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead. |
910
1010
  | `description` | `ReactNode` | | Help text under the input, linked with `aria-describedby`. |
911
- | `disabled` | `boolean` | | |
1011
+ | `disabled` | `boolean` | | Disables the input and greys out the label. |
912
1012
  | `error` | `ReactNode` | | Error message. When set, the input is marked invalid and the message is announced. |
913
1013
  | `fieldProps` | `FieldRootProps` | | Props for the field's root element, e.g. `{ 'data-testid': 'name-field' }`. `className` already goes there. |
914
1014
  | `hideLabel` | `boolean` | | Hides the label visually. It still names the input for screen readers and tests. |
915
1015
  | `label` | `ReactNode` | | Visible label, also the input's accessible name. |
916
- | `name` | `string` | | Submits the value with a form via a hidden input. |
917
- | `onValueChange` | `((value: string) => void)` | | |
918
- | `optionalText` | `ReactNode` | | Text for `requiredIndicator="optional-note"`. |
919
- | `options` * | `ToggleGroupOption[]` | | |
920
- | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the hidden input. |
921
- | `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ToggleGroupState>` | | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
922
- | `required` | `boolean` | | Marks the label with an asterisk (the input gets native `required`). |
923
- | `requiredIndicator` | `RequiredIndicator` | | `asterisk` (default) marks required fields with `*`. `optional-note` instead adds `optionalText` to fields that aren't required. `none` shows neither. |
924
- | `showRequired` | `boolean` | | Shows the field as required (marker and `aria-required`) without native `required`, e.g. when a form library validates instead of the browser. |
1016
+ | `multiple` | `boolean` | | |
1017
+ | `name` | `string` | | Identifies the field when a form is submitted. |
1018
+ | `onValueChange` | `((value: string) => void) \| ((value: string[]) => void)` | | Called with the chosen option's `value`. Called with the values of the selected options. |
1019
+ | `options` * | `ToggleGroupOption[]` | | The segments, in order. Keep to 2–4 short labels. |
1020
+ | `ref` | `Ref<HTMLInputElement>` | | Forwarded to the group's hidden input (for form libraries). Single selection only. |
1021
+ | `required` | `boolean` | | Native `required`: the label gets an asterisk and the browser blocks submitting an empty field. When a form library validates instead, keep `required` and put `noValidate` on the `<form>`. |
925
1022
  | `size` | `"sm" \| "md"` | `md` | `sm` is a compact control for use inside forms and toolbars. |
926
- | `style` | `CSSProperties \| ((state: ToggleGroupState) => CSSProperties)` | | Style applied to the element, or a function that returns a style object based on the component's state. |
927
- | `value` | `string \| null` | | |
1023
+ | `style` | `CSSProperties \| ((state: CheckboxGroupState) => CSSProperties) \| ((state: RadioGroupState) => CSSProperties) \| undefined` | | Style applied to the element, or a function that returns a style object based on the component's state. |
1024
+ | `value` | `string \| null` | | The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead. |
928
1025
 
929
1026
  ### Tooltip
930
1027
 
931
- A short inverted label shown on hover and keyboard focus.
1028
+ A short inverted label shown on hover and keyboard focus. It's visual only, so give the trigger
1029
+ an accessible name too, e.g. `aria-label` matching `label` on an icon-only button.
932
1030
 
933
1031
  | Prop | Type | Default | Description |
934
1032
  | --- | --- | --- | --- |
935
- | `align` | `Align` | `center` | |
1033
+ | `align` | `Align` | `center` | Alignment against the trigger along `side`. |
936
1034
  | `children` * | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | | The trigger element. It must accept a ref and props, e.g. a `<button>` or our `Button`. |
937
- | `className` | `string` | | |
1035
+ | `className` | `string` | | Goes on the popup. |
938
1036
  | `defaultOpen` | `boolean` | `false` | Whether the tooltip is initially open. To render a controlled tooltip, use the `open` prop instead. |
939
- | `delay` | `number` | `300` | Hover delay in ms. |
940
- | `label` * | `ReactNode` | | |
1037
+ | `label` * | `ReactNode` | | The tooltip text. Visual only: screen readers don't get it, so the trigger needs its own name. |
941
1038
  | `onOpenChange` | `((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)` | | Event handler called when the tooltip is opened or closed. |
942
1039
  | `open` | `boolean` | | Whether the tooltip is currently open. |
943
1040
  | `portalContainer` | `PortalContainerTarget` | | Where the popup renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
944
- | `side` | `Side` | `top` | |
945
- | `withArrow` | `boolean` | `true` | |
1041
+ | `side` | `Side` | `top` | Side of the trigger the tooltip shows on. |
946
1042
 
947
1043
  ### TopBar
948
1044
 
@@ -963,8 +1059,8 @@ Account menu: avatar button that opens a menu of account actions. Fits the NavRa
963
1059
 
964
1060
  | Prop | Type | Default | Description |
965
1061
  | --- | --- | --- | --- |
966
- | `align` | `Align` | `end` | |
967
- | `avatarSrc` | `string` | | |
1062
+ | `align` | `Align` | `end` | How the menu lines up with the trigger along that side. |
1063
+ | `avatarSrc` | `string` | | Avatar image URL. Falls back to initials. |
968
1064
  | `className` | `string` | | Goes on the popup (role `menu`). |
969
1065
  | `defaultOpen` | `boolean` | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
970
1066
  | `email` | `string` | | Shown under the name in the default header. |
@@ -978,10 +1074,20 @@ Account menu: avatar button that opens a menu of account actions. Fits the NavRa
978
1074
  | `popupProps` | `PartProps<MenuPopupProps>` | | Props for the popup (role `menu`), e.g. `{ 'data-testid': 'account-menu' }`. |
979
1075
  | `portalContainer` | `PortalContainerTarget` | | Where the menu renders. Defaults to the nearest `PortalContainer`, else `document.body`. |
980
1076
  | `showName` | `boolean` | `false` | Show the name next to the avatar (e.g. in an expanded NavRail). |
981
- | `side` | `Side` | `right` | |
982
- | `signOutLabel` | `string` | `Sign out` | |
1077
+ | `side` | `Side` | `right` | Which side of the trigger the menu opens on. It flips if there isn't room. |
1078
+ | `signOutLabel` | `string` | `Sign out` | Text of the Sign out item. |
983
1079
  | `signOutProps` | `MenuItemElementProps` | | Props for the Sign out item, e.g. `{ 'data-testid': 'sign-out' }`. |
984
- | `triggerProps` | `(ClassAttributes<HTMLButtonElement> & ButtonHTMLAttributes<HTMLButtonElement> & { [data: `data-${string}`]: string; })` | | Props for the trigger button, e.g. `aria-label` or `data-testid`. |
1080
+ | `triggerProps` | `(ClassAttributes<HTMLButtonElement> & ButtonHTMLAttributes<HTMLButtonElement> & DataAttributes)` | | Props for the trigger button, e.g. `aria-label` or `data-testid`. |
1081
+
1082
+ ## Helpers
1083
+
1084
+ Also exported from `@15gifts/back-office-kit`.
1085
+
1086
+ - `lastDuration(ms: number)`: The last `ms` milliseconds, ending now, e.g. `lastDuration(15 * 60_000)`.
1087
+ - `today(timeZone?: string)`: The whole of today, in `timeZone` (local when omitted).
1088
+ - `yesterday(timeZone?: string)`: The whole of yesterday, in `timeZone` (local when omitted).
1089
+ - `thisMonth(timeZone?: string)`: The whole of the current month, in `timeZone` (local when omitted).
1090
+ - `getDefaultPresets(timeZone?: string)`: The default quick ranges. Day-based ones follow `timeZone`.
985
1091
 
986
1092
  ## Theme and text size
987
1093
 
@@ -989,14 +1095,14 @@ Functions and hooks exported from `@15gifts/back-office-kit` (no provider needed
989
1095
 
990
1096
  - `FONT_SIZES`: Global text size. `md` (default) gives 14px body text, as in the original Back Office; `sm` and `lg` are about 6% smaller and larger. Everything in the library scales with it.
991
1097
  - `FONT_SIZE_STORAGE_KEY`: localStorage key used to remember the user's choice.
992
- - `getFontSize(): FontSize`: The active size, read from `<html data-font-size>`. Defaults to `md`.
993
- - `setFontSize(size: FontSize, { persist = true } = {})`: Sets `<html data-font-size>` and remembers the choice (unless `persist` is false).
1098
+ - `getFontSize: () => FontSize`: The active size, read from `<html data-font-size>`. Defaults to `md`.
1099
+ - `setFontSize: (size: FontSize, options?: { persist?: boolean }) => void`: Sets `<html data-font-size>` and remembers the choice (unless `persist` is false).
994
1100
  - `applyStoredFontSize(fallback: FontSize = 'md')`: Applies the saved size. Call once before the first render, next to `applyStoredTheme`.
995
1101
  - `useFontSize(): readonly [FontSize, (next: FontSize) => void]`: React hook over `getFontSize`/`setFontSize`. No provider needed.
996
1102
  - `THEME_STORAGE_KEY`: localStorage key used to remember the user's choice.
997
- - `getTheme(): Theme`: The active theme, read from `<html data-theme>`. Defaults to `system`.
1103
+ - `getTheme: () => Theme`: The active theme, read from `<html data-theme>`. Defaults to `system`.
998
1104
  - `getColorScheme(theme: Theme = getTheme()): ColorScheme`: Whether the page currently renders light or dark. Use it to drive libraries with their own dark mode.
999
- - `setTheme(theme: Theme, { persist = true } = {})`: Sets `<html data-theme>` and remembers the choice (unless `persist` is false).
1105
+ - `setTheme: (theme: Theme, options?: { persist?: boolean }) => void`: Sets `<html data-theme>` and remembers the choice (unless `persist` is false).
1000
1106
  - `applyStoredTheme(options: Theme | ApplyStoredThemeOptions = {})`: Applies the saved theme. Call once before the first render to avoid a flash of the wrong theme.
1001
1107
  - `useTheme(): readonly [Theme, (next: Theme) => void]`: React hook over `getTheme`/`setTheme`. No provider needed.
1002
1108
  - `useColorScheme(): ColorScheme`: The resolved `light`/`dark` scheme, updating on theme changes and OS changes.
@@ -1012,7 +1118,9 @@ export type BadgeTone =
1012
1118
  'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'highlight'
1013
1119
 
1014
1120
  export interface BreadcrumbItem {
1121
+ /** Crumb text, or a control such as a `Switcher` (then set `current: false`). */
1015
1122
  label: ReactNode
1123
+ /** Link target. Use `render` instead for a router link. Without either, the crumb is plain text. */
1016
1124
  href?: string
1017
1125
  /** Router link element, e.g. `<Link to="/customers" />`. */
1018
1126
  render?: ReactElement
@@ -1048,20 +1156,59 @@ export interface ChatMessage {
1048
1156
  messageProps?: Omit<ComponentProps<'div'>, 'role'> & DataAttributes
1049
1157
  }
1050
1158
 
1159
+ export interface CheckboxGroupOption {
1160
+ /** Submitted with the form and included in `value` when ticked. */
1161
+ value: string
1162
+ label: ReactNode
1163
+ /** Help text under this option. */
1164
+ description?: ReactNode
1165
+ disabled?: boolean
1166
+ }
1167
+
1051
1168
  export interface ComboboxOption {
1169
+ /** What `value` and `onValueChange` use. Unique within the options. */
1052
1170
  value: string
1171
+ /** The text shown in the list and, once picked, in the input. Typing filters on it. */
1053
1172
  label: string
1173
+ /** A muted line under the label in the list. Screen readers announce it as the option's description. Not filtered on. */
1174
+ description?: ReactNode
1175
+ /** Muted text at the end of the row, e.g. "32–50 wpm". Also part of the option's description. */
1176
+ detail?: ReactNode
1177
+ /** Shown but can't be picked. */
1054
1178
  disabled?: boolean
1055
1179
  }
1056
1180
 
1181
+ export interface DateRange {
1182
+ start: Date | null
1183
+ end: Date | null
1184
+ }
1185
+
1186
+ export interface FullDateRange {
1187
+ start: Date
1188
+ end: Date
1189
+ }
1190
+
1191
+ export interface DateRangePreset {
1192
+ label: string
1193
+ range: () => FullDateRange
1194
+ }
1195
+
1057
1196
  export interface DescriptionListItem {
1197
+ /** The label, e.g. "Customer". */
1058
1198
  term: ReactNode
1199
+ /** The value. */
1059
1200
  description: ReactNode
1060
1201
  /** Show the description in the mono font, e.g. for IDs and codes. */
1061
1202
  mono?: boolean
1203
+ /** Native tooltip on the value, e.g. the full text of a truncated value. */
1204
+ title?: string
1205
+ /** Extra class on the value (`<dd>`), e.g. to truncate it. */
1206
+ className?: string
1062
1207
  }
1063
1208
 
1064
- export type RequiredIndicator = 'asterisk' | 'optional-note' | 'none'
1209
+ export type DetailsSummaryTone = BadgeTone
1210
+
1211
+ export type EnvironmentTone = 'danger' | 'highlight' | 'info' | 'neutral'
1065
1212
 
1066
1213
  export type DataAttributes = { [key: `data-${string}`]: string | number | boolean | undefined }
1067
1214
 
@@ -1073,28 +1220,37 @@ export type IconSize = keyof typeof sizes | `${number}${'em' | 'rem'}` | 12 | 14
1073
1220
 
1074
1221
  export interface MenuItem {
1075
1222
  type?: 'item'
1223
+ /** The item's text. */
1076
1224
  label: ReactNode
1225
+ /** Called when the item is picked by click or Enter. The menu then closes. */
1077
1226
  onClick?: () => void
1078
1227
  /** A decorative icon shown before the label. */
1079
1228
  icon?: ReactNode
1080
1229
  /** Styled in the danger colour, e.g. Delete. */
1081
1230
  destructive?: boolean
1231
+ /** Shown but can't be picked. A disabled link renders without its `href`. */
1082
1232
  disabled?: boolean
1083
1233
  /** Renders a link. */
1084
1234
  href?: string
1085
1235
  /** Renders a link through your router's link component. */
1086
1236
  render?: ReactElement
1087
- /** Defaults to the item's index. */
1237
+ /** React key. Defaults to the item's index. */
1088
1238
  key?: string
1239
+ /** Props for the item's element. */
1089
1240
  itemProps?: MenuItemElementProps
1090
1241
  }
1091
1242
 
1092
1243
  export interface MenuSubmenu {
1093
1244
  type?: 'submenu'
1245
+ /** The text of the item that opens the submenu. */
1094
1246
  label: ReactNode
1247
+ /** A decorative icon shown before the label. */
1095
1248
  icon?: ReactNode
1249
+ /** The submenu's entries. */
1096
1250
  items: MenuEntry[]
1251
+ /** Shown but can't be opened. */
1097
1252
  disabled?: boolean
1253
+ /** React key. Defaults to the entry's index. */
1098
1254
  key?: string
1099
1255
  /** Props for the item that opens the submenu. */
1100
1256
  itemProps?: MenuItemElementProps
@@ -1106,31 +1262,44 @@ export interface MenuRadioGroup {
1106
1262
  type: 'radio'
1107
1263
  /** A visible label above the options. */
1108
1264
  label?: ReactNode
1265
+ /** The `value` of the checked option. */
1109
1266
  value: string
1267
+ /** Called with the picked option's `value`. The menu stays open. */
1110
1268
  onValueChange: (value: string) => void
1269
+ /** The choices. `itemProps` go on each option's element. */
1111
1270
  options: Array<{
1112
1271
  value: string
1113
1272
  label: ReactNode
1114
1273
  disabled?: boolean
1115
1274
  itemProps?: MenuItemElementProps
1116
1275
  }>
1276
+ /** React key. Defaults to the entry's index. */
1117
1277
  key?: string
1118
1278
  }
1119
1279
 
1120
1280
  export interface MenuCheckboxItem {
1121
1281
  type: 'checkbox'
1282
+ /** The setting's text. */
1122
1283
  label: ReactNode
1284
+ /** Whether the setting is on. */
1123
1285
  checked: boolean
1286
+ /** Called with the new state when toggled. The menu stays open. */
1124
1287
  onCheckedChange: (checked: boolean) => void
1288
+ /** A decorative icon shown before the label. */
1125
1289
  icon?: ReactNode
1290
+ /** Shown but can't be toggled. */
1126
1291
  disabled?: boolean
1292
+ /** React key. Defaults to the entry's index. */
1127
1293
  key?: string
1294
+ /** Props for the item's element. */
1128
1295
  itemProps?: MenuItemElementProps
1129
1296
  }
1130
1297
 
1131
1298
  export interface MenuGroupLabel {
1132
1299
  type: 'label'
1300
+ /** The heading text. Also names the group for screen readers. */
1133
1301
  label: ReactNode
1302
+ /** React key. Defaults to the entry's index. */
1134
1303
  key?: string
1135
1304
  }
1136
1305
 
@@ -1142,34 +1311,59 @@ export type MetricBarSegmentTone = 'success' | 'neutral' | 'danger' | 'highlight
1142
1311
  export interface MetricBarSegment {
1143
1312
  /** Percentage of the bar's width (0 to 100). */
1144
1313
  value: number
1314
+ /** Segment colour. */
1145
1315
  tone: MetricBarSegmentTone
1316
+ /** Names the segment in a legend under the bar, so its meaning isn't carried by colour alone. */
1317
+ label?: ReactNode
1146
1318
  }
1147
1319
 
1148
1320
  export interface NavRailItem {
1321
+ /** Shown beside the icon when expanded, and as the tooltip and accessible name when collapsed. */
1149
1322
  label: string
1150
1323
  /** Icon element, e.g. `<Settings size="1.43em" aria-hidden />` (em keeps it scaling with text). */
1151
1324
  icon: ReactNode
1325
+ /** Link target. Use `render` instead for a router link. */
1152
1326
  href?: string
1153
1327
  /** Router link element, e.g. `<Link to="/settings" />`. Takes precedence over `href`. */
1154
1328
  render?: ReactElement
1329
+ /** Marks the current section (`aria-current="page"`). */
1155
1330
  active?: boolean
1156
1331
  /** Props for the item's link, e.g. `{ 'data-testid': 'nav-settings' }`. */
1157
1332
  itemProps?: ComponentProps<'a'> & DataAttributes
1158
1333
  }
1159
1334
 
1335
+ export interface NavRailGroup {
1336
+ /** Group heading, e.g. "Results". Short: one or two words. */
1337
+ group: string
1338
+ items: NavRailItem[]
1339
+ }
1340
+
1160
1341
  export type PortalContainerTarget =
1161
1342
  HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
1162
1343
 
1163
1344
  export interface RadioCardOption {
1345
+ /** Submitted with the form and passed to `onValueChange`. */
1164
1346
  value: string
1347
+ /** The card's title, also the radio's accessible name. */
1165
1348
  label: ReactNode
1349
+ /** Smaller text under the title, also the radio's accessible description. */
1166
1350
  description?: ReactNode
1167
1351
  disabled?: boolean
1168
1352
  }
1169
1353
 
1170
1354
  export interface SelectOption {
1355
+ /**
1356
+ * What `value` and `onValueChange` use. Unique within the options. `''` works as a real choice
1357
+ * (e.g. "All sites"), but like a native `<select>` it doesn't satisfy `required`.
1358
+ */
1171
1359
  value: string
1360
+ /** The text shown in the list and, once picked, in the trigger. Typeahead matches it. */
1172
1361
  label: string
1362
+ /** A muted line under the label in the list. Screen readers announce it as the option's description. */
1363
+ description?: ReactNode
1364
+ /** Muted text at the end of the row, e.g. "32–50 wpm". Also part of the option's description. */
1365
+ detail?: ReactNode
1366
+ /** Shown but can't be picked. */
1173
1367
  disabled?: boolean
1174
1368
  }
1175
1369
 
@@ -1178,6 +1372,7 @@ export type Status = 'queued' | 'running' | 'paused' | 'completed' | 'failed' |
1178
1372
  export interface SwitcherItem {
1179
1373
  /** Unique ID, e.g. a customer ID or branch name. Also matched by the filter. */
1180
1374
  value: string
1375
+ /** The row's name, also shown in the trigger when it's the current item. Matched by the filter. */
1181
1376
  label: string
1182
1377
  /** Secondary text under the label, e.g. an ID. */
1183
1378
  description?: string
@@ -1187,6 +1382,7 @@ export interface SwitcherItem {
1187
1382
  badge?: ReactNode
1188
1383
  /** Extra words the filter matches. */
1189
1384
  keywords?: string[]
1385
+ /** Shown but can't be picked. */
1190
1386
  disabled?: boolean
1191
1387
  /** Render the row as a link, e.g. `render={<a href="/customer/o2" />}` or a router `<Link />`. */
1192
1388
  render?: ReactElement
@@ -1195,26 +1391,55 @@ export interface SwitcherItem {
1195
1391
  }
1196
1392
 
1197
1393
  export interface SwitcherFooter {
1394
+ /** The button's text, e.g. "View all customers". */
1198
1395
  label: ReactNode
1199
1396
  /** e.g. `<a href="/customers" />` or a router `<Link to="/customers" />`. */
1200
1397
  render?: ButtonProps['render']
1398
+ /** Called on click. The popup then closes. */
1201
1399
  onClick?: () => void
1202
1400
  }
1203
1401
 
1402
+ export type SortDirection = 'asc' | 'desc'
1403
+
1404
+ export interface SortState {
1405
+ key: string
1406
+ direction: SortDirection
1407
+ }
1408
+
1204
1409
  export interface TableColumn<Row> {
1410
+ /** Unique column ID. Also the row field shown when there's no `render`. */
1205
1411
  key: string
1412
+ /** Column header content. */
1206
1413
  header: ReactNode
1414
+ /** Text alignment. Use `right` for numbers. */
1207
1415
  align?: Align
1416
+ /** Column width, e.g. `1` to shrink an actions column to fit. */
1208
1417
  width?: CSSProperties['width']
1209
1418
  /** Defaults to `row[key]`. */
1210
1419
  render?: (row: Row) => ReactNode
1420
+ /**
1421
+ * Shown after the cell's content and outside the row's link or button, so it isn't part of its
1422
+ * accessible name, e.g. tags beside a name.
1423
+ */
1424
+ extra?: (row: Row) => ReactNode
1425
+ /** Makes the header a sort button (see `sort`). */
1426
+ sortable?: boolean
1427
+ /** Ascending order for client-side sorting. Without it, rows show in the order given (the server sorts). */
1428
+ compare?: (a: Row, b: Row) => number
1429
+ /** One line with an ellipsis. A string sets the max width, e.g. `'16rem'` (default `20rem`). */
1430
+ truncate?: boolean | string
1211
1431
  }
1212
1432
 
1213
- export interface TabItem {
1214
- value: string
1433
+ export interface TabItem<Value extends string = string> {
1434
+ /** Unique key, used by `value`/`defaultValue`/`onValueChange`. */
1435
+ value: Value
1436
+ /** Tab text. */
1215
1437
  label: ReactNode
1438
+ /** Shown muted after the label, e.g. the number of items in the panel. */
1216
1439
  count?: ReactNode
1440
+ /** The panel shown while this tab is active. */
1217
1441
  content: ReactNode
1442
+ /** Can't be selected. */
1218
1443
  disabled?: boolean
1219
1444
  /** Keeps this panel in the DOM (hidden) while another tab is active. Overrides the `Tabs` prop. */
1220
1445
  keepMounted?: boolean
@@ -1224,15 +1449,21 @@ export interface TabItem {
1224
1449
  panelProps?: PartProps<BaseTabs.Panel.Props>
1225
1450
  }
1226
1451
 
1452
+ export type TagTone = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'highlight'
1453
+
1227
1454
  export interface ThemeOption {
1455
+ /** The theme this option applies. */
1228
1456
  value: Theme
1457
+ /** Visible name under the preview. */
1229
1458
  label: string
1230
1459
  /** Palettes drawn in the preview. Two are drawn side by side (e.g. system = light + dark). */
1231
1460
  palettes: ('light' | 'dark' | 'sand')[]
1232
1461
  }
1233
1462
 
1234
1463
  export interface ToggleGroupOption {
1464
+ /** Submitted with the form and passed to `onValueChange`. */
1235
1465
  value: string
1466
+ /** The segment's text. */
1236
1467
  label: string
1237
1468
  disabled?: boolean
1238
1469
  }