@peerproblem/sw3-ui 0.0.0-stage → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +109 -2
- package/agent/components/accordion.md +95 -0
- package/agent/components/action-square.md +106 -0
- package/agent/components/agent-bridge.md +87 -0
- package/agent/components/agent-console.md +123 -0
- package/agent/components/alert-dialog.md +82 -0
- package/agent/components/app-shell.md +105 -0
- package/agent/components/area-chart.md +56 -0
- package/agent/components/async-options.md +47 -0
- package/agent/components/autocomplete.md +69 -0
- package/agent/components/avatar.md +88 -0
- package/agent/components/badge.md +51 -0
- package/agent/components/bar-chart.md +56 -0
- package/agent/components/bar-list.md +49 -0
- package/agent/components/breadcrumbs.md +43 -0
- package/agent/components/button.md +109 -0
- package/agent/components/calendar.md +114 -0
- package/agent/components/canvas.md +105 -0
- package/agent/components/card.md +78 -0
- package/agent/components/carousel.md +113 -0
- package/agent/components/chart-card.md +41 -0
- package/agent/components/chart-surface.md +56 -0
- package/agent/components/checkbox.md +88 -0
- package/agent/components/citation-chip.md +61 -0
- package/agent/components/collapsible.md +69 -0
- package/agent/components/color-picker.md +82 -0
- package/agent/components/combobox.md +104 -0
- package/agent/components/command.md +92 -0
- package/agent/components/dashboard-grid.md +73 -0
- package/agent/components/date-input.md +87 -0
- package/agent/components/date-picker.md +122 -0
- package/agent/components/dialog.md +97 -0
- package/agent/components/donut-chart.md +50 -0
- package/agent/components/drawer.md +101 -0
- package/agent/components/empty-state.md +52 -0
- package/agent/components/field.md +80 -0
- package/agent/components/file-input.md +84 -0
- package/agent/components/hover-card.md +64 -0
- package/agent/components/image-cropper.md +77 -0
- package/agent/components/input.md +49 -0
- package/agent/components/label.md +53 -0
- package/agent/components/line-chart.md +60 -0
- package/agent/components/listbox.md +84 -0
- package/agent/components/map-view.md +104 -0
- package/agent/components/menu.md +117 -0
- package/agent/components/menubar.md +67 -0
- package/agent/components/meter.md +59 -0
- package/agent/components/navigation-menu.md +98 -0
- package/agent/components/number-input.md +81 -0
- package/agent/components/otp-input.md +67 -0
- package/agent/components/pagination.md +80 -0
- package/agent/components/password-input.md +67 -0
- package/agent/components/pill-button.md +116 -0
- package/agent/components/popover.md +85 -0
- package/agent/components/poster-card.md +61 -0
- package/agent/components/preferences.md +92 -0
- package/agent/components/progress.md +63 -0
- package/agent/components/provider.md +47 -0
- package/agent/components/radio.md +91 -0
- package/agent/components/rating.md +66 -0
- package/agent/components/reorder.md +61 -0
- package/agent/components/resizable.md +87 -0
- package/agent/components/scatter-chart.md +49 -0
- package/agent/components/scroll-area.md +81 -0
- package/agent/components/segmented-control.md +56 -0
- package/agent/components/select.md +130 -0
- package/agent/components/separator.md +60 -0
- package/agent/components/shortcuts.md +50 -0
- package/agent/components/sidebar-nav.md +68 -0
- package/agent/components/skeleton.md +58 -0
- package/agent/components/slider.md +79 -0
- package/agent/components/sparkline.md +39 -0
- package/agent/components/squircle.md +58 -0
- package/agent/components/stat.md +58 -0
- package/agent/components/switch.md +48 -0
- package/agent/components/table.md +58 -0
- package/agent/components/tabs.md +108 -0
- package/agent/components/textarea.md +68 -0
- package/agent/components/time-input.md +84 -0
- package/agent/components/timeline.md +91 -0
- package/agent/components/toast.md +85 -0
- package/agent/components/toggle.md +76 -0
- package/agent/components/token-input.md +66 -0
- package/agent/components/toolbar.md +76 -0
- package/agent/components/tooltip.md +83 -0
- package/agent/components/tracker.md +47 -0
- package/agent/components/tree.md +87 -0
- package/agent/components/treemap.md +72 -0
- package/agent/components/trend-chart.md +80 -0
- package/agent/components/trigger-menu.md +67 -0
- package/agent/components/typography.md +51 -0
- package/agent/components/waterfall.md +78 -0
- package/agent/components/week-schedule.md +113 -0
- package/agent/llms/actions-and-layout.txt +1749 -0
- package/agent/llms/agents.txt +505 -0
- package/agent/llms/charts.txt +778 -0
- package/agent/llms/dashboards.txt +457 -0
- package/agent/llms/extend.txt +132 -0
- package/agent/llms/extras.txt +527 -0
- package/agent/llms/forms.txt +2152 -0
- package/agent/llms/foundations.txt +674 -0
- package/agent/llms/hooks.txt +178 -0
- package/agent/llms/maps.txt +229 -0
- package/agent/llms/overlays-and-navigation.txt +1167 -0
- package/agent/llms-full.txt +8717 -0
- package/agent/llms.txt +145 -0
- package/agent/registry.json +11289 -0
- package/agent/tokens.md +66 -0
- package/dist/agent/index.d.ts +235 -0
- package/dist/agent/index.js +21 -0
- package/dist/card-Ipm-Cj5f.d.ts +490 -0
- package/dist/charts/index.d.ts +289 -0
- package/dist/charts/index.js +815 -0
- package/dist/check/cli.d.ts +1 -0
- package/dist/check/cli.js +48 -0
- package/dist/check/rendered.d.ts +11 -0
- package/dist/check/rendered.js +77 -0
- package/dist/check/source.d.ts +13 -0
- package/dist/check/source.js +182 -0
- package/dist/chunk-3DXBM65D.js +65 -0
- package/dist/chunk-3H5X4ZP6.js +55 -0
- package/dist/chunk-6XC4BC5C.js +92 -0
- package/dist/chunk-7H6TEAWD.js +507 -0
- package/dist/chunk-I63ZTJOI.js +1089 -0
- package/dist/chunk-JCIRUM4W.js +33 -0
- package/dist/chunk-LTBEHZ3P.js +25 -0
- package/dist/chunk-QDPPLO4U.js +60 -0
- package/dist/chunk-U2XFBPU4.js +56 -0
- package/dist/chunk-UY2WH5AY.js +681 -0
- package/dist/extras.d.ts +203 -0
- package/dist/extras.js +904 -0
- package/dist/icons-BJiGEAnU.d.ts +68 -0
- package/dist/index.d.ts +3737 -0
- package/dist/index.js +14477 -0
- package/dist/map/index.d.ts +115 -0
- package/dist/map/index.js +394 -0
- package/dist/meta/index.d.ts +3314 -0
- package/dist/meta/index.js +5106 -0
- package/dist/rules-1RIZ_JZr.d.ts +38 -0
- package/dist/styles.css +4037 -0
- package/dist/themes/calm.css +42 -0
- package/dist/themes/frost.css +40 -0
- package/package.json +142 -4
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Checkbox / CheckboxGroup
|
|
2
|
+
|
|
3
|
+
> A squircle box with an animated check: checked, unchecked or indeterminate. CheckboxGroup shares one array value and supports a select-all parent.
|
|
4
|
+
|
|
5
|
+
Category: inputs · Status: beta · Slug: `checkbox`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Checkbox, CheckboxGroup } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Independent yes/no options in a form that is submitted later.
|
|
13
|
+
- Picking several items from a short list (CheckboxGroup).
|
|
14
|
+
- Accepting terms.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Settings that apply immediately — use Switch.
|
|
18
|
+
- Choosing exactly one option — use RadioGroup or SegmentedControl.
|
|
19
|
+
- Long lists (>8) — use a multi-select Combobox/Listbox.
|
|
20
|
+
|
|
21
|
+
## Props
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `checked` | `boolean \| 'indeterminate'` | | Controlled state. |
|
|
26
|
+
| `defaultChecked` | `boolean \| 'indeterminate'` | `false` | Initial state when uncontrolled. |
|
|
27
|
+
| `onCheckedChange` | `(checked: boolean) => void` | | Called on press. From indeterminate, a press checks. |
|
|
28
|
+
| `label` | `ReactNode` | | Clickable text next to the box (children works too). |
|
|
29
|
+
| `description` | `ReactNode` | | Muted line under the label. |
|
|
30
|
+
| `value` | `string` | `'on'` | Submitted while checked; identifies it inside a group. |
|
|
31
|
+
| `name` | `string` | | Form field name. |
|
|
32
|
+
| `parent` | `boolean` | | Inside a group: select-all checkbox, indeterminate when some are checked. |
|
|
33
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. |
|
|
34
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Box 16 / 18 / 22px. |
|
|
35
|
+
| `CheckboxGroup.value` | `string[]` | | Values of checked boxes (controlled). |
|
|
36
|
+
| `CheckboxGroup.defaultValue` | `string[]` | `[]` | Initial values. |
|
|
37
|
+
| `CheckboxGroup.onValueChange` | `(value: string[]) => void` | | Called when any box changes. |
|
|
38
|
+
| `CheckboxGroup.items` | `{ value, label, description?, disabled? }[]` | | Shorthand: one Checkbox per item. |
|
|
39
|
+
| `CheckboxGroup.allValues` | `string[]` | | Values a parent checkbox controls (default: the boxes in the group). |
|
|
40
|
+
| `CheckboxGroup.name / disabled / readOnly / orientation` | `string / boolean / boolean / 'vertical' \| 'horizontal'` | | Shared settings. |
|
|
41
|
+
|
|
42
|
+
## Examples
|
|
43
|
+
|
|
44
|
+
### Single
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
<Checkbox label="Email me when the run finishes" defaultChecked />
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Group with select-all
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
const [tools, setTools] = useState(['search'])
|
|
54
|
+
|
|
55
|
+
<CheckboxGroup aria-label="Tools" value={tools} onValueChange={setTools}>
|
|
56
|
+
<Checkbox parent label="All tools" />
|
|
57
|
+
<Checkbox value="search" label="Web search" />
|
|
58
|
+
<Checkbox value="code" label="Code interpreter" />
|
|
59
|
+
<Checkbox value="files" label="File access" />
|
|
60
|
+
</CheckboxGroup>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Items shorthand
|
|
64
|
+
|
|
65
|
+
```tsx
|
|
66
|
+
<CheckboxGroup aria-label="Notify" name="notify" defaultValue={['email']} items={[
|
|
67
|
+
{ value: 'email', label: 'Email' },
|
|
68
|
+
{ value: 'slack', label: 'Slack' },
|
|
69
|
+
]} />
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Rules
|
|
73
|
+
- Labels are positive statements ("Send a summary", not "Don't skip the summary").
|
|
74
|
+
- Use the accent only through the checked state; never recolor the box.
|
|
75
|
+
|
|
76
|
+
## Accessibility
|
|
77
|
+
- role="checkbox" with aria-checked true / false / mixed. Space toggles; Enter does not.
|
|
78
|
+
- Group is role="group"; name it with aria-label or a Field label.
|
|
79
|
+
|
|
80
|
+
## DOM contract (for agents operating the page)
|
|
81
|
+
|
|
82
|
+
- Selector: `[data-sw="checkbox"]`
|
|
83
|
+
- `aria-checked`: true | false | mixed
|
|
84
|
+
- `data-state`: checked | unchecked | indeterminate
|
|
85
|
+
- `disabled`: native disabled
|
|
86
|
+
- How to operate: Click [data-sw="checkbox"] (or its label). Agent bridge (checkbox): toggle(), setChecked(bool). Group [data-sw="checkbox-group"]: setValue(values[]), add(value), remove(value), clear(); items = options.
|
|
87
|
+
|
|
88
|
+
Related: `switch`, `radio`, `field`
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# CitationChip
|
|
2
|
+
|
|
3
|
+
> An inline source reference that opens citation details and a link to the original source.
|
|
4
|
+
|
|
5
|
+
Category: agents · Status: beta · Slug: `citation-chip`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { CitationChip } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Citing a source next to a statement, metric, or table.
|
|
13
|
+
|
|
14
|
+
## Avoid
|
|
15
|
+
- General navigation links or status labels.
|
|
16
|
+
|
|
17
|
+
## Props
|
|
18
|
+
|
|
19
|
+
| Prop | Type | Default | Description |
|
|
20
|
+
| --- | --- | --- | --- |
|
|
21
|
+
| `reference` * | `string` | | Short visible source ID, such as S1. |
|
|
22
|
+
| `title` * | `string` | | Source title shown in the citation details. |
|
|
23
|
+
| `href` * | `string` | | Absolute HTTP or HTTPS URL. An invalid or empty URL omits the chip. |
|
|
24
|
+
| `publisher` | `string` | | Publisher or organization that issued the source. |
|
|
25
|
+
| `excerpt` | `string` | | Short plain-text passage from the source. |
|
|
26
|
+
| `open` | `boolean` | | Controlled open state of the citation preview. |
|
|
27
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
28
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
29
|
+
|
|
30
|
+
## Examples
|
|
31
|
+
|
|
32
|
+
### Inline source reference
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
<p>
|
|
36
|
+
The city closed one lane.{' '}
|
|
37
|
+
<CitationChip
|
|
38
|
+
reference="S1"
|
|
39
|
+
title="Road closure advisory"
|
|
40
|
+
href="https://example.com/road-closure"
|
|
41
|
+
publisher="City transportation department"
|
|
42
|
+
excerpt="The eastbound lane is closed until 18:00."
|
|
43
|
+
/>
|
|
44
|
+
</p>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Rules
|
|
48
|
+
- Use an identifiable source title and a short, distinct reference. The Open source link opens the original URL in a new tab.
|
|
49
|
+
|
|
50
|
+
## Accessibility
|
|
51
|
+
- The leading note icon is decorative. Enter or Space opens the non-modal preview and moves focus to Open source.
|
|
52
|
+
- Escape closes the preview and returns focus to the chip. Tab can leave the preview.
|
|
53
|
+
|
|
54
|
+
## DOM contract (for agents operating the page)
|
|
55
|
+
|
|
56
|
+
- Selector: `[data-sw="citation-chip"]`
|
|
57
|
+
- `aria-expanded`: on the nested [data-sw="popover-trigger"]
|
|
58
|
+
- `data-state`: open | closed on the nested popover trigger and panel
|
|
59
|
+
- How to operate: Open or close the preview through its existing popover agent binding. The external URL is available on [data-sw="citation-chip-link"] in the open panel.
|
|
60
|
+
|
|
61
|
+
Related: `popover`
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Collapsible
|
|
2
|
+
|
|
3
|
+
> One trigger that shows and hides one panel, with an animated height.
|
|
4
|
+
|
|
5
|
+
Category: layout · Status: beta · Slug: `collapsible`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Collapsible, CollapsibleTrigger, CollapsiblePanel } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- "Show more" / "Advanced options" sections.
|
|
13
|
+
- Revealing details (logs, raw JSON) under a summary line.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- A list of several sections — use Accordion.
|
|
17
|
+
- Floating content over the page — use Popover.
|
|
18
|
+
- Hiding the only way to do a primary task.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `open` | `boolean` | | Controlled open state. |
|
|
25
|
+
| `defaultOpen` | `boolean` | `false` | Open at first, when uncontrolled. |
|
|
26
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when the trigger toggles. |
|
|
27
|
+
| `disabled` | `boolean` | `false` | Disable the trigger. |
|
|
28
|
+
| `keepMounted` | `boolean` | `false` | Keep the panel's contents mounted (hidden) while closed, so their state survives. |
|
|
29
|
+
| `CollapsibleTrigger.indicator` | `boolean` | `true` | Show the rotating chevron. |
|
|
30
|
+
| `CollapsiblePanel.keepMounted` | `boolean` | | Override keepMounted for the panel. |
|
|
31
|
+
|
|
32
|
+
## Examples
|
|
33
|
+
|
|
34
|
+
### Advanced options
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
<Collapsible>
|
|
38
|
+
<CollapsibleTrigger>Advanced options</CollapsibleTrigger>
|
|
39
|
+
<CollapsiblePanel>
|
|
40
|
+
<Input label="Max tokens" defaultValue="4096" />
|
|
41
|
+
</CollapsiblePanel>
|
|
42
|
+
</Collapsible>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Controlled, contents kept
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
const [open, setOpen] = useState(false)
|
|
49
|
+
|
|
50
|
+
<Collapsible open={open} onOpenChange={setOpen} keepMounted>
|
|
51
|
+
<CollapsibleTrigger>{open ? 'Hide' : 'Show'} raw response</CollapsibleTrigger>
|
|
52
|
+
<CollapsiblePanel><pre>{json}</pre></CollapsiblePanel>
|
|
53
|
+
</Collapsible>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Rules
|
|
57
|
+
- The trigger label says what is hidden ("Advanced options", "Show 12 more").
|
|
58
|
+
|
|
59
|
+
## Accessibility
|
|
60
|
+
- The trigger is a <button aria-expanded aria-controls>; Enter/Space toggles.
|
|
61
|
+
|
|
62
|
+
## DOM contract (for agents operating the page)
|
|
63
|
+
|
|
64
|
+
- Selector: `[data-sw="collapsible"]`
|
|
65
|
+
- `data-state`: open | closed (root, trigger and panel)
|
|
66
|
+
- `aria-expanded`: on [data-sw="collapsible-trigger"]
|
|
67
|
+
- How to operate: Click [data-sw="collapsible-trigger"]. Agent bridge: open(), close(), toggle(); state = { open, disabled }.
|
|
68
|
+
|
|
69
|
+
Related: `accordion`
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# ColorPicker
|
|
2
|
+
|
|
3
|
+
> Pick a color with a saturation/brightness area, hue and alpha sliders, a text field that accepts any CSS color, and preset swatches. The value is a CSS color string.
|
|
4
|
+
|
|
5
|
+
Category: inputs · Status: beta · Slug: `color-picker`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { ColorPicker, ColorPickerPopover } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Choosing a brand, label, chart or theme color.
|
|
13
|
+
- Inline in a settings panel (`ColorPicker`) or behind a swatch button in a form (`ColorPickerPopover`).
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- `<input type="color">` — it has no alpha, no presets and looks different per browser.
|
|
17
|
+
- A picker for a handful of fixed choices only. Use a RadioGroup or SegmentedControl of swatches, or pass `presets` with `showInput={false}`.
|
|
18
|
+
- Storing `oklch()`/named values and expecting SSR to parse them: during server rendering only hex, rgb() and hsl() parse.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `value` | `string` | | The color as any CSS color string. Controlled. |
|
|
25
|
+
| `defaultValue` | `string` | `'#000000'` | Initial color when uncontrolled. |
|
|
26
|
+
| `onValueChange` | `(value: string) => void` | | Every step of a drag, key, swatch or text commit, written in `format`. |
|
|
27
|
+
| `onValueCommit` | `(value: string) => void` | | Once an interaction ends (pointer up, key, swatch, text). Save here. |
|
|
28
|
+
| `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | How the value is written. hex becomes #rrggbbaa when translucent. |
|
|
29
|
+
| `alpha` | `boolean` | `true` | Show the alpha slider. |
|
|
30
|
+
| `presets` | `string[]` | | Preset swatches as CSS colors (a listbox; arrow keys move). |
|
|
31
|
+
| `showInput` | `boolean` | `true` | Show the text field (Enter or blur commits; invalid text reverts). |
|
|
32
|
+
| `name / form` | `string` | | Submit the value with a form (hidden input). |
|
|
33
|
+
| `disabled / readOnly / required` | `boolean` | | Like native controls. Works with <Field>. |
|
|
34
|
+
| `aria-label` | `string` | | Names the picker when it is not inside a <Field>. |
|
|
35
|
+
| `ColorPickerPopover.open / defaultOpen / onOpenChange` | `boolean / (open) => void` | | Popover state (plus every ColorPicker prop). |
|
|
36
|
+
| `ColorPickerPopover.size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Trigger height 32 / 40 / 52px. |
|
|
37
|
+
| `ColorPickerPopover.placement` | `Placement` | `'bottom-start'` | Where the popover opens. |
|
|
38
|
+
|
|
39
|
+
## Examples
|
|
40
|
+
|
|
41
|
+
### Inline with presets
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
const [color, setColor] = useState('#006bff')
|
|
45
|
+
|
|
46
|
+
<ColorPicker aria-label="Brand color" value={color} onValueChange={setColor}
|
|
47
|
+
presets={['#0a0a0a', '#006bff', '#00a74a', '#ff7a00', '#e40014']} />
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Popover in a form
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
<form>
|
|
54
|
+
<ColorPickerPopover aria-label="Label color" name="labelColor" defaultValue="#00a74a" alpha={false} />
|
|
55
|
+
</form>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Write rgb()
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
<ColorPicker aria-label="Overlay" defaultValue="rgb(0 0 0 / 0.4)" format="rgb" onValueCommit={save} />
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Rules
|
|
65
|
+
- One inner shape: area, swatch, presets and tracks share the panel-concentric squircle (panel lg radius − 12px inset).
|
|
66
|
+
- Give it a name: `aria-label` or a surrounding <Field label>.
|
|
67
|
+
- Save in `onValueCommit`, not `onValueChange` (which fires on every drag step).
|
|
68
|
+
- Use `alpha={false}` when transparency makes no sense (labels, brand colors).
|
|
69
|
+
|
|
70
|
+
## Accessibility
|
|
71
|
+
- The picker is a group. The area thumb is a slider announced as "Saturation N%, Brightness N%"; hue and alpha are sliders with value text.
|
|
72
|
+
- Arrows step 1 (Shift 10), Page Up/Down step 10, Home/End jump. Presets are a listbox named by color ("vivid blue").
|
|
73
|
+
|
|
74
|
+
## DOM contract (for agents operating the page)
|
|
75
|
+
|
|
76
|
+
- Selector: `[data-sw="color-picker"], [data-sw="color-picker-popover"]`
|
|
77
|
+
- `data-disabled`: present when disabled
|
|
78
|
+
- `data-state (popover)`: 'open' | 'closed'
|
|
79
|
+
- `aria-valuenow (thumbs)`: channel values
|
|
80
|
+
- How to operate: Agent bridge: setValue(cssColor) (any CSS color; returns false when it does not parse); popover adds open(), close(); items = presets. DOM: type into [data-sw="color-picker-input"] input and press Enter, or click a [data-sw="color-picker-swatch-item"].
|
|
81
|
+
|
|
82
|
+
Related: `input`, `popover`, `slider`
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Combobox
|
|
2
|
+
|
|
3
|
+
> A searchable select: type to filter a popup list and pick one value, or several shown as chips. Async-friendly.
|
|
4
|
+
|
|
5
|
+
Category: selection · Status: beta · Slug: `combobox`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Combobox, ComboboxItem, ComboboxGroup } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Choosing from many options (users, repos, countries) where typing is faster than scrolling.
|
|
13
|
+
- Several values as chips (`multiple`): labels, reviewers.
|
|
14
|
+
- Server search: `onInputChange` + `filter={false}` + `loading`.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Free text where any value is fine — use Autocomplete.
|
|
18
|
+
- Under ~8 options — use Select.
|
|
19
|
+
- Running commands — use Command.
|
|
20
|
+
|
|
21
|
+
## Props
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `items` | `Array<{ value: string; label: string; keywords?: string[]; disabled?: boolean; icon?: ReactNode; description?: ReactNode } \| { type: 'group'; label: string; items: [...] } \| { type: 'separator' }>` | | Options as data — the one-line way. Or pass `<ComboboxItem>` children instead. |
|
|
26
|
+
| `value / defaultValue / onValueChange` | `string \| null (string[] with multiple)` | | Selected value(s). |
|
|
27
|
+
| `multiple` | `boolean` | `false` | Pick several; chips in the field, Backspace on empty text removes the last. |
|
|
28
|
+
| `inputValue / defaultInputValue / onInputChange` | `string / (text) => void` | | The typed text. Use `onInputChange` to fetch results. |
|
|
29
|
+
| `filter` | `'contains' \| 'startsWith' \| false \| (item, query) => boolean` | `'contains'` | How typing narrows the list (label + keywords). `false` for server-filtered results. |
|
|
30
|
+
| `loading` | `boolean` | `false` | Spinner in the field, a loading row, aria-busy on the list. |
|
|
31
|
+
| `emptyMessage` | `ReactNode` | `"No results"` | Shown when nothing matches. |
|
|
32
|
+
| `openOnFocus` | `boolean` | `false` | Open as soon as the field is focused. |
|
|
33
|
+
| `clearable` | `boolean` | `false` | Show a clear (✕) button while there is a value. |
|
|
34
|
+
| `placeholder / label / icon` | `string / ReactNode / ReactNode` | | Placeholder, visible label, leading icon. |
|
|
35
|
+
| `open / defaultOpen / onOpenChange` | `boolean` | | Popup state. |
|
|
36
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field heights 32 / 40 / 52px, like Input. |
|
|
37
|
+
| `name` | `string` | | Native form field name; the value submits through hidden inputs (one per value when multiple). |
|
|
38
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. Inherit from a surrounding `<Field>`. |
|
|
39
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label or Field. |
|
|
40
|
+
|
|
41
|
+
## Anatomy
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
Combobox
|
|
45
|
+
├─ field text input, chips when multiple, clear and chevron buttons
|
|
46
|
+
└─ popup PopupPanel
|
|
47
|
+
└─ list ComboboxGroup / ComboboxGroupLabel / ComboboxItem / ComboboxSeparator
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Built from: `PopupPanel (usePopup)`, `useListNavigation`, `useSquircle`.
|
|
51
|
+
|
|
52
|
+
## Examples
|
|
53
|
+
|
|
54
|
+
### Single
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
<Combobox label="Repository" placeholder="Search repos…" items={repos.map((r) => ({ value: r.id, label: r.name }))} onValueChange={setRepo} />
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Multiple chips
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
<Combobox multiple aria-label="Reviewers" placeholder="Add reviewers" defaultValue={['ada']} items={[
|
|
64
|
+
{ value: 'ada', label: 'Ada Lovelace' },
|
|
65
|
+
{ value: 'grace', label: 'Grace Hopper' },
|
|
66
|
+
{ value: 'alan', label: 'Alan Turing' },
|
|
67
|
+
]} />
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Async search
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
const [results, setResults] = useState([])
|
|
74
|
+
const [loading, setLoading] = useState(false)
|
|
75
|
+
<Combobox
|
|
76
|
+
aria-label="User"
|
|
77
|
+
filter={false}
|
|
78
|
+
loading={loading}
|
|
79
|
+
items={results}
|
|
80
|
+
onInputChange={async (q) => { setLoading(true); setResults(await searchUsers(q)); setLoading(false) }}
|
|
81
|
+
/>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Rules
|
|
85
|
+
- Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
|
|
86
|
+
- Keep the chosen option visible as the field text (single) or chips (multiple); never clear what the user picked on blur.
|
|
87
|
+
|
|
88
|
+
## Accessibility
|
|
89
|
+
- Input role="combobox" with aria-autocomplete="list", aria-expanded, aria-controls and aria-activedescendant; focus never leaves the input.
|
|
90
|
+
- Typing opens + filters; ArrowDown/Up open and move; Enter chooses; Escape closes; Backspace on empty text removes the last chip.
|
|
91
|
+
|
|
92
|
+
## DOM contract (for agents operating the page)
|
|
93
|
+
|
|
94
|
+
- Selector: `[data-sw="combobox"]`
|
|
95
|
+
- `aria-expanded`: true while the list is open (on the trigger / input)
|
|
96
|
+
- `aria-activedescendant`: id of the highlighted option while open
|
|
97
|
+
- `aria-selected`: on each [role=option]: whether it is chosen
|
|
98
|
+
- `data-value`: on each option: its value
|
|
99
|
+
- `data-state`: root: 'open' | 'closed'
|
|
100
|
+
- `data-disabled / data-invalid`: present when disabled / invalid
|
|
101
|
+
- `[data-sw="combobox-chip"]`: one per chosen value (multiple), with data-value
|
|
102
|
+
- How to operate: Type into [data-sw="combobox-input"], then click an enabled [role=option]. Agent bridge: setValue(value | value[] | null), select(value), remove(value), clear(), setInputValue(text), open(), close(). Use option IDs or unique full labels. Null clears the selection. Remove an option that left the results by its selected ID.
|
|
103
|
+
|
|
104
|
+
Related: `select`, `autocomplete`, `command`
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Command
|
|
2
|
+
|
|
3
|
+
> A command palette: a search field over grouped commands with shortcuts and nested pages; `CommandDialog` opens it with ⌘K.
|
|
4
|
+
|
|
5
|
+
Category: navigation · Status: beta · Slug: `command`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Command, CommandInput, CommandList, CommandGroup, CommandItem, CommandSeparator, CommandEmpty, CommandPage, CommandShortcut, CommandDialog } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- A ⌘K palette for jumping and running actions across an app.
|
|
13
|
+
- An inline searchable action list (e.g. "Add block").
|
|
14
|
+
- Drill-down choices with pages (Switch project → list of projects).
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Choosing a form value — use Combobox.
|
|
18
|
+
- A handful of actions on one object — use Menu.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `items` | `Array<{ value, label, keywords?, icon?, shortcut?, disabled?, description?, items? (page), onSelect? } \| { type: 'group', label, items } \| { type: 'separator' }>` | | Commands as data; renders input + list for you. An item with `items` opens a page. |
|
|
25
|
+
| `onAction` | `(value: string) => void` | | Runs when a command runs (Enter, click or its shortcut). |
|
|
26
|
+
| `query / defaultQuery / onQueryChange` | `string` | | Search text. |
|
|
27
|
+
| `value / defaultValue / onValueChange` | `string \| null` | | The highlighted command (the first match is highlighted by default). |
|
|
28
|
+
| `pages / defaultPages / onPagesChange` | `string[]` | | Stack of open pages. |
|
|
29
|
+
| `filter` | `'contains' \| 'fuzzy' \| 'startsWith' \| false \| fn` | `'contains'` | How the search narrows commands (label + keywords). |
|
|
30
|
+
| `loading` | `boolean` | | Spinner in the search field and "Loading…" while empty. |
|
|
31
|
+
| `loop / bordered / placeholder` | `boolean / boolean / string` | | Arrow wrap (true); framed surface (true, false in a dialog); placeholder for `items` mode. Inline density is compact (34px rows, 6px list inset); CommandDialog is roomy (40px rows, 8px inset). Row corners are concentric with the frame. |
|
|
32
|
+
| `CommandItem: value?, label?, keywords?, icon?, shortcut?, page?, disabled?, onSelect?` | `props` | | `shortcut` ("mod+p") runs it while the palette is mounted, even when filtered out. `page` opens that CommandPage. `onSelect(e)` + `e.preventDefault()` skips onAction/closing. |
|
|
33
|
+
| `CommandPage: value?` | `string` | | Commands shown only while this page is open; leave `value` out for the first page. |
|
|
34
|
+
| `CommandGroup: heading` | `ReactNode` | | Group label; hides itself when no command in it matches. |
|
|
35
|
+
| `CommandEmpty: children` | `ReactNode` | `"No results"` | Shown when nothing matches. |
|
|
36
|
+
| `CommandDialog: open / defaultOpen / onOpenChange, shortcut, closeOnSelect, aria-label + all Command props` | `boolean, string \| false = 'mod+k', boolean = true` | | Modal palette toggled by the shortcut; closes after a command runs. |
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
40
|
+
### Inline palette
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
<Command onAction={run}>
|
|
44
|
+
<CommandInput placeholder="Type a command…" />
|
|
45
|
+
<CommandList>
|
|
46
|
+
<CommandGroup heading="Agents">
|
|
47
|
+
<CommandItem value="new-agent" icon={<Icon name="plus" />} shortcut="mod+n">New agent</CommandItem>
|
|
48
|
+
<CommandItem value="runs" page="runs">Open run…</CommandItem>
|
|
49
|
+
</CommandGroup>
|
|
50
|
+
<CommandPage value="runs">
|
|
51
|
+
<CommandItem value="run-812">Run #812</CommandItem>
|
|
52
|
+
</CommandPage>
|
|
53
|
+
<CommandEmpty>No commands found.</CommandEmpty>
|
|
54
|
+
</CommandList>
|
|
55
|
+
</Command>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### ⌘K dialog from data
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
<CommandDialog onAction={run} items={[
|
|
62
|
+
{ type: 'group', label: 'Navigate', items: [
|
|
63
|
+
{ value: 'dashboard', label: 'Dashboard', shortcut: 'mod+1' },
|
|
64
|
+
{ value: 'settings', label: 'Settings', keywords: ['preferences'] },
|
|
65
|
+
] },
|
|
66
|
+
{ value: 'theme', label: 'Change theme…', items: [
|
|
67
|
+
{ value: 'light', label: 'Light' },
|
|
68
|
+
{ value: 'dark', label: 'Dark' },
|
|
69
|
+
] },
|
|
70
|
+
]} />
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Rules
|
|
74
|
+
- Search matches are shown weight-free: matched text in the foreground, the rest muted. On a page the search icon becomes a ghost back button.
|
|
75
|
+
- Commands are verbs or destinations in sentence case; add `keywords` for synonyms.
|
|
76
|
+
- One CommandDialog per app; its default shortcut is ⌘K / Ctrl+K.
|
|
77
|
+
- Group by intent (Navigate, Create, Settings); put the most used first.
|
|
78
|
+
|
|
79
|
+
## Accessibility
|
|
80
|
+
- Input role="combobox" (aria-expanded=true, aria-controls the list, aria-activedescendant); list role="listbox"; commands role="option".
|
|
81
|
+
- Typing filters and highlights the first match; arrows move; Enter runs; Escape clears the search, then goes back a page, then closes the dialog; Backspace on an empty search goes back.
|
|
82
|
+
- CommandDialog is role="dialog" aria-modal with a focus trap and scroll lock; focus returns to where it was.
|
|
83
|
+
|
|
84
|
+
## DOM contract (for agents operating the page)
|
|
85
|
+
|
|
86
|
+
- Selector: `[data-sw="command"]`
|
|
87
|
+
- `data-page`: current page value (absent on the first page)
|
|
88
|
+
- `[data-sw="command-item"]`: visible commands; data-value, data-label, data-active (highlighted), data-disabled
|
|
89
|
+
- `[data-sw="command-dialog"]`: hidden marker with data-state 'open' | 'closed'
|
|
90
|
+
- How to operate: Type into [data-sw="command-input"] and press Enter, or click a [data-sw="command-item"]. Agent bridge (command): search(text), clear(), back(), select(valueOrLabel); items = visible commands. (command-dialog): open(), close(), toggle().
|
|
91
|
+
|
|
92
|
+
Related: `menu`, `combobox`, `dialog`
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# DashboardGrid
|
|
2
|
+
|
|
3
|
+
> A 12-column grid of DashboardTiles that share 1px lines in one frame, or sit apart as separate cards. Tiles reorder by their header grip, and DashboardSection folds a row.
|
|
4
|
+
|
|
5
|
+
Category: layout · Status: beta · Slug: `dashboard-grid`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { DashboardGrid, DashboardTile, DashboardSection } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- The main area of a dashboard: KPI strip, charts, tables.
|
|
13
|
+
- Grouping related tiles into foldable rows (one row per service or area).
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Cards scattered with big gaps and their own shadows. The default joined variant shares lines.
|
|
17
|
+
- Fixed heights on tiles, except charts and maps that need one.
|
|
18
|
+
- Tiles that answer more than one question. Split them.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `variant` | `'flush' \| 'joined' \| 'gapped'` | `'flush' in AppShellMain, else 'joined'` | flush: tiles share the shell's lines to the edges, with no frame. joined: shared lines in one rounded frame. gapped: separate framed cards 12px apart, only for galleries of independent items. |
|
|
25
|
+
| `minTileWidth` | `number` | `280` | Tiles narrower than this grow to half, then full width. |
|
|
26
|
+
| `columns` | `number` | `12` | Columns on wide containers. |
|
|
27
|
+
| `rowHeight` | `number` | | Fixed row height for tiles with rowSpan. By default rows follow their content. |
|
|
28
|
+
| `order / defaultOrder / onOrderChange` | `string[]` | | Tile ids in order. onOrderChange turns on reordering by the header grip (drag, or Space, arrows, Space). |
|
|
29
|
+
| `DashboardTile.id` | `string` | | Stable id, required for reordering. |
|
|
30
|
+
| `DashboardTile.span` | `number` | `4` | Columns spanned. A tile narrower than `minTileWidth` (280px) grows to half, then full width. Rows never end in a hole: the last tile of a row stretches to its end. |
|
|
31
|
+
| `DashboardTile.rowSpan` | `number` | | Rows spanned when rowHeight is set. |
|
|
32
|
+
| `DashboardTile.*` | `CardProps` | | title, count, actions, toolbar, footer, padding. A tile is a grid cell holding a Card in the panel layout, unframed in a joined grid and framed in a gapped one. |
|
|
33
|
+
| `DashboardSection.title / count / actions` | `ReactNode` | | A foldable row heading with a line to the end. |
|
|
34
|
+
| `DashboardSection.keepMounted` | `boolean` | `false` | A folded section unmounts its content so its charts stop loading. Set true to keep it. |
|
|
35
|
+
|
|
36
|
+
## Examples
|
|
37
|
+
|
|
38
|
+
### Sections of joined tiles
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
const [order, setOrder] = useState(['latency', 'errors', 'throughput'])
|
|
42
|
+
|
|
43
|
+
<DashboardSection title="API" count="3 panels">
|
|
44
|
+
<DashboardGrid aria-label="API" order={order} onOrderChange={setOrder}>
|
|
45
|
+
<DashboardTile id="latency" span={6} title="p95 latency" actions={<Pagination variant="compact" pageCount={3} />}>…</DashboardTile>
|
|
46
|
+
<DashboardTile id="errors" span={3} title="Error rate">…</DashboardTile>
|
|
47
|
+
<DashboardTile id="throughput" span={3} title="Throughput">…</DashboardTile>
|
|
48
|
+
</DashboardGrid>
|
|
49
|
+
</DashboardSection>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Rules
|
|
53
|
+
- Order the dashboard from general to specific: metric Tabs over a TrendChart, then tiles, then lists and tables.
|
|
54
|
+
- One question per tile. The title says what it answers.
|
|
55
|
+
- Inside AppShellMain, leave the grid flush (the default) with `AppShellMain padding="none"`: the shell is already the frame.
|
|
56
|
+
- Gapped tiles are for galleries of independent items such as projects. Never use them for metrics.
|
|
57
|
+
- Tiles may sit inside your own wrapper components: they register with the grid through context.
|
|
58
|
+
- Do not wrap a single tile in a section whose title repeats the tile title.
|
|
59
|
+
- Tiles drag from their header bar. The grip is a hover-revealed 2xs Button in the header actions.
|
|
60
|
+
|
|
61
|
+
## Accessibility
|
|
62
|
+
- Tiles are sections labelled by their title. The grip is a button: Space or Enter lifts, the arrows move, Space drops, Escape cancels. Every step is announced.
|
|
63
|
+
- Section headings are buttons with aria-expanded.
|
|
64
|
+
|
|
65
|
+
## DOM contract (for agents operating the page)
|
|
66
|
+
|
|
67
|
+
- Selector: `[data-sw="dashboard-grid"]`
|
|
68
|
+
- `data-variant`: joined | gapped
|
|
69
|
+
- `data-tile-id`: on each [data-sw="dashboard-tile"]
|
|
70
|
+
- `data-state`: open | closed on [data-sw="dashboard-section"]
|
|
71
|
+
- How to operate: Agent bridge: move(id, toIndex), setOrder(ids). state = { order, reorderable }. Sections: open(), close(), toggle().
|
|
72
|
+
|
|
73
|
+
Related: `card`, `tabs`, `trend-chart`, `pagination`, `app-shell`
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# DateInput
|
|
2
|
+
|
|
3
|
+
> Segmented date entry: month, day and year are spinbuttons in the order and with the separators of the user's locale. Value is ISO "YYYY-MM-DD".
|
|
4
|
+
|
|
5
|
+
Category: dates · Status: beta · Slug: `date-input`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { DateInput, Field } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Dates people know by heart and type faster than they pick: birthdays, document dates, an exact deadline.
|
|
13
|
+
|
|
14
|
+
## Avoid
|
|
15
|
+
- Dates people browse for (trip dates, "next Tuesday") → use DatePicker, which adds the calendar.
|
|
16
|
+
- A plain <Input type="text"> for dates → you lose locale order, validation and ISO output.
|
|
17
|
+
- Parsing the displayed text → read `value` / the hidden input; it is always ISO or null.
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `value` | `string \| null` | | ISO date. Stays null until every segment is filled. Pass to control. |
|
|
24
|
+
| `defaultValue` | `string \| null` | `null` | Initial value (and what a form reset restores). |
|
|
25
|
+
| `onValueChange` | `(value: string \| null) => void` | | Runs with the ISO date once complete, and with null when a segment is cleared. |
|
|
26
|
+
| `min` | `string (ISO date)` | | Earliest date that is valid, e.g. "2026-11-01". |
|
|
27
|
+
| `max` | `string (ISO date)` | | Latest date that is valid. |
|
|
28
|
+
| `isDateUnavailable` | `(date: string) => boolean` | | Return true for dates that are invalid (booked days). They stay focusable so keyboard users hear them. |
|
|
29
|
+
| `unavailable` | `DateMatcher \| DateMatcher[]` | | The same as data: ISO dates, `{ from, to }`, `{ before }`, `{ after }`, `{ weekday: [0, 6] }` (weekends) or a function. |
|
|
30
|
+
| `locale` | `string` | `page lang, then browser` | BCP 47 locale for names, order and week start. |
|
|
31
|
+
| `label` | `ReactNode` | | Visible label. Omit inside <Field> (the Field labels it) or pass aria-label. |
|
|
32
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
33
|
+
| `error` | `ReactNode` | | Error text; also marks the field invalid. |
|
|
34
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
35
|
+
| `inline` | `boolean` | `false` | Shrink the box to its content. By default it fills the width, like Input. |
|
|
36
|
+
| `disabled` | `boolean` | `false` | Cannot be focused or changed. |
|
|
37
|
+
| `readOnly` | `boolean` | `false` | Value is visible but cannot change. |
|
|
38
|
+
| `required` | `boolean` | `false` | Blocks form submit while empty. |
|
|
39
|
+
| `invalid` | `boolean` | | Force the invalid look (also set automatically when out of range). |
|
|
40
|
+
| `name` | `string` | | Submits the ISO value under this name through a hidden input. |
|
|
41
|
+
| `form` | `string` | | id of the form it belongs to when outside it. |
|
|
42
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label. |
|
|
43
|
+
| `suffix` | `ReactNode` | | Content inside the box after the segments (an icon). |
|
|
44
|
+
| `id` | `string` | | id for the first segment (so <label for> focuses it). |
|
|
45
|
+
|
|
46
|
+
## Examples
|
|
47
|
+
|
|
48
|
+
### In a Field
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
<Field label="Start date">
|
|
52
|
+
<DateInput name="start" defaultValue="2026-11-14" />
|
|
53
|
+
</Field>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Controlled with bounds
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
const [due, setDue] = useState<string | null>(null)
|
|
60
|
+
<DateInput label="Due date" value={due} onValueChange={setDue} min="2026-11-14" hint="Today or later" />
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### German order (TT.MM.JJJJ)
|
|
64
|
+
|
|
65
|
+
```tsx
|
|
66
|
+
<DateInput aria-label="Geburtsdatum" locale="de-DE" />
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Rules
|
|
70
|
+
- Value is ISO or null — never a partial date. A partly filled date blocks form submit.
|
|
71
|
+
- Let the locale decide the order; do not hard-code MM/DD/YYYY.
|
|
72
|
+
- Uses the same size and corner scale as Input. Pass `inline` to size it to its content.
|
|
73
|
+
|
|
74
|
+
## Accessibility
|
|
75
|
+
- Root is role="group" named by its label; each unit is role="spinbutton" named by its unit (localized via Intl.DisplayNames) with aria-valuenow/min/max and aria-valuetext ("Empty" when empty).
|
|
76
|
+
- Digits fill a segment and auto-advance; ↑/↓ step (wrapping; an empty segment starts at today), PageUp/PageDown take big steps, Home/End go to min/max, ←/→ move between segments, Backspace deletes then moves back, a separator key advances, paste fills every segment.
|
|
77
|
+
|
|
78
|
+
## DOM contract (for agents operating the page)
|
|
79
|
+
|
|
80
|
+
- Selector: `[data-sw="date-input"]`
|
|
81
|
+
- `data-invalid`: out of range / unavailable / error
|
|
82
|
+
- `[data-sw="date-input-group"][data-empty]`: every segment empty
|
|
83
|
+
- `[data-sw="date-input-segment"][data-type]`: year | month | day; aria-valuenow holds its number
|
|
84
|
+
- `input[name] (hidden)`: the ISO value submitted with the form
|
|
85
|
+
- How to operate: Focus a segment and type digits (e.g. focus the first segment and type 11142026 in en-US). Agent bridge: setValue("YYYY-MM-DD"), clear(); state = { value, min, max, disabled, readOnly, invalid, required }.
|
|
86
|
+
|
|
87
|
+
Related: `date-picker`, `time-input`, `calendar`
|