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