@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.
- package/README.md +9 -6
- package/dist/browser/back-office-kit.js +6649 -5932
- package/dist/components/Alert/Alert.css.d.ts +1 -0
- package/dist/components/Alert/Alert.d.ts +12 -2
- package/dist/components/Alert/Alert.js +33 -29
- package/dist/components/Alert/Alert.js.map +1 -1
- package/dist/components/Alert/Alert.styles.js +2 -2
- package/dist/components/Alert/Alert.styles.js.map +1 -1
- package/dist/components/AppShell/AppShell.css.d.ts +2 -0
- package/dist/components/AppShell/AppShell.d.ts +3 -1
- package/dist/components/AppShell/AppShell.js +42 -26
- package/dist/components/AppShell/AppShell.js.map +1 -1
- package/dist/components/AppShell/AppShell.styles.js +3 -2
- package/dist/components/AppShell/AppShell.styles.js.map +1 -1
- package/dist/components/Avatar/Avatar.d.ts +1 -0
- package/dist/components/Avatar/Avatar.js.map +1 -1
- package/dist/components/Badge/Badge.css.d.ts +5 -0
- package/dist/components/Badge/Badge.d.ts +4 -1
- package/dist/components/Badge/Badge.js +6 -5
- package/dist/components/Badge/Badge.js.map +1 -1
- package/dist/components/Badge/Badge.styles.js +16 -15
- package/dist/components/Badge/Badge.styles.js.map +1 -1
- package/dist/components/Breadcrumbs/Breadcrumbs.css.d.ts +2 -0
- package/dist/components/Breadcrumbs/Breadcrumbs.d.ts +2 -0
- package/dist/components/Breadcrumbs/Breadcrumbs.js +27 -27
- package/dist/components/Breadcrumbs/Breadcrumbs.js.map +1 -1
- package/dist/components/Breadcrumbs/Breadcrumbs.styles.js +2 -2
- package/dist/components/Breadcrumbs/Breadcrumbs.styles.js.map +1 -1
- package/dist/components/Button/Button.css.d.ts +1 -1
- package/dist/components/Button/Button.d.ts +5 -4
- package/dist/components/Button/Button.js +21 -21
- package/dist/components/Button/Button.js.map +1 -1
- package/dist/components/Button/Button.styles.js.map +1 -1
- package/dist/components/Card/Card.css.d.ts +2 -0
- package/dist/components/Card/Card.d.ts +7 -1
- package/dist/components/Card/Card.js +33 -22
- package/dist/components/Card/Card.js.map +1 -1
- package/dist/components/Card/Card.styles.js +2 -2
- package/dist/components/Card/Card.styles.js.map +1 -1
- package/dist/components/ChatTranscript/ChatTranscript.d.ts +2 -2
- package/dist/components/ChatTranscript/ChatTranscript.js +74 -71
- package/dist/components/ChatTranscript/ChatTranscript.js.map +1 -1
- package/dist/components/Checkbox/Checkbox.d.ts +2 -1
- package/dist/components/Checkbox/Checkbox.js +30 -34
- package/dist/components/Checkbox/Checkbox.js.map +1 -1
- package/dist/components/Checkbox/Checkbox.styles.js.map +1 -1
- package/dist/components/CheckboxGroup/CheckboxGroup.css.d.ts +2 -0
- package/dist/components/CheckboxGroup/CheckboxGroup.d.ts +28 -0
- package/dist/components/CheckboxGroup/CheckboxGroup.js +66 -0
- package/dist/components/CheckboxGroup/CheckboxGroup.js.map +1 -0
- package/dist/components/CheckboxGroup/CheckboxGroup.styles.js +10 -0
- package/dist/components/CheckboxGroup/CheckboxGroup.styles.js.map +1 -0
- package/dist/components/CheckboxGroup/index.d.ts +2 -0
- package/dist/components/Chip/Chip.css.d.ts +2 -0
- package/dist/components/Chip/Chip.d.ts +15 -3
- package/dist/components/Chip/Chip.js +35 -16
- package/dist/components/Chip/Chip.js.map +1 -1
- package/dist/components/Chip/Chip.styles.js +2 -2
- package/dist/components/Chip/Chip.styles.js.map +1 -1
- package/dist/components/Chip/index.d.ts +1 -1
- package/dist/components/ColorPicker/ColorPicker.d.ts +3 -1
- package/dist/components/ColorPicker/ColorPicker.js +46 -47
- package/dist/components/ColorPicker/ColorPicker.js.map +1 -1
- package/dist/components/ColorPicker/ColorPicker.styles.js.map +1 -1
- package/dist/components/Combobox/Combobox.d.ts +28 -4
- package/dist/components/Combobox/Combobox.js +130 -109
- package/dist/components/Combobox/Combobox.js.map +1 -1
- package/dist/components/CopyButton/CopyButton.d.ts +11 -0
- package/dist/components/CopyButton/CopyButton.js +40 -0
- package/dist/components/CopyButton/CopyButton.js.map +1 -0
- package/dist/components/CopyButton/index.d.ts +2 -0
- package/dist/components/DateRangePicker/DateRangePicker.d.ts +10 -3
- package/dist/components/DateRangePicker/DateRangePicker.js +107 -110
- package/dist/components/DateRangePicker/DateRangePicker.js.map +1 -1
- package/dist/components/DateRangePicker/DateRangePicker.styles.js +2 -2
- package/dist/components/DateRangePicker/DateRangePicker.styles.js.map +1 -1
- package/dist/components/DateTimeInput/DateTimeInput.d.ts +1 -1
- package/dist/components/DateTimeInput/DateTimeInput.js +20 -28
- package/dist/components/DateTimeInput/DateTimeInput.js.map +1 -1
- package/dist/components/DateTimeInput/DateTimeInput.styles.js +1 -0
- package/dist/components/DescriptionList/DescriptionList.d.ts +8 -0
- package/dist/components/DescriptionList/DescriptionList.js +2 -1
- package/dist/components/DescriptionList/DescriptionList.js.map +1 -1
- package/dist/components/DetailsSummary/DetailsSummary.css.d.ts +1 -0
- package/dist/components/DetailsSummary/DetailsSummary.d.ts +5 -1
- package/dist/components/DetailsSummary/DetailsSummary.js +15 -15
- package/dist/components/DetailsSummary/DetailsSummary.js.map +1 -1
- package/dist/components/DetailsSummary/DetailsSummary.styles.js +10 -2
- package/dist/components/DetailsSummary/DetailsSummary.styles.js.map +1 -1
- package/dist/components/DetailsSummary/index.d.ts +1 -1
- package/dist/components/Drawer/Drawer.css.d.ts +3 -0
- package/dist/components/Drawer/Drawer.d.ts +24 -3
- package/dist/components/Drawer/Drawer.js +55 -46
- package/dist/components/Drawer/Drawer.js.map +1 -1
- package/dist/components/Drawer/Drawer.styles.js +7 -2
- package/dist/components/Drawer/Drawer.styles.js.map +1 -1
- package/dist/components/EmptyState/EmptyState.css.d.ts +16 -0
- package/dist/components/EmptyState/EmptyState.d.ts +15 -0
- package/dist/components/EmptyState/EmptyState.js +37 -0
- package/dist/components/EmptyState/EmptyState.js.map +1 -0
- package/dist/components/EmptyState/EmptyState.styles.js +15 -0
- package/dist/components/EmptyState/EmptyState.styles.js.map +1 -0
- package/dist/components/EmptyState/index.d.ts +2 -0
- package/dist/components/EnvironmentChip/EnvironmentChip.css.d.ts +5 -0
- package/dist/components/EnvironmentChip/EnvironmentChip.d.ts +13 -5
- package/dist/components/EnvironmentChip/EnvironmentChip.js +14 -3
- package/dist/components/EnvironmentChip/EnvironmentChip.js.map +1 -1
- package/dist/components/EnvironmentChip/EnvironmentChip.styles.js +3 -2
- package/dist/components/EnvironmentChip/EnvironmentChip.styles.js.map +1 -1
- package/dist/components/EnvironmentChip/index.d.ts +2 -2
- package/dist/components/Field/Field.css.d.ts +0 -1
- package/dist/components/Field/Field.d.ts +11 -28
- package/dist/components/Field/Field.js +25 -36
- package/dist/components/Field/Field.js.map +1 -1
- package/dist/components/Field/Field.styles.js +2 -2
- package/dist/components/Field/Field.styles.js.map +1 -1
- package/dist/components/Field/index.d.ts +1 -1
- package/dist/components/Fieldset/Fieldset.d.ts +1 -0
- package/dist/components/Fieldset/Fieldset.js.map +1 -1
- package/dist/components/Fieldset/Fieldset.styles.js.map +1 -1
- package/dist/components/Grid/Grid.css.d.ts +22 -0
- package/dist/components/Grid/Grid.d.ts +21 -0
- package/dist/components/Grid/Grid.js +23 -0
- package/dist/components/Grid/Grid.js.map +1 -0
- package/dist/components/Grid/Grid.styles.js +28 -0
- package/dist/components/Grid/Grid.styles.js.map +1 -0
- package/dist/components/Grid/index.d.ts +2 -0
- package/dist/components/List/List.d.ts +1 -0
- package/dist/components/List/List.js.map +1 -1
- package/dist/components/Loader/Loader.d.ts +1 -1
- package/dist/components/Loader/Loader.js +6 -2
- package/dist/components/Loader/Loader.js.map +1 -1
- package/dist/components/Menu/Menu.d.ts +25 -1
- package/dist/components/Menu/Menu.js +1 -1
- package/dist/components/Menu/Menu.js.map +1 -1
- package/dist/components/Menu/Menu.styles.js.map +1 -1
- package/dist/components/MetricBar/MetricBar.css.d.ts +5 -0
- package/dist/components/MetricBar/MetricBar.d.ts +9 -1
- package/dist/components/MetricBar/MetricBar.js +38 -22
- package/dist/components/MetricBar/MetricBar.js.map +1 -1
- package/dist/components/MetricBar/MetricBar.styles.js +15 -10
- package/dist/components/MetricBar/MetricBar.styles.js.map +1 -1
- package/dist/components/Modal/Modal.d.ts +6 -0
- package/dist/components/Modal/Modal.js +25 -28
- package/dist/components/Modal/Modal.js.map +1 -1
- package/dist/components/Modal/Modal.styles.js +2 -1
- package/dist/components/Modal/Modal.styles.js.map +1 -1
- package/dist/components/NavRail/NavRail.css.d.ts +2 -0
- package/dist/components/NavRail/NavRail.d.ts +22 -7
- package/dist/components/NavRail/NavRail.js +79 -58
- package/dist/components/NavRail/NavRail.js.map +1 -1
- package/dist/components/NavRail/NavRail.styles.js +3 -2
- package/dist/components/NavRail/NavRail.styles.js.map +1 -1
- package/dist/components/NavRail/index.d.ts +1 -1
- package/dist/components/NumberInput/NumberInput.d.ts +9 -1
- package/dist/components/NumberInput/NumberInput.js +37 -31
- package/dist/components/NumberInput/NumberInput.js.map +1 -1
- package/dist/components/PageHeader/PageHeader.css.d.ts +1 -1
- package/dist/components/PageHeader/PageHeader.d.ts +3 -1
- package/dist/components/PageHeader/PageHeader.js +21 -23
- package/dist/components/PageHeader/PageHeader.js.map +1 -1
- package/dist/components/PageHeader/PageHeader.styles.js +1 -1
- package/dist/components/PageHeader/PageHeader.styles.js.map +1 -1
- package/dist/components/Pagination/Pagination.d.ts +5 -0
- package/dist/components/Pagination/Pagination.js.map +1 -1
- package/dist/components/Popover/Popover.d.ts +9 -1
- package/dist/components/Popover/Popover.js +7 -6
- package/dist/components/Popover/Popover.js.map +1 -1
- package/dist/components/Popover/Popover.styles.js.map +1 -1
- package/dist/components/PortalContainer/PortalContainer.d.ts +1 -0
- package/dist/components/PortalContainer/PortalContainer.js.map +1 -1
- package/dist/components/ProgressBar/ProgressBar.css.d.ts +3 -0
- package/dist/components/ProgressBar/ProgressBar.d.ts +5 -1
- package/dist/components/ProgressBar/ProgressBar.js +21 -7
- package/dist/components/ProgressBar/ProgressBar.js.map +1 -1
- package/dist/components/ProgressBar/ProgressBar.styles.js +6 -6
- package/dist/components/ProgressBar/ProgressBar.styles.js.map +1 -1
- package/dist/components/RadioCards/RadioCards.d.ts +8 -2
- package/dist/components/RadioCards/RadioCards.js +40 -44
- package/dist/components/RadioCards/RadioCards.js.map +1 -1
- package/dist/components/SaveBar/SaveBar.d.ts +6 -1
- package/dist/components/SaveBar/SaveBar.js +1 -2
- package/dist/components/SaveBar/SaveBar.js.map +1 -1
- package/dist/components/SaveBar/SaveBar.styles.js.map +1 -1
- package/dist/components/Select/Select.css.d.ts +2 -0
- package/dist/components/Select/Select.d.ts +32 -5
- package/dist/components/Select/Select.js +91 -62
- package/dist/components/Select/Select.js.map +1 -1
- package/dist/components/Select/Select.styles.js +3 -2
- package/dist/components/Select/Select.styles.js.map +1 -1
- package/dist/components/Skeleton/Skeleton.d.ts +2 -0
- package/dist/components/Skeleton/Skeleton.js +20 -19
- package/dist/components/Skeleton/Skeleton.js.map +1 -1
- package/dist/components/Stack/Stack.css.d.ts +4 -1
- package/dist/components/Stack/Stack.d.ts +7 -3
- package/dist/components/Stack/Stack.js.map +1 -1
- package/dist/components/Stack/Stack.styles.js +16 -23
- package/dist/components/Stack/Stack.styles.js.map +1 -1
- package/dist/components/StatCard/StatCard.d.ts +3 -0
- package/dist/components/StatCard/StatCard.js.map +1 -1
- package/dist/components/StatCard/StatCard.styles.js.map +1 -1
- package/dist/components/StatsGrid/StatsGrid.d.ts +3 -6
- package/dist/components/StatsGrid/StatsGrid.js +3 -7
- package/dist/components/StatsGrid/StatsGrid.js.map +1 -1
- package/dist/components/StatusBadge/StatusBadge.d.ts +3 -2
- package/dist/components/StatusBadge/StatusBadge.js.map +1 -1
- package/dist/components/Switch/Switch.d.ts +2 -1
- package/dist/components/Switch/Switch.js +27 -31
- package/dist/components/Switch/Switch.js.map +1 -1
- package/dist/components/Switcher/Switcher.css.d.ts +0 -1
- package/dist/components/Switcher/Switcher.d.ts +13 -1
- package/dist/components/Switcher/Switcher.js +35 -35
- package/dist/components/Switcher/Switcher.js.map +1 -1
- package/dist/components/Switcher/Switcher.styles.js +2 -2
- package/dist/components/Switcher/Switcher.styles.js.map +1 -1
- package/dist/components/Table/Table.css.d.ts +16 -1
- package/dist/components/Table/Table.d.ts +110 -13
- package/dist/components/Table/Table.js +214 -102
- package/dist/components/Table/Table.js.map +1 -1
- package/dist/components/Table/Table.styles.js +7 -6
- package/dist/components/Table/Table.styles.js.map +1 -1
- package/dist/components/Table/index.d.ts +1 -1
- package/dist/components/Tabs/Tabs.d.ts +23 -8
- package/dist/components/Tabs/Tabs.js +1 -1
- package/dist/components/Tabs/Tabs.js.map +1 -1
- package/dist/components/Tabs/Tabs.styles.js.map +1 -1
- package/dist/components/Tabs/index.d.ts +1 -1
- package/dist/components/Tag/Tag.css.d.ts +33 -0
- package/dist/components/Tag/Tag.d.ts +5 -2
- package/dist/components/Tag/Tag.js +23 -6
- package/dist/components/Tag/Tag.js.map +1 -1
- package/dist/components/Tag/Tag.styles.js +12 -1
- package/dist/components/Tag/Tag.styles.js.map +1 -1
- package/dist/components/Tag/index.d.ts +1 -1
- package/dist/components/TextInput/TextInput.d.ts +13 -2
- package/dist/components/TextInput/TextInput.js +45 -48
- package/dist/components/TextInput/TextInput.js.map +1 -1
- package/dist/components/Textarea/Textarea.css.d.ts +2 -0
- package/dist/components/Textarea/Textarea.d.ts +5 -2
- package/dist/components/Textarea/Textarea.js +37 -37
- package/dist/components/Textarea/Textarea.js.map +1 -1
- package/dist/components/Textarea/Textarea.styles.js +3 -2
- package/dist/components/Textarea/Textarea.styles.js.map +1 -1
- package/dist/components/ThemeMenu/ThemeMenu.d.ts +13 -0
- package/dist/components/ThemeMenu/ThemeMenu.js +52 -0
- package/dist/components/ThemeMenu/ThemeMenu.js.map +1 -0
- package/dist/components/ThemeMenu/index.d.ts +2 -0
- package/dist/components/ThemePicker/ThemePicker.d.ts +9 -1
- package/dist/components/ThemePicker/ThemePicker.js +3 -1
- package/dist/components/ThemePicker/ThemePicker.js.map +1 -1
- package/dist/components/TimeInput/TimeInput.d.ts +10 -0
- package/dist/components/TimeInput/TimeInput.js +29 -0
- package/dist/components/TimeInput/TimeInput.js.map +1 -0
- package/dist/components/TimeInput/index.d.ts +2 -0
- package/dist/components/ToggleGroup/ToggleGroup.d.ts +30 -10
- package/dist/components/ToggleGroup/ToggleGroup.js +60 -59
- package/dist/components/ToggleGroup/ToggleGroup.js.map +1 -1
- package/dist/components/ToggleGroup/ToggleGroup.styles.js.map +1 -1
- package/dist/components/ToggleGroup/index.d.ts +1 -1
- package/dist/components/Tooltip/Tooltip.css.d.ts +0 -1
- package/dist/components/Tooltip/Tooltip.d.ts +9 -5
- package/dist/components/Tooltip/Tooltip.js +9 -9
- package/dist/components/Tooltip/Tooltip.js.map +1 -1
- package/dist/components/Tooltip/Tooltip.styles.js +2 -2
- package/dist/components/Tooltip/Tooltip.styles.js.map +1 -1
- package/dist/components/TopBar/TopBar.styles.js.map +1 -1
- package/dist/components/UserMenu/UserMenu.d.ts +4 -3
- package/dist/components/UserMenu/UserMenu.js.map +1 -1
- package/dist/examples/Crm.css.d.ts +3 -0
- package/dist/examples/ExampleShell.d.ts +28 -0
- package/dist/examples/Expenses.css.d.ts +2 -0
- package/dist/examples/HiringTracker.css.d.ts +13 -0
- package/dist/examples/SalesPipeline.css.d.ts +11 -0
- package/dist/foundations/Foundations.css.d.ts +1 -1
- package/dist/index.d.ts +6 -0
- package/dist/index.js +51 -45
- package/dist/styles/input.css.d.ts +8 -0
- package/dist/styles/input.styles.js +3 -2
- package/dist/styles/input.styles.js.map +1 -1
- package/dist/styles/shared.css.d.ts +5 -0
- package/dist/styles/shared.styles.js.map +1 -1
- package/dist/styles.css +1 -1
- package/dist/theme/fontSize.d.ts +4 -4
- package/dist/theme/fontSize.js +8 -23
- package/dist/theme/fontSize.js.map +1 -1
- package/dist/theme/htmlSetting.d.ts +14 -0
- package/dist/theme/htmlSetting.js +33 -0
- package/dist/theme/htmlSetting.js.map +1 -0
- package/dist/theme/theme.d.ts +4 -4
- package/dist/theme/theme.js +18 -33
- package/dist/theme/theme.js.map +1 -1
- package/dist/tokens/index.d.ts +0 -2
- package/dist/tokens.js +1 -2
- package/package.json +8 -3
- package/skills/back-office-kit/SKILL.md +27 -14
- package/skills/back-office-kit/references/artifact-template.html +1 -0
- package/skills/back-office-kit/references/components.md +482 -251
- package/skills/back-office-kit/references/install.md +27 -4
- package/skills/back-office-kit/references/migrate.md +58 -2
- package/skills/back-office-kit/references/patterns.md +129 -33
- package/skills/back-office-kit/references/testing.md +26 -22
- package/dist/tokens/sprinkles.css.d.ts +0 -38
- package/dist/tokens/sprinkles.styles.js +0 -349
- 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
|
-
| `
|
|
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`
|
|
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
|
-
| `
|
|
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` | |
|
|
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
|
-
| `
|
|
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.
|
|
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
|
-
| `
|
|
115
|
-
| `
|
|
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
|
-
| `
|
|
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` | |
|
|
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` | |
|
|
207
|
-
| `
|
|
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
|
-
| `
|
|
242
|
-
| `
|
|
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` | |
|
|
248
|
-
| `
|
|
249
|
-
|
|
250
|
-
|
|
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` | |
|
|
282
|
-
| `
|
|
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` | |
|
|
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
|
|
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
|
-
| `
|
|
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
|
|
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. "
|
|
366
|
-
|
|
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` | |
|
|
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` |
|
|
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
|
-
| `
|
|
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
|
|
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
|
-
| `
|
|
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` | |
|
|
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
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
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` | |
|
|
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
|
-
| `
|
|
670
|
-
| `
|
|
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
|
-
| `
|
|
676
|
-
| `
|
|
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" \| "
|
|
700
|
-
| `direction` | `"row" \| "column"` | `column` |
|
|
701
|
-
| `gap` | `"
|
|
702
|
-
| `justify` | `"center" \| "
|
|
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
|
|
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` | |
|
|
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
|
-
| `
|
|
792
|
-
| `
|
|
793
|
-
| `
|
|
794
|
-
| `
|
|
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
|
-
| `
|
|
799
|
-
| `
|
|
800
|
-
| `
|
|
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
|
-
| `
|
|
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` | `
|
|
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:
|
|
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` | `
|
|
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` | |
|
|
861
|
-
| `
|
|
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` | |
|
|
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
|
|
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.
|
|
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` | `
|
|
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
|
-
| `
|
|
917
|
-
| `
|
|
918
|
-
| `
|
|
919
|
-
| `options` * | `ToggleGroupOption[]` | |
|
|
920
|
-
| `ref` | `Ref<HTMLInputElement>` | | Forwarded to the hidden input. |
|
|
921
|
-
| `
|
|
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:
|
|
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
|
-
| `
|
|
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> &
|
|
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()
|
|
993
|
-
- `setFontSize(size: FontSize, { persist
|
|
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()
|
|
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
|
|
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
|
|
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
|
|
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
|
}
|