@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.
Files changed (144) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -2
  3. package/agent/components/accordion.md +95 -0
  4. package/agent/components/action-square.md +106 -0
  5. package/agent/components/agent-bridge.md +87 -0
  6. package/agent/components/agent-console.md +123 -0
  7. package/agent/components/alert-dialog.md +82 -0
  8. package/agent/components/app-shell.md +105 -0
  9. package/agent/components/area-chart.md +56 -0
  10. package/agent/components/async-options.md +47 -0
  11. package/agent/components/autocomplete.md +69 -0
  12. package/agent/components/avatar.md +88 -0
  13. package/agent/components/badge.md +51 -0
  14. package/agent/components/bar-chart.md +56 -0
  15. package/agent/components/bar-list.md +49 -0
  16. package/agent/components/breadcrumbs.md +43 -0
  17. package/agent/components/button.md +109 -0
  18. package/agent/components/calendar.md +114 -0
  19. package/agent/components/canvas.md +105 -0
  20. package/agent/components/card.md +78 -0
  21. package/agent/components/carousel.md +113 -0
  22. package/agent/components/chart-card.md +41 -0
  23. package/agent/components/chart-surface.md +56 -0
  24. package/agent/components/checkbox.md +88 -0
  25. package/agent/components/citation-chip.md +61 -0
  26. package/agent/components/collapsible.md +69 -0
  27. package/agent/components/color-picker.md +82 -0
  28. package/agent/components/combobox.md +104 -0
  29. package/agent/components/command.md +92 -0
  30. package/agent/components/dashboard-grid.md +73 -0
  31. package/agent/components/date-input.md +87 -0
  32. package/agent/components/date-picker.md +122 -0
  33. package/agent/components/dialog.md +97 -0
  34. package/agent/components/donut-chart.md +50 -0
  35. package/agent/components/drawer.md +101 -0
  36. package/agent/components/empty-state.md +52 -0
  37. package/agent/components/field.md +80 -0
  38. package/agent/components/file-input.md +84 -0
  39. package/agent/components/hover-card.md +64 -0
  40. package/agent/components/image-cropper.md +77 -0
  41. package/agent/components/input.md +49 -0
  42. package/agent/components/label.md +53 -0
  43. package/agent/components/line-chart.md +60 -0
  44. package/agent/components/listbox.md +84 -0
  45. package/agent/components/map-view.md +104 -0
  46. package/agent/components/menu.md +117 -0
  47. package/agent/components/menubar.md +67 -0
  48. package/agent/components/meter.md +59 -0
  49. package/agent/components/navigation-menu.md +98 -0
  50. package/agent/components/number-input.md +81 -0
  51. package/agent/components/otp-input.md +67 -0
  52. package/agent/components/pagination.md +80 -0
  53. package/agent/components/password-input.md +67 -0
  54. package/agent/components/pill-button.md +116 -0
  55. package/agent/components/popover.md +85 -0
  56. package/agent/components/poster-card.md +61 -0
  57. package/agent/components/preferences.md +92 -0
  58. package/agent/components/progress.md +63 -0
  59. package/agent/components/provider.md +47 -0
  60. package/agent/components/radio.md +91 -0
  61. package/agent/components/rating.md +66 -0
  62. package/agent/components/reorder.md +61 -0
  63. package/agent/components/resizable.md +87 -0
  64. package/agent/components/scatter-chart.md +49 -0
  65. package/agent/components/scroll-area.md +81 -0
  66. package/agent/components/segmented-control.md +56 -0
  67. package/agent/components/select.md +130 -0
  68. package/agent/components/separator.md +60 -0
  69. package/agent/components/shortcuts.md +50 -0
  70. package/agent/components/sidebar-nav.md +68 -0
  71. package/agent/components/skeleton.md +58 -0
  72. package/agent/components/slider.md +79 -0
  73. package/agent/components/sparkline.md +39 -0
  74. package/agent/components/squircle.md +58 -0
  75. package/agent/components/stat.md +58 -0
  76. package/agent/components/switch.md +48 -0
  77. package/agent/components/table.md +58 -0
  78. package/agent/components/tabs.md +108 -0
  79. package/agent/components/textarea.md +68 -0
  80. package/agent/components/time-input.md +84 -0
  81. package/agent/components/timeline.md +91 -0
  82. package/agent/components/toast.md +85 -0
  83. package/agent/components/toggle.md +76 -0
  84. package/agent/components/token-input.md +66 -0
  85. package/agent/components/toolbar.md +76 -0
  86. package/agent/components/tooltip.md +83 -0
  87. package/agent/components/tracker.md +47 -0
  88. package/agent/components/tree.md +87 -0
  89. package/agent/components/treemap.md +72 -0
  90. package/agent/components/trend-chart.md +80 -0
  91. package/agent/components/trigger-menu.md +67 -0
  92. package/agent/components/typography.md +51 -0
  93. package/agent/components/waterfall.md +78 -0
  94. package/agent/components/week-schedule.md +113 -0
  95. package/agent/llms/actions-and-layout.txt +1749 -0
  96. package/agent/llms/agents.txt +505 -0
  97. package/agent/llms/charts.txt +778 -0
  98. package/agent/llms/dashboards.txt +457 -0
  99. package/agent/llms/extend.txt +132 -0
  100. package/agent/llms/extras.txt +527 -0
  101. package/agent/llms/forms.txt +2152 -0
  102. package/agent/llms/foundations.txt +674 -0
  103. package/agent/llms/hooks.txt +178 -0
  104. package/agent/llms/maps.txt +229 -0
  105. package/agent/llms/overlays-and-navigation.txt +1167 -0
  106. package/agent/llms-full.txt +8717 -0
  107. package/agent/llms.txt +145 -0
  108. package/agent/registry.json +11289 -0
  109. package/agent/tokens.md +66 -0
  110. package/dist/agent/index.d.ts +235 -0
  111. package/dist/agent/index.js +21 -0
  112. package/dist/card-Ipm-Cj5f.d.ts +490 -0
  113. package/dist/charts/index.d.ts +289 -0
  114. package/dist/charts/index.js +815 -0
  115. package/dist/check/cli.d.ts +1 -0
  116. package/dist/check/cli.js +48 -0
  117. package/dist/check/rendered.d.ts +11 -0
  118. package/dist/check/rendered.js +77 -0
  119. package/dist/check/source.d.ts +13 -0
  120. package/dist/check/source.js +182 -0
  121. package/dist/chunk-3DXBM65D.js +65 -0
  122. package/dist/chunk-3H5X4ZP6.js +55 -0
  123. package/dist/chunk-6XC4BC5C.js +92 -0
  124. package/dist/chunk-7H6TEAWD.js +507 -0
  125. package/dist/chunk-I63ZTJOI.js +1089 -0
  126. package/dist/chunk-JCIRUM4W.js +33 -0
  127. package/dist/chunk-LTBEHZ3P.js +25 -0
  128. package/dist/chunk-QDPPLO4U.js +60 -0
  129. package/dist/chunk-U2XFBPU4.js +56 -0
  130. package/dist/chunk-UY2WH5AY.js +681 -0
  131. package/dist/extras.d.ts +203 -0
  132. package/dist/extras.js +904 -0
  133. package/dist/icons-BJiGEAnU.d.ts +68 -0
  134. package/dist/index.d.ts +3737 -0
  135. package/dist/index.js +14477 -0
  136. package/dist/map/index.d.ts +115 -0
  137. package/dist/map/index.js +394 -0
  138. package/dist/meta/index.d.ts +3314 -0
  139. package/dist/meta/index.js +5106 -0
  140. package/dist/rules-1RIZ_JZr.d.ts +38 -0
  141. package/dist/styles.css +4037 -0
  142. package/dist/themes/calm.css +42 -0
  143. package/dist/themes/frost.css +40 -0
  144. 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`