@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,2152 @@
|
|
|
1
|
+
# SW3 UI SDK · Inputs, selection and dates
|
|
2
|
+
|
|
3
|
+
> Text fields, Field wiring, switches, sliders; Select, Combobox, Autocomplete, Listbox, RadioGroup; date and time pickers.
|
|
4
|
+
|
|
5
|
+
Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
|
|
6
|
+
Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
|
|
7
|
+
Index of all topics and components: llms.txt.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Components
|
|
12
|
+
|
|
13
|
+
# Switch
|
|
14
|
+
|
|
15
|
+
> An on/off toggle with a spring-animated thumb, optionally with label and description.
|
|
16
|
+
|
|
17
|
+
Category: inputs · Status: stable · Slug: `switch`
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
import { Switch } from '@peerproblem/sw3-ui'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## When to use
|
|
24
|
+
- Settings that apply immediately (notifications, features).
|
|
25
|
+
|
|
26
|
+
## Avoid
|
|
27
|
+
- Actions that need a Save button — use a checkbox in a form.
|
|
28
|
+
|
|
29
|
+
## Props
|
|
30
|
+
|
|
31
|
+
| Prop | Type | Default | Description |
|
|
32
|
+
| --- | --- | --- | --- |
|
|
33
|
+
| `checked` * | `boolean` | | Controlled state. |
|
|
34
|
+
| `onCheckedChange` * | `(checked: boolean) => void` | | Called on toggle. |
|
|
35
|
+
| `label` | `ReactNode` | | Renders a label row (label left, switch right). |
|
|
36
|
+
| `description` | `ReactNode` | | Quiet line under the label. |
|
|
37
|
+
| `size` | `'sm' \| 'md'` | `'md'` | Track 34 or 44px wide. |
|
|
38
|
+
| `disabled` | `boolean` | `false` | |
|
|
39
|
+
|
|
40
|
+
## Examples
|
|
41
|
+
|
|
42
|
+
### Settings list
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
<Switch label="Weekly digest" description="A summary of your week, every Monday." checked={digest} onCheckedChange={setDigest} />
|
|
46
|
+
<Switch label="Mentions" description="Only when someone mentions you." checked={mentions} onCheckedChange={setMentions} />
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Rules
|
|
50
|
+
- The track uses the smooth capsule curve and the thumb is circular.
|
|
51
|
+
|
|
52
|
+
## Accessibility
|
|
53
|
+
- Native button with role="switch" and aria-checked.
|
|
54
|
+
|
|
55
|
+
## DOM contract (for agents operating the page)
|
|
56
|
+
|
|
57
|
+
- Selector: `[data-sw="switch"]`
|
|
58
|
+
- `aria-checked`: true | false
|
|
59
|
+
- `data-state`: on | off
|
|
60
|
+
- How to operate: Click to toggle. The label is the <label for> of the button.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
# SegmentedControl
|
|
65
|
+
|
|
66
|
+
> Pick one of 2–5 options; the active pill glides between segments (motion layout animation).
|
|
67
|
+
|
|
68
|
+
Category: selection · Status: stable · Slug: `segmented-control`
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
import { SegmentedControl } from '@peerproblem/sw3-ui'
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## When to use
|
|
75
|
+
- Switching between mutually exclusive views.
|
|
76
|
+
- Time ranges on charts (Week / Month / Year).
|
|
77
|
+
|
|
78
|
+
## Avoid
|
|
79
|
+
- More than 5 options or long labels — use Tabs or a select.
|
|
80
|
+
- Formatting buttons in a toolbar, or a choice that can be empty — use ToggleGroup.
|
|
81
|
+
|
|
82
|
+
## Props
|
|
83
|
+
|
|
84
|
+
| Prop | Type | Default | Description |
|
|
85
|
+
| --- | --- | --- | --- |
|
|
86
|
+
| `options` * | `Array<{ value: string; label: ReactNode; disabled?: boolean }>` | | The segments. |
|
|
87
|
+
| `value` * | `string` | | Selected value. |
|
|
88
|
+
| `onValueChange` * | `(value) => void` | | |
|
|
89
|
+
| `aria-label` * | `string` | | Names the control. |
|
|
90
|
+
| `size` | `'sm' \| 'md'` | `'md'` | |
|
|
91
|
+
| `appearance` | `'default' \| 'icon-capsule'` | `'default'` | Icon-only options use a smooth capsule track and a circular selected marker. Give each icon an accessible text label. |
|
|
92
|
+
| `fullWidth` | `boolean` | `false` | Equal-width segments filling the container. |
|
|
93
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'sm'` | Squircle corner radius (token or px). |
|
|
94
|
+
|
|
95
|
+
## Examples
|
|
96
|
+
|
|
97
|
+
### Chart range
|
|
98
|
+
|
|
99
|
+
```tsx
|
|
100
|
+
<SegmentedControl
|
|
101
|
+
aria-label="Range"
|
|
102
|
+
value={range}
|
|
103
|
+
onValueChange={setRange}
|
|
104
|
+
options={[{ value: 'week', label: 'Week' }, { value: 'month', label: 'Month' }, { value: 'year', label: 'Year' }]}
|
|
105
|
+
/>
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Rules
|
|
109
|
+
- The default pill is concentric with the track (track radius − 3px). Both appearances show a focus ring on the selected marker.
|
|
110
|
+
- Set `--sw-segmented-track-bg` on an ancestor to distinguish the track from the surrounding surface. Keep the selected marker distinct from the track.
|
|
111
|
+
|
|
112
|
+
## Accessibility
|
|
113
|
+
- role="radiogroup"; Arrow keys move and select.
|
|
114
|
+
|
|
115
|
+
## DOM contract (for agents operating the page)
|
|
116
|
+
|
|
117
|
+
- Selector: `[data-sw="segmented-control"]`
|
|
118
|
+
- `[role=radio][aria-checked=true]`: the selected segment
|
|
119
|
+
- How to operate: Click the segment button with the matching text.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
# Input
|
|
124
|
+
|
|
125
|
+
> A text field with label, hint, error and optional prefix/suffix, in a squircle frame.
|
|
126
|
+
|
|
127
|
+
Category: inputs · Status: stable · Slug: `input`
|
|
128
|
+
|
|
129
|
+
```tsx
|
|
130
|
+
import { Input } from '@peerproblem/sw3-ui'
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## When to use
|
|
134
|
+
- Single-line text, email, number, search.
|
|
135
|
+
|
|
136
|
+
## Avoid
|
|
137
|
+
- Placeholder as the only label — always pass `label` (or aria-label).
|
|
138
|
+
|
|
139
|
+
## Props
|
|
140
|
+
|
|
141
|
+
| Prop | Type | Default | Description |
|
|
142
|
+
| --- | --- | --- | --- |
|
|
143
|
+
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Heights 28 / 32 / 40 / 52px. Use xs for dense toolbars and card headers. |
|
|
144
|
+
| `variant` | `'outline' \| 'filled'` | `'outline'` | filled: a borderless muted well whose frame appears on focus. Use it for search in dense toolbars. |
|
|
145
|
+
| `shortcut` | `string` | | A key that focuses the field, e.g. '/' or 'mod+k'. Shown as a hint while the field is empty. |
|
|
146
|
+
| `label` | `ReactNode` | | Visible label. |
|
|
147
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
148
|
+
| `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
|
|
149
|
+
| `invalid` | `boolean` | | Mark invalid without error text (e.g. inside a Field that shows the error). |
|
|
150
|
+
| `clearable` | `boolean` | `false` | Show a × button that clears the value (data-sw="input-clear"). |
|
|
151
|
+
| `onValueChange` | `(value: string) => void` | | Called with the new text on every change, including clear. |
|
|
152
|
+
| `prefix / suffix` | `ReactNode` | | Icon or unit inside the field. |
|
|
153
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'sm'` | Squircle corner radius (token or px). |
|
|
154
|
+
| `...rest` | `InputHTMLAttributes` | | value, onChange, type, placeholder… |
|
|
155
|
+
|
|
156
|
+
## Examples
|
|
157
|
+
|
|
158
|
+
### Email
|
|
159
|
+
|
|
160
|
+
```tsx
|
|
161
|
+
<Input label="Email" type="email" placeholder="you@company.com" />
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Rules
|
|
165
|
+
- Search in a list toolbar: `<Input type="search" size="xs" variant="filled" prefix={<Icon name="search"/>} clearable aria-label="Search …"/>`. Escape clears it.
|
|
166
|
+
|
|
167
|
+
## DOM contract (for agents operating the page)
|
|
168
|
+
|
|
169
|
+
- Selector: `[data-sw="input"] input`
|
|
170
|
+
- `aria-invalid`: true on error
|
|
171
|
+
- How to operate: Type into the <input>; its <label> names it. Works inside <Field>. Agent bridge: setValue(text), clear().
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
# Field
|
|
176
|
+
|
|
177
|
+
> Connects one form control to its label, description and error (ids, for, aria-describedby, aria-invalid, required, disabled).
|
|
178
|
+
|
|
179
|
+
Category: inputs · Status: beta · Slug: `field`
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
import { Field, FieldLabel, FieldDescription, FieldError } from '@peerproblem/sw3-ui'
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## When to use
|
|
186
|
+
- Any form control that needs a visible label, help text or validation message.
|
|
187
|
+
- Controls without their own `label` prop (Slider, Radio Group, OTP Input, Rating, Number Input in a form).
|
|
188
|
+
- Showing an error from your own validation or the server: pass `error`.
|
|
189
|
+
|
|
190
|
+
## Avoid
|
|
191
|
+
- Two controls in one Field — each Field connects exactly one control. Use a CheckboxGroup / RadioGroup for sets.
|
|
192
|
+
- Passing `label` to both the Field and the Input inside it (double label).
|
|
193
|
+
- Hand-wiring ids and aria-describedby — the Field does it.
|
|
194
|
+
|
|
195
|
+
## Props
|
|
196
|
+
|
|
197
|
+
| Prop | Type | Default | Description |
|
|
198
|
+
| --- | --- | --- | --- |
|
|
199
|
+
| `label` | `ReactNode` | | Visible label (or put a `<FieldLabel>` in children). |
|
|
200
|
+
| `description` | `ReactNode` | | Help text under the control (or `<FieldDescription>`). |
|
|
201
|
+
| `error` | `ReactNode` | | Error message. Setting it marks the field invalid. |
|
|
202
|
+
| `invalid` | `boolean` | `!!error` | Invalid without a message, or `false` to hide the error. |
|
|
203
|
+
| `required` | `boolean` | `false` | Marks the control required and shows `*` after the label. |
|
|
204
|
+
| `disabled` | `boolean` | `false` | Disables the control. |
|
|
205
|
+
| `controlId` | `string` | | id for the control. Generated when omitted. |
|
|
206
|
+
| `children` * | `ReactNode` | | The control (Input, Textarea, Slider, RadioGroup…), plus optional parts. |
|
|
207
|
+
| `FieldError.forceShow` | `boolean` | `false` | Show the error part even when the field is valid. |
|
|
208
|
+
|
|
209
|
+
## Examples
|
|
210
|
+
|
|
211
|
+
### Shorthand
|
|
212
|
+
|
|
213
|
+
```tsx
|
|
214
|
+
<Field label="Project name" description="Lowercase, no spaces." required>
|
|
215
|
+
<Input placeholder="my-agent" />
|
|
216
|
+
</Field>
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Parts + server error
|
|
220
|
+
|
|
221
|
+
```tsx
|
|
222
|
+
<Field invalid={!!serverError}>
|
|
223
|
+
<FieldLabel>API key</FieldLabel>
|
|
224
|
+
<PasswordInput autoComplete="off" />
|
|
225
|
+
<FieldDescription>Find it in Settings → Keys.</FieldDescription>
|
|
226
|
+
<FieldError>{serverError}</FieldError>
|
|
227
|
+
</Field>
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Any control
|
|
231
|
+
|
|
232
|
+
```tsx
|
|
233
|
+
<Field label="Temperature" description="Higher is more creative.">
|
|
234
|
+
<Slider defaultValue={0.7} min={0} max={2} step={0.1} />
|
|
235
|
+
</Field>
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Rules
|
|
239
|
+
- One Field per control. Keep descriptions to one short line; put errors in `error`, not in the description.
|
|
240
|
+
- Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
|
|
241
|
+
|
|
242
|
+
## Accessibility
|
|
243
|
+
- Label uses <label for> for labelable controls and aria-labelledby for groups; pressing it focuses or checks the control.
|
|
244
|
+
- Description and error are linked with aria-describedby; the error has role="alert".
|
|
245
|
+
|
|
246
|
+
## DOM contract (for agents operating the page)
|
|
247
|
+
|
|
248
|
+
- Selector: `[data-sw="field"]`
|
|
249
|
+
- `data-invalid`: present when invalid
|
|
250
|
+
- `data-disabled`: present when disabled
|
|
251
|
+
- `data-required`: present when required
|
|
252
|
+
- How to operate: Find the control inside it; its accessible name is the [data-sw="field-label"] text. Errors are in [data-sw="field-error"].
|
|
253
|
+
|
|
254
|
+
Related: `label`, `input`, `textarea`
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
# Label
|
|
259
|
+
|
|
260
|
+
> Names any control; pressing it focuses or activates the control, even groups a native label cannot reach.
|
|
261
|
+
|
|
262
|
+
Category: inputs · Status: beta · Slug: `label`
|
|
263
|
+
|
|
264
|
+
```tsx
|
|
265
|
+
import { Label } from '@peerproblem/sw3-ui'
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
## When to use
|
|
269
|
+
- A visible name for a control outside a Field: `<Label htmlFor="plan">` next to `<RadioGroup id="plan">`.
|
|
270
|
+
- Inside `<Field>` (no htmlFor needed) — same as FieldLabel.
|
|
271
|
+
|
|
272
|
+
## Avoid
|
|
273
|
+
- Label without htmlFor outside a Field — it names nothing. Use Field, or a control with its own `label` prop.
|
|
274
|
+
- Using a <span> as a label — screen readers and agents won’t connect it.
|
|
275
|
+
|
|
276
|
+
## Props
|
|
277
|
+
|
|
278
|
+
| Prop | Type | Default | Description |
|
|
279
|
+
| --- | --- | --- | --- |
|
|
280
|
+
| `htmlFor` | `string` | | id of the control. Optional inside a Field. |
|
|
281
|
+
| `required` | `boolean` | | Show a `*` marker. |
|
|
282
|
+
| `...rest` | `LabelHTMLAttributes` | | id, className, children… |
|
|
283
|
+
|
|
284
|
+
## Examples
|
|
285
|
+
|
|
286
|
+
### Label a radio group
|
|
287
|
+
|
|
288
|
+
```tsx
|
|
289
|
+
<Label htmlFor="plan">Plan</Label>
|
|
290
|
+
<RadioGroup id="plan" defaultValue="pro" items={[{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }]} />
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### Inside a Field
|
|
294
|
+
|
|
295
|
+
```tsx
|
|
296
|
+
<Field>
|
|
297
|
+
<Label>Model</Label>
|
|
298
|
+
<Input defaultValue="sw3-large" />
|
|
299
|
+
</Field>
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
## Accessibility
|
|
303
|
+
- Renders a native <label>. Non-labelable targets get aria-labelledby pointing at it (unless they already have a name).
|
|
304
|
+
|
|
305
|
+
## DOM contract (for agents operating the page)
|
|
306
|
+
|
|
307
|
+
- Selector: `[data-sw="label"]`
|
|
308
|
+
- How to operate: Click it to focus/check its control.
|
|
309
|
+
|
|
310
|
+
Related: `field`
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
# Textarea
|
|
315
|
+
|
|
316
|
+
> Multi-line text field that grows with its content between minRows and maxRows, with an optional character count.
|
|
317
|
+
|
|
318
|
+
Category: inputs · Status: beta · Slug: `textarea`
|
|
319
|
+
|
|
320
|
+
```tsx
|
|
321
|
+
import { Textarea } from '@peerproblem/sw3-ui'
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
## When to use
|
|
325
|
+
- Prompts, messages, descriptions, notes — anything longer than one line.
|
|
326
|
+
- Chat composers: `submitShortcut="enter"` + `onSubmitShortcut`.
|
|
327
|
+
|
|
328
|
+
## Avoid
|
|
329
|
+
- Single-line values (names, emails) — use Input.
|
|
330
|
+
- A fixed huge height — let it autosize with `minRows`/`maxRows`.
|
|
331
|
+
|
|
332
|
+
## Props
|
|
333
|
+
|
|
334
|
+
| Prop | Type | Default | Description |
|
|
335
|
+
| --- | --- | --- | --- |
|
|
336
|
+
| `value` | `string` | | Controlled text. |
|
|
337
|
+
| `defaultValue` | `string` | | Initial text when uncontrolled. |
|
|
338
|
+
| `onValueChange` | `(value: string) => void` | | Called on every edit. |
|
|
339
|
+
| `autoResize` | `boolean` | `true` | Grow and shrink with the text. |
|
|
340
|
+
| `minRows` | `number` | `3` | Rows when empty. |
|
|
341
|
+
| `maxRows` | `number` | | Stop growing and scroll after this many rows. |
|
|
342
|
+
| `showCount` | `boolean` | `false` | Show "count / maxLength" under the field. Set `maxLength` to enforce the limit. |
|
|
343
|
+
| `submitShortcut` | `'enter' \| 'mod+enter'` | | Keys that submit. `enter` keeps Shift+Enter for new lines. |
|
|
344
|
+
| `onSubmitShortcut` | `(value: string) => void` | | Runs on the shortcut; without it the surrounding form submits. |
|
|
345
|
+
| `label` | `ReactNode` | | Visible label. Inside `<Field>`, give the label to the Field instead. |
|
|
346
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
347
|
+
| `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
|
|
348
|
+
| `invalid` | `boolean` | | Invalid without a message (a surrounding Field sets it too). |
|
|
349
|
+
| `disabled / required / readOnly` | `boolean` | | Native states. Inherit from a surrounding Field. |
|
|
350
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
351
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| number` | `'sm'` | Squircle corner radius of the field frame. |
|
|
352
|
+
| `...rest` | `TextareaHTMLAttributes` | | placeholder, maxLength, name, onChange… |
|
|
353
|
+
|
|
354
|
+
## Examples
|
|
355
|
+
|
|
356
|
+
### Prompt with count
|
|
357
|
+
|
|
358
|
+
```tsx
|
|
359
|
+
<Textarea label="System prompt" placeholder="You are a helpful agent…" maxLength={500} showCount minRows={3} maxRows={8} />
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
### Chat composer
|
|
363
|
+
|
|
364
|
+
```tsx
|
|
365
|
+
<Textarea aria-label="Message" minRows={1} maxRows={6} submitShortcut="enter" onSubmitShortcut={(text) => send(text)} />
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
## Rules
|
|
369
|
+
- Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
|
|
370
|
+
|
|
371
|
+
## Accessibility
|
|
372
|
+
- Native <textarea>. The count is aria-live="polite".
|
|
373
|
+
|
|
374
|
+
## DOM contract (for agents operating the page)
|
|
375
|
+
|
|
376
|
+
- Selector: `[data-sw="textarea"] textarea`
|
|
377
|
+
- `aria-invalid`: true on error
|
|
378
|
+
- `data-full`: on [data-sw="textarea-count"] when at maxLength
|
|
379
|
+
- How to operate: Type into the <textarea>. Agent bridge: setValue(text), clear().
|
|
380
|
+
|
|
381
|
+
Related: `input`, `field`
|
|
382
|
+
|
|
383
|
+
---
|
|
384
|
+
|
|
385
|
+
# Checkbox / CheckboxGroup
|
|
386
|
+
|
|
387
|
+
> A squircle box with an animated check: checked, unchecked or indeterminate. CheckboxGroup shares one array value and supports a select-all parent.
|
|
388
|
+
|
|
389
|
+
Category: inputs · Status: beta · Slug: `checkbox`
|
|
390
|
+
|
|
391
|
+
```tsx
|
|
392
|
+
import { Checkbox, CheckboxGroup } from '@peerproblem/sw3-ui'
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
## When to use
|
|
396
|
+
- Independent yes/no options in a form that is submitted later.
|
|
397
|
+
- Picking several items from a short list (CheckboxGroup).
|
|
398
|
+
- Accepting terms.
|
|
399
|
+
|
|
400
|
+
## Avoid
|
|
401
|
+
- Settings that apply immediately — use Switch.
|
|
402
|
+
- Choosing exactly one option — use RadioGroup or SegmentedControl.
|
|
403
|
+
- Long lists (>8) — use a multi-select Combobox/Listbox.
|
|
404
|
+
|
|
405
|
+
## Props
|
|
406
|
+
|
|
407
|
+
| Prop | Type | Default | Description |
|
|
408
|
+
| --- | --- | --- | --- |
|
|
409
|
+
| `checked` | `boolean \| 'indeterminate'` | | Controlled state. |
|
|
410
|
+
| `defaultChecked` | `boolean \| 'indeterminate'` | `false` | Initial state when uncontrolled. |
|
|
411
|
+
| `onCheckedChange` | `(checked: boolean) => void` | | Called on press. From indeterminate, a press checks. |
|
|
412
|
+
| `label` | `ReactNode` | | Clickable text next to the box (children works too). |
|
|
413
|
+
| `description` | `ReactNode` | | Muted line under the label. |
|
|
414
|
+
| `value` | `string` | `'on'` | Submitted while checked; identifies it inside a group. |
|
|
415
|
+
| `name` | `string` | | Form field name. |
|
|
416
|
+
| `parent` | `boolean` | | Inside a group: select-all checkbox, indeterminate when some are checked. |
|
|
417
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. |
|
|
418
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Box 16 / 18 / 22px. |
|
|
419
|
+
| `CheckboxGroup.value` | `string[]` | | Values of checked boxes (controlled). |
|
|
420
|
+
| `CheckboxGroup.defaultValue` | `string[]` | `[]` | Initial values. |
|
|
421
|
+
| `CheckboxGroup.onValueChange` | `(value: string[]) => void` | | Called when any box changes. |
|
|
422
|
+
| `CheckboxGroup.items` | `{ value, label, description?, disabled? }[]` | | Shorthand: one Checkbox per item. |
|
|
423
|
+
| `CheckboxGroup.allValues` | `string[]` | | Values a parent checkbox controls (default: the boxes in the group). |
|
|
424
|
+
| `CheckboxGroup.name / disabled / readOnly / orientation` | `string / boolean / boolean / 'vertical' \| 'horizontal'` | | Shared settings. |
|
|
425
|
+
|
|
426
|
+
## Examples
|
|
427
|
+
|
|
428
|
+
### Single
|
|
429
|
+
|
|
430
|
+
```tsx
|
|
431
|
+
<Checkbox label="Email me when the run finishes" defaultChecked />
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
### Group with select-all
|
|
435
|
+
|
|
436
|
+
```tsx
|
|
437
|
+
const [tools, setTools] = useState(['search'])
|
|
438
|
+
|
|
439
|
+
<CheckboxGroup aria-label="Tools" value={tools} onValueChange={setTools}>
|
|
440
|
+
<Checkbox parent label="All tools" />
|
|
441
|
+
<Checkbox value="search" label="Web search" />
|
|
442
|
+
<Checkbox value="code" label="Code interpreter" />
|
|
443
|
+
<Checkbox value="files" label="File access" />
|
|
444
|
+
</CheckboxGroup>
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
### Items shorthand
|
|
448
|
+
|
|
449
|
+
```tsx
|
|
450
|
+
<CheckboxGroup aria-label="Notify" name="notify" defaultValue={['email']} items={[
|
|
451
|
+
{ value: 'email', label: 'Email' },
|
|
452
|
+
{ value: 'slack', label: 'Slack' },
|
|
453
|
+
]} />
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
## Rules
|
|
457
|
+
- Labels are positive statements ("Send a summary", not "Don't skip the summary").
|
|
458
|
+
- Use the accent only through the checked state; never recolor the box.
|
|
459
|
+
|
|
460
|
+
## Accessibility
|
|
461
|
+
- role="checkbox" with aria-checked true / false / mixed. Space toggles; Enter does not.
|
|
462
|
+
- Group is role="group"; name it with aria-label or a Field label.
|
|
463
|
+
|
|
464
|
+
## DOM contract (for agents operating the page)
|
|
465
|
+
|
|
466
|
+
- Selector: `[data-sw="checkbox"]`
|
|
467
|
+
- `aria-checked`: true | false | mixed
|
|
468
|
+
- `data-state`: checked | unchecked | indeterminate
|
|
469
|
+
- `disabled`: native disabled
|
|
470
|
+
- 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.
|
|
471
|
+
|
|
472
|
+
Related: `switch`, `radio`, `field`
|
|
473
|
+
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
# RadioGroup / Radio
|
|
477
|
+
|
|
478
|
+
> One choice out of a few, all visible: radio dots, or card rows with icons (`variant="card"`). Arrow keys move and check; submits natively with `name`.
|
|
479
|
+
|
|
480
|
+
Category: selection · Status: beta · Slug: `radio`
|
|
481
|
+
|
|
482
|
+
```tsx
|
|
483
|
+
import { RadioGroup, Radio } from '@peerproblem/sw3-ui'
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
## When to use
|
|
487
|
+
- Choosing exactly one of 2–6 options where seeing all of them helps.
|
|
488
|
+
- Form choices with a short description per option.
|
|
489
|
+
- A list of modes or sections in a side panel or settings page: `variant="card"` with icons.
|
|
490
|
+
|
|
491
|
+
## Avoid
|
|
492
|
+
- Many options — use Select.
|
|
493
|
+
- Picking an item to open (a project, a run) — use Listbox.
|
|
494
|
+
- A view switcher — use SegmentedControl or Tabs.
|
|
495
|
+
- Independent options — use Checkbox.
|
|
496
|
+
|
|
497
|
+
## Props
|
|
498
|
+
|
|
499
|
+
| Prop | Type | Default | Description |
|
|
500
|
+
| --- | --- | --- | --- |
|
|
501
|
+
| `value` | `string \| null` | | Checked value (controlled). null checks none. |
|
|
502
|
+
| `defaultValue` | `string \| null` | `null` | Initial value. |
|
|
503
|
+
| `onValueChange` | `(value: string) => void` | | Called on click or arrow key. |
|
|
504
|
+
| `items` | `{ value, label, description?, icon?, disabled? }[]` | | Shorthand: one Radio per item. |
|
|
505
|
+
| `variant` | `'default' \| 'card'` | `'default'` | card: rows with an optional icon and no dot; a squircle fill marks hover and the checked row. |
|
|
506
|
+
| `columns` | `1 \| 2 \| 3 \| 4` | `1` | Card columns once the container is at least 35rem wide. |
|
|
507
|
+
| `radius` | `RadiusValue` | `'md'` | Corner radius of card rows. |
|
|
508
|
+
| `name` | `string` | | Form field name; submits the checked value. |
|
|
509
|
+
| `loop` | `boolean` | `true` | Arrow keys wrap around. |
|
|
510
|
+
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout and arrow keys. |
|
|
511
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. |
|
|
512
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Circle 16 / 18 / 22px. |
|
|
513
|
+
| `aria-label` | `string` | | Names the group when there is no Field/Label. |
|
|
514
|
+
| `Radio.value` * | `string` | | Value of this option. |
|
|
515
|
+
| `Radio.label / description` | `ReactNode` | | Clickable text and a muted line. |
|
|
516
|
+
| `Radio.icon` | `IconName \| ReactNode` | | Leading 18px icon in card rows, e.g. 'user', 'clock'. |
|
|
517
|
+
| `Radio.disabled` | `boolean` | | Skip this option. |
|
|
518
|
+
|
|
519
|
+
## Examples
|
|
520
|
+
|
|
521
|
+
### Compound
|
|
522
|
+
|
|
523
|
+
```tsx
|
|
524
|
+
<RadioGroup aria-label="Run mode" name="mode" defaultValue="auto">
|
|
525
|
+
<Radio value="auto" label="Autonomous" description="The agent runs every step." />
|
|
526
|
+
<Radio value="review" label="Review each step" />
|
|
527
|
+
<Radio value="dry" label="Dry run" disabled />
|
|
528
|
+
</RadioGroup>
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
### Options in a foldable side panel
|
|
532
|
+
|
|
533
|
+
```tsx
|
|
534
|
+
<Accordion size="sm" multiple defaultValue={['view']}>
|
|
535
|
+
<AccordionItem value="view">
|
|
536
|
+
<AccordionTrigger>View</AccordionTrigger>
|
|
537
|
+
<AccordionPanel>
|
|
538
|
+
<RadioGroup variant="card" aria-label="Section" value={section} onValueChange={setSection}>
|
|
539
|
+
<Radio value="deliveries" icon="upload" label="Deliveries" />
|
|
540
|
+
<Radio value="agents" icon="user" label="Agents & keys" />
|
|
541
|
+
<Radio value="log" icon="clock" label="Access log" description="Last 30 days" />
|
|
542
|
+
</RadioGroup>
|
|
543
|
+
</AccordionPanel>
|
|
544
|
+
</AccordionItem>
|
|
545
|
+
</Accordion>
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
### Items in a Field
|
|
549
|
+
|
|
550
|
+
```tsx
|
|
551
|
+
<Field label="Region" required>
|
|
552
|
+
<RadioGroup items={[{ value: 'eu', label: 'Europe' }, { value: 'us', label: 'United States' }]} />
|
|
553
|
+
</Field>
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
## Accessibility
|
|
557
|
+
- role="radiogroup" with role="radio" buttons; one tab stop on the checked (or first) radio; Arrow keys move and check, skipping disabled.
|
|
558
|
+
|
|
559
|
+
## DOM contract (for agents operating the page)
|
|
560
|
+
|
|
561
|
+
- Selector: `[data-sw="radio-group"]`
|
|
562
|
+
- `aria-checked`: on each [data-sw="radio"]
|
|
563
|
+
- `data-value`: value of each radio
|
|
564
|
+
- How to operate: Click the [data-sw="radio"] whose label matches. Agent bridge: setValue(value) / select(value); items = options.
|
|
565
|
+
|
|
566
|
+
Related: `segmented-control`, `listbox`, `checkbox`
|
|
567
|
+
|
|
568
|
+
---
|
|
569
|
+
|
|
570
|
+
# Slider
|
|
571
|
+
|
|
572
|
+
> Pick a number or a range by dragging or with the keyboard. Steps, marks, Intl-formatted value and onValueCommit for saving.
|
|
573
|
+
|
|
574
|
+
Category: inputs · Status: beta · Slug: `slider`
|
|
575
|
+
|
|
576
|
+
```tsx
|
|
577
|
+
import { Slider } from '@peerproblem/sw3-ui'
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
## When to use
|
|
581
|
+
- Approximate values where position matters more than the exact number (temperature, volume, budget range).
|
|
582
|
+
- A min–max range filter: `defaultValue={[20, 80]}`.
|
|
583
|
+
|
|
584
|
+
## Avoid
|
|
585
|
+
- Exact numbers people type — use NumberInput.
|
|
586
|
+
- Saving on every drag step — use `onValueCommit`.
|
|
587
|
+
- Huge ranges with tiny steps — use NumberInput or add marks.
|
|
588
|
+
|
|
589
|
+
## Props
|
|
590
|
+
|
|
591
|
+
| Prop | Type | Default | Description |
|
|
592
|
+
| --- | --- | --- | --- |
|
|
593
|
+
| `value` | `number \| [number, number]` | | Controlled value; a tuple makes a range with two thumbs. |
|
|
594
|
+
| `defaultValue` | `number \| [number, number]` | `min` | Initial value. |
|
|
595
|
+
| `onValueChange` | `(value) => void` | | Every step of a drag or key press. |
|
|
596
|
+
| `onValueCommit` | `(value) => void` | | Once when the drag or key press ends. |
|
|
597
|
+
| `min / max / step` | `number` | `0 / 100 / 1` | Bounds and step. |
|
|
598
|
+
| `largeStep` | `number` | `10 × step` | PageUp/PageDown and Shift+Arrow. |
|
|
599
|
+
| `minStepsBetweenThumbs` | `number` | `0` | Range: minimum gap in steps. |
|
|
600
|
+
| `label` | `ReactNode` | | Label above the track (or use Field). |
|
|
601
|
+
| `showValue` | `boolean` | `!!label` | Show the formatted value at the top right. |
|
|
602
|
+
| `marks` | `Array<number \| { value, label? }>` | | Ticks; labelled ones show text under the track. |
|
|
603
|
+
| `formatOptions` | `Intl.NumberFormatOptions` | | Value text, e.g. `{ style: "currency", currency: "USD" }`. Percent = position in the range. |
|
|
604
|
+
| `locale` | `string` | | Formatting locale (default: page lang after mount). |
|
|
605
|
+
| `thumbLabels` | `[string, string]` | `['Minimum', 'Maximum']` | Range thumb names. |
|
|
606
|
+
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical grows upward. |
|
|
607
|
+
| `name` | `string` | | Form name; submits the number (range "start/end"). |
|
|
608
|
+
| `disabled / readOnly` | `boolean` | | States. |
|
|
609
|
+
| `size` | `'sm' \| 'md'` | `'md'` | Thumb 16 / 20px. |
|
|
610
|
+
| `aria-label` | `string` | | Name when there is no label/Field. |
|
|
611
|
+
|
|
612
|
+
## Examples
|
|
613
|
+
|
|
614
|
+
### Single
|
|
615
|
+
|
|
616
|
+
```tsx
|
|
617
|
+
<Slider label="Temperature" defaultValue={0.7} min={0} max={2} step={0.1} />
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
### Range with currency
|
|
621
|
+
|
|
622
|
+
```tsx
|
|
623
|
+
<Slider label="Monthly budget" defaultValue={[200, 800]} min={0} max={1000} step={50}
|
|
624
|
+
formatOptions={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }} onValueCommit={save} />
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
### Marks
|
|
628
|
+
|
|
629
|
+
```tsx
|
|
630
|
+
<Slider aria-label="Reasoning effort" defaultValue={2} min={1} max={3}
|
|
631
|
+
marks={[{ value: 1, label: 'Low' }, { value: 2, label: 'Med' }, { value: 3, label: 'High' }]} />
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
## Rules
|
|
635
|
+
- Always show the value (label + showValue) when the exact number matters.
|
|
636
|
+
|
|
637
|
+
## Accessibility
|
|
638
|
+
- Each thumb is role="slider" with aria-valuenow/min/max/valuetext. Arrows ±step, Shift/PageUp/PageDown ±largeStep, Home/End to the ends. The root is role="group".
|
|
639
|
+
|
|
640
|
+
## DOM contract (for agents operating the page)
|
|
641
|
+
|
|
642
|
+
- Selector: `[data-sw="slider"]`
|
|
643
|
+
- `aria-valuenow`: on each [data-sw="slider-thumb"]
|
|
644
|
+
- `data-range`: present for two thumbs
|
|
645
|
+
- `data-dragging`: present while dragging
|
|
646
|
+
- How to operate: Focus a [data-sw="slider-thumb"] and press arrow keys, or click the track. Agent bridge: setValue(number | [a, b]), increment(), decrement().
|
|
647
|
+
|
|
648
|
+
Related: `number-input`, `field`
|
|
649
|
+
|
|
650
|
+
---
|
|
651
|
+
|
|
652
|
+
# NumberInput
|
|
653
|
+
|
|
654
|
+
> A number field with − / + steppers, min/max/step snapping, Intl formatting (currency, percent, units) and spinbutton keys.
|
|
655
|
+
|
|
656
|
+
Category: inputs · Status: beta · Slug: `number-input`
|
|
657
|
+
|
|
658
|
+
```tsx
|
|
659
|
+
import { NumberInput } from '@peerproblem/sw3-ui'
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
## When to use
|
|
663
|
+
- Exact numbers: quantities, seats, limits, prices, timeouts.
|
|
664
|
+
- Values with units or currency shown while typing.
|
|
665
|
+
|
|
666
|
+
## Avoid
|
|
667
|
+
- `<Input type="number">` — it can’t format and its spinners are tiny.
|
|
668
|
+
- Approximate values — use Slider.
|
|
669
|
+
- Phone numbers, codes or ids — use Input / OTPInput.
|
|
670
|
+
|
|
671
|
+
## Props
|
|
672
|
+
|
|
673
|
+
| Prop | Type | Default | Description |
|
|
674
|
+
| --- | --- | --- | --- |
|
|
675
|
+
| `value` | `number \| null` | | Controlled value; null = empty. |
|
|
676
|
+
| `defaultValue` | `number \| null` | `null` | Initial value. |
|
|
677
|
+
| `onValueChange` | `(value: number \| null) => void` | | While typing (once valid) and on each step. |
|
|
678
|
+
| `onValueCommit` | `(value: number \| null) => void` | | On blur/Enter and when a key or button is released. |
|
|
679
|
+
| `min / max` | `number` | | Bounds; typed values clamp on commit. |
|
|
680
|
+
| `step` | `number` | `1` | Arrow/button step; committed values snap to it. |
|
|
681
|
+
| `largeStep / smallStep` | `number` | `10 × step / step ÷ 10` | Shift or PageUp/Down / Alt+Arrow. |
|
|
682
|
+
| `formatOptions` | `Intl.NumberFormatOptions` | | Display format. Percent values are fractions (0.25 = 25%). |
|
|
683
|
+
| `locale` | `string` | | Formatting/parsing locale. |
|
|
684
|
+
| `wheel` | `boolean` | `false` | Mouse wheel steps while focused. |
|
|
685
|
+
| `stepper` | `boolean` | `true` | Show − / + buttons. |
|
|
686
|
+
| `name` | `string` | | Submits the raw number (unformatted). |
|
|
687
|
+
| `incrementLabel / decrementLabel` | `string` | `'Increase' / 'Decrease'` | Button names. |
|
|
688
|
+
| `label` | `ReactNode` | | Visible label. Inside `<Field>`, give the label to the Field instead. |
|
|
689
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
690
|
+
| `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
|
|
691
|
+
| `invalid` | `boolean` | | Invalid without a message (a surrounding Field sets it too). |
|
|
692
|
+
| `disabled / required / readOnly` | `boolean` | | Native states. Inherit from a surrounding Field. |
|
|
693
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
694
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| number` | `'sm'` | Squircle corner radius of the field frame. |
|
|
695
|
+
|
|
696
|
+
## Examples
|
|
697
|
+
|
|
698
|
+
### Seats
|
|
699
|
+
|
|
700
|
+
```tsx
|
|
701
|
+
<NumberInput label="Seats" defaultValue={5} min={1} max={500} />
|
|
702
|
+
```
|
|
703
|
+
|
|
704
|
+
### Currency
|
|
705
|
+
|
|
706
|
+
```tsx
|
|
707
|
+
<NumberInput label="Spend limit" value={limit} onValueChange={setLimit} min={0} step={10}
|
|
708
|
+
formatOptions={{ style: 'currency', currency: 'USD' }} />
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
### Percent in a Field
|
|
712
|
+
|
|
713
|
+
```tsx
|
|
714
|
+
<Field label="Sampling rate" description="Share of traffic to trace.">
|
|
715
|
+
<NumberInput defaultValue={0.25} min={0} max={1} step={0.05} formatOptions={{ style: 'percent' }} />
|
|
716
|
+
</Field>
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
## Rules
|
|
720
|
+
- Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
|
|
721
|
+
|
|
722
|
+
## Accessibility
|
|
723
|
+
- Native text input with role="spinbutton" (aria-valuenow/min/max/valuetext). ArrowUp/Down step, Shift ×10, Alt ÷10, PageUp/Down, Home/End to min/max, Enter commits. Step buttons are out of the tab order and point at the input with aria-controls.
|
|
724
|
+
|
|
725
|
+
## DOM contract (for agents operating the page)
|
|
726
|
+
|
|
727
|
+
- Selector: `[data-sw="number-input"] input[role="spinbutton"]`
|
|
728
|
+
- `aria-valuenow`: current number (absent when empty)
|
|
729
|
+
- `aria-valuetext`: formatted text
|
|
730
|
+
- How to operate: Type a number then blur/Enter, or press [data-sw="number-input-increment"] / [data-sw="number-input-decrement"]. Agent bridge: setValue(n | null), increment(), decrement(), clear().
|
|
731
|
+
|
|
732
|
+
Related: `slider`, `input`, `field`
|
|
733
|
+
|
|
734
|
+
---
|
|
735
|
+
|
|
736
|
+
# PasswordInput
|
|
737
|
+
|
|
738
|
+
> A password field with an eye / eye-off reveal toggle and a Caps Lock hint. Hides again when its form submits.
|
|
739
|
+
|
|
740
|
+
Category: inputs · Status: beta · Slug: `password-input`
|
|
741
|
+
|
|
742
|
+
```tsx
|
|
743
|
+
import { PasswordInput } from '@peerproblem/sw3-ui'
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
## When to use
|
|
747
|
+
- Sign-in and sign-up passwords, API secrets and tokens people paste.
|
|
748
|
+
|
|
749
|
+
## Avoid
|
|
750
|
+
- `<Input type="password">` — no reveal toggle.
|
|
751
|
+
- Showing a secret by default — use `defaultVisible` only for generated values the user must copy.
|
|
752
|
+
- Wrong autoComplete: use `new-password` on sign-up so managers offer a strong one.
|
|
753
|
+
|
|
754
|
+
## Props
|
|
755
|
+
|
|
756
|
+
| Prop | Type | Default | Description |
|
|
757
|
+
| --- | --- | --- | --- |
|
|
758
|
+
| `onValueChange` | `(value: string) => void` | | Called with the text on each change (value/defaultValue/onChange also work). |
|
|
759
|
+
| `visible` | `boolean` | | Controlled reveal state. |
|
|
760
|
+
| `defaultVisible` | `boolean` | `false` | Initial reveal state. |
|
|
761
|
+
| `onVisibleChange` | `(visible: boolean) => void` | | Called when the toggle (or a form submit) shows/hides. |
|
|
762
|
+
| `autoComplete` | `'current-password' \| 'new-password' \| 'off' \| string` | `'current-password'` | Password-manager hint. |
|
|
763
|
+
| `toggleLabel` | `string` | `'Show password'` | Accessible name of the reveal button (state is aria-pressed). |
|
|
764
|
+
| `prefix` | `ReactNode` | | Icon before the text. |
|
|
765
|
+
| `label` | `ReactNode` | | Visible label. Inside `<Field>`, give the label to the Field instead. |
|
|
766
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
767
|
+
| `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
|
|
768
|
+
| `invalid` | `boolean` | | Invalid without a message (a surrounding Field sets it too). |
|
|
769
|
+
| `disabled / required / readOnly` | `boolean` | | Native states. Inherit from a surrounding Field. |
|
|
770
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
771
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| number` | `'sm'` | Squircle corner radius of the field frame. |
|
|
772
|
+
|
|
773
|
+
## Examples
|
|
774
|
+
|
|
775
|
+
### Sign in
|
|
776
|
+
|
|
777
|
+
```tsx
|
|
778
|
+
<PasswordInput label="Password" name="password" required />
|
|
779
|
+
```
|
|
780
|
+
|
|
781
|
+
### New password
|
|
782
|
+
|
|
783
|
+
```tsx
|
|
784
|
+
<Field label="New password" description="At least 12 characters.">
|
|
785
|
+
<PasswordInput autoComplete="new-password" minLength={12} />
|
|
786
|
+
</Field>
|
|
787
|
+
```
|
|
788
|
+
|
|
789
|
+
## Rules
|
|
790
|
+
- Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
|
|
791
|
+
|
|
792
|
+
## Accessibility
|
|
793
|
+
- Toggle is a <button aria-pressed> with aria-controls; it does not steal focus from the input. Caps Lock state is data-capslock on the root.
|
|
794
|
+
|
|
795
|
+
## DOM contract (for agents operating the page)
|
|
796
|
+
|
|
797
|
+
- Selector: `[data-sw="password-input"] input`
|
|
798
|
+
- `data-visible`: present while shown (on root)
|
|
799
|
+
- `data-capslock`: present while Caps Lock is on
|
|
800
|
+
- How to operate: Type into the input; click [data-sw="password-input-toggle"] to reveal. Agent bridge (secret, value hidden): setValue(text), clear(), toggle().
|
|
801
|
+
|
|
802
|
+
Related: `input`, `field`
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
# OTPInput
|
|
807
|
+
|
|
808
|
+
> One-time-code entry: N squircle boxes backed by one real input, so paste fills every box and phones autofill the code from a message.
|
|
809
|
+
|
|
810
|
+
Category: inputs · Status: beta · Slug: `otp-input`
|
|
811
|
+
|
|
812
|
+
```tsx
|
|
813
|
+
import { OTPInput } from '@peerproblem/sw3-ui'
|
|
814
|
+
```
|
|
815
|
+
|
|
816
|
+
## When to use
|
|
817
|
+
- Verification codes from email/SMS/authenticator apps (4–8 characters).
|
|
818
|
+
- Verify on the last character: `onComplete`.
|
|
819
|
+
|
|
820
|
+
## Avoid
|
|
821
|
+
- N separate inputs — breaks paste and autofill. This component already uses one input.
|
|
822
|
+
- Long or free-form codes — use Input.
|
|
823
|
+
- Passwords — use PasswordInput.
|
|
824
|
+
|
|
825
|
+
## Props
|
|
826
|
+
|
|
827
|
+
| Prop | Type | Default | Description |
|
|
828
|
+
| --- | --- | --- | --- |
|
|
829
|
+
| `length` | `number` | `6` | Number of characters / boxes. |
|
|
830
|
+
| `value` | `string` | | Controlled code. |
|
|
831
|
+
| `defaultValue` | `string` | `''` | Initial code. |
|
|
832
|
+
| `onValueChange` | `(value: string) => void` | | Called on each change. |
|
|
833
|
+
| `onComplete` | `(value: string) => void` | | Called when a change fills every box. |
|
|
834
|
+
| `pattern` | `'digits' \| 'letters' \| 'alphanumeric' \| RegExp` | `'digits'` | Accepted characters; others are dropped (so "123-456" pastes as 123456). |
|
|
835
|
+
| `groupSize` | `number` | | Dash after every N boxes (3 → 123–456). |
|
|
836
|
+
| `mask` | `boolean` | `false` | Show dots instead of characters. |
|
|
837
|
+
| `autoComplete` | `string` | `'one-time-code'` | Lets phones offer the code from a message. |
|
|
838
|
+
| `name / required / disabled / readOnly / invalid / autoFocus` | `string / boolean` | | Native form behaviour. |
|
|
839
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Boxes 36×42 / 44×52 / 52×60. |
|
|
840
|
+
| `aria-label` | `string` | | Name when there is no Field label. |
|
|
841
|
+
|
|
842
|
+
## Examples
|
|
843
|
+
|
|
844
|
+
### Verify on complete
|
|
845
|
+
|
|
846
|
+
```tsx
|
|
847
|
+
<Field label="Verification code" description="We sent it to ada@example.com.">
|
|
848
|
+
<OTPInput length={6} groupSize={3} onComplete={(code) => verify(code)} autoFocus />
|
|
849
|
+
</Field>
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
### Alphanumeric
|
|
853
|
+
|
|
854
|
+
```tsx
|
|
855
|
+
<OTPInput aria-label="Recovery code" length={8} pattern="alphanumeric" groupSize={4} />
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
## Rules
|
|
859
|
+
- Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
|
|
860
|
+
- Clear the value and set `invalid` (or Field `error`) when verification fails; don’t disable the input.
|
|
861
|
+
|
|
862
|
+
## Accessibility
|
|
863
|
+
- Screen readers see one text input with the whole code; the boxes are aria-hidden. Backspace deletes, paste fills.
|
|
864
|
+
|
|
865
|
+
## DOM contract (for agents operating the page)
|
|
866
|
+
|
|
867
|
+
- Selector: `[data-sw="otp-input"]`
|
|
868
|
+
- `data-state`: complete | incomplete
|
|
869
|
+
- `data-invalid`: present when invalid
|
|
870
|
+
- How to operate: Type or paste the code into [data-sw="otp-input-control"]. Agent bridge (secret, value hidden): setValue(code), clear().
|
|
871
|
+
|
|
872
|
+
Related: `input`, `field`
|
|
873
|
+
|
|
874
|
+
---
|
|
875
|
+
|
|
876
|
+
# Rating
|
|
877
|
+
|
|
878
|
+
> Star rating: a radio group of scores with hover preview, half steps, keyboard, and a read-only mode that shows any fraction.
|
|
879
|
+
|
|
880
|
+
Category: inputs · Status: beta · Slug: `rating`
|
|
881
|
+
|
|
882
|
+
```tsx
|
|
883
|
+
import { Rating } from '@peerproblem/sw3-ui'
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
## When to use
|
|
887
|
+
- Rating an answer, run or product (1–5).
|
|
888
|
+
- Showing an average score: `readOnly value={4.3}`.
|
|
889
|
+
|
|
890
|
+
## Avoid
|
|
891
|
+
- Binary feedback — use two Toggles (thumbs up/down).
|
|
892
|
+
- More than 10 stars — use Slider.
|
|
893
|
+
|
|
894
|
+
## Props
|
|
895
|
+
|
|
896
|
+
| Prop | Type | Default | Description |
|
|
897
|
+
| --- | --- | --- | --- |
|
|
898
|
+
| `value` | `number \| null` | | Controlled score; null = unrated. |
|
|
899
|
+
| `defaultValue` | `number \| null` | `null` | Initial score. |
|
|
900
|
+
| `onValueChange` | `(value: number \| null) => void` | | Called on click or arrow key. |
|
|
901
|
+
| `max` | `number` | `5` | Number of stars. |
|
|
902
|
+
| `step` | `1 \| 0.5` | `1` | 0.5 allows half stars. |
|
|
903
|
+
| `deselectable` | `boolean` | `false` | Pressing the checked star clears it. |
|
|
904
|
+
| `readOnly` | `boolean` | `false` | Image of the score (role="img"); fractions show. |
|
|
905
|
+
| `disabled / required / loop` | `boolean` | | States; loop wraps arrow keys. |
|
|
906
|
+
| `name` | `string` | | Submits the score. |
|
|
907
|
+
| `getValueLabel` | `(value, max) => string` | | Name of each score. Default "3 stars". |
|
|
908
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Stars 18 / 24 / 32px. |
|
|
909
|
+
| `aria-label` | `string` | | Name of the group. |
|
|
910
|
+
|
|
911
|
+
## Examples
|
|
912
|
+
|
|
913
|
+
### Rate an answer
|
|
914
|
+
|
|
915
|
+
```tsx
|
|
916
|
+
<Rating aria-label="Rate this answer" value={score} onValueChange={setScore} deselectable />
|
|
917
|
+
```
|
|
918
|
+
|
|
919
|
+
### Half stars
|
|
920
|
+
|
|
921
|
+
```tsx
|
|
922
|
+
<Rating aria-label="Quality" step={0.5} defaultValue={3.5} />
|
|
923
|
+
```
|
|
924
|
+
|
|
925
|
+
### Average
|
|
926
|
+
|
|
927
|
+
```tsx
|
|
928
|
+
<Rating aria-label="Average rating" readOnly value={4.3} size="sm" />
|
|
929
|
+
```
|
|
930
|
+
|
|
931
|
+
## Accessibility
|
|
932
|
+
- role="radiogroup" with one role="radio" per score (two per star with halves); one tab stop; Arrow keys move and check; Space checks (or clears when deselectable).
|
|
933
|
+
|
|
934
|
+
## DOM contract (for agents operating the page)
|
|
935
|
+
|
|
936
|
+
- Selector: `[data-sw="rating"]`
|
|
937
|
+
- `aria-checked`: on the chosen [data-score] radio
|
|
938
|
+
- `data-state`: full | partial | empty on each [data-sw="rating-item"]
|
|
939
|
+
- How to operate: Click the button with data-score="N". Agent bridge: setValue(n | null), clear().
|
|
940
|
+
|
|
941
|
+
Related: `slider`, `toggle`
|
|
942
|
+
|
|
943
|
+
---
|
|
944
|
+
|
|
945
|
+
# Select
|
|
946
|
+
|
|
947
|
+
> Pick one or several options from a popup list, with groups, optional search inside the dropdown, and a native form value.
|
|
948
|
+
|
|
949
|
+
Category: selection · Status: beta · Slug: `select`
|
|
950
|
+
|
|
951
|
+
```tsx
|
|
952
|
+
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectSeparator } from '@peerproblem/sw3-ui'
|
|
953
|
+
```
|
|
954
|
+
|
|
955
|
+
## When to use
|
|
956
|
+
- Choosing from known options such as models, regions, or roles.
|
|
957
|
+
- Use `searchable` when search belongs inside the dropdown and the closed trigger should show the selected value.
|
|
958
|
+
- Inside forms: pass `name` and it submits like a native select.
|
|
959
|
+
|
|
960
|
+
## Avoid
|
|
961
|
+
- Search that starts in the field itself, or server-filtered options — use Combobox.
|
|
962
|
+
- 2–4 options always visible — use SegmentedControl or a Radio group.
|
|
963
|
+
- Running actions — use Menu.
|
|
964
|
+
- Free text — use Autocomplete or Input.
|
|
965
|
+
|
|
966
|
+
## Props
|
|
967
|
+
|
|
968
|
+
| Prop | Type | Default | Description |
|
|
969
|
+
| --- | --- | --- | --- |
|
|
970
|
+
| `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 `<SelectItem>` children instead. |
|
|
971
|
+
| `value / defaultValue / onValueChange` | `string \| null (string[] with multiple)` | | Selected value(s). `onValueChange(null)` when cleared. |
|
|
972
|
+
| `multiple` | `boolean` | `false` | Pick several; the list stays open while toggling; the trigger shows "A, B +2". |
|
|
973
|
+
| `searchable` | `boolean` | `false` | Show a search input inside the dropdown. Filters option labels and keywords and clears the query when closed. |
|
|
974
|
+
| `searchPlaceholder / searchLabel` | `string / string` | `"Search options…" / "Search options"` | Search input placeholder and accessible name. |
|
|
975
|
+
| `placeholder` | `string` | | Shown while nothing is selected. |
|
|
976
|
+
| `label` | `ReactNode` | | Visible label above the trigger (leave out inside Field). |
|
|
977
|
+
| `open / defaultOpen / onOpenChange` | `boolean` | | Popup state. |
|
|
978
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field heights 32 / 40 / 52px, like Input. |
|
|
979
|
+
| `name` | `string` | | Native form field name; the value submits through hidden inputs (one per value when multiple). |
|
|
980
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. Inherit from a surrounding `<Field>`. |
|
|
981
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label or Field. |
|
|
982
|
+
| `form` | `string` | | Id of a form the hidden inputs belong to. |
|
|
983
|
+
| `SelectItem: value, label?, disabled?, icon?, description?` | `props` | | `label` is what the trigger shows when children are not plain text. |
|
|
984
|
+
| `SelectGroup: label` | `ReactNode` | | Heading of a group of SelectItems. |
|
|
985
|
+
| `SelectTrigger: asChild?, icon?` | `props` | | Customise the trigger (leading icon) or clone your own element. |
|
|
986
|
+
| `SelectValue: placeholder?, maxLabels?` | `props` | | What the trigger shows. `maxLabels` (default 2) before "+N". |
|
|
987
|
+
| `SelectContent: placement?, emptyMessage?` | `props` | | Popup placement (default bottom-start, matches trigger width). |
|
|
988
|
+
|
|
989
|
+
## Anatomy
|
|
990
|
+
|
|
991
|
+
```
|
|
992
|
+
Select
|
|
993
|
+
├─ trigger shows the value, opens the popup
|
|
994
|
+
└─ popup PopupPanel
|
|
995
|
+
├─ search optional
|
|
996
|
+
└─ list groups and items
|
|
997
|
+
```
|
|
998
|
+
|
|
999
|
+
Built from: `PopupPanel (usePopup)`, `useListNavigation`, `useSquircle`.
|
|
1000
|
+
|
|
1001
|
+
## Examples
|
|
1002
|
+
|
|
1003
|
+
### One line with items
|
|
1004
|
+
|
|
1005
|
+
```tsx
|
|
1006
|
+
<Select
|
|
1007
|
+
label="Model"
|
|
1008
|
+
name="model"
|
|
1009
|
+
placeholder="Choose a model"
|
|
1010
|
+
defaultValue="sonnet"
|
|
1011
|
+
items={[
|
|
1012
|
+
{ value: 'opus', label: 'Opus', description: 'Most capable' },
|
|
1013
|
+
{ value: 'sonnet', label: 'Sonnet' },
|
|
1014
|
+
{ value: 'haiku', label: 'Haiku' },
|
|
1015
|
+
]}
|
|
1016
|
+
/>
|
|
1017
|
+
```
|
|
1018
|
+
|
|
1019
|
+
### Search inside the dropdown
|
|
1020
|
+
|
|
1021
|
+
```tsx
|
|
1022
|
+
<Select label="Model" searchable searchLabel="Search models" searchPlaceholder="Search models…" items={[
|
|
1023
|
+
{ value: 'opus', label: 'Opus' },
|
|
1024
|
+
{ value: 'sonnet', label: 'Sonnet' },
|
|
1025
|
+
{ value: 'haiku', label: 'Haiku' },
|
|
1026
|
+
]} />
|
|
1027
|
+
```
|
|
1028
|
+
|
|
1029
|
+
### Children with groups
|
|
1030
|
+
|
|
1031
|
+
```tsx
|
|
1032
|
+
<Select aria-label="Region" value={region} onValueChange={setRegion} placeholder="Region">
|
|
1033
|
+
<SelectGroup label="Europe">
|
|
1034
|
+
<SelectItem value="fra">Frankfurt</SelectItem>
|
|
1035
|
+
<SelectItem value="hel">Helsinki</SelectItem>
|
|
1036
|
+
</SelectGroup>
|
|
1037
|
+
<SelectSeparator />
|
|
1038
|
+
<SelectItem value="iad">Washington, D.C.</SelectItem>
|
|
1039
|
+
</Select>
|
|
1040
|
+
```
|
|
1041
|
+
|
|
1042
|
+
### Multiple inside a Field
|
|
1043
|
+
|
|
1044
|
+
```tsx
|
|
1045
|
+
<Field label="Notify on">
|
|
1046
|
+
<Select multiple name="events" defaultValue={['fail']} items={[
|
|
1047
|
+
{ value: 'start', label: 'Run started' },
|
|
1048
|
+
{ value: 'fail', label: 'Run failed' },
|
|
1049
|
+
{ value: 'done', label: 'Run finished' },
|
|
1050
|
+
]} />
|
|
1051
|
+
</Field>
|
|
1052
|
+
```
|
|
1053
|
+
|
|
1054
|
+
## Rules
|
|
1055
|
+
- Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
|
|
1056
|
+
- Option labels are nouns in sentence case; keep them short so the trigger never truncates.
|
|
1057
|
+
- Always give a placeholder or a default value.
|
|
1058
|
+
|
|
1059
|
+
## Accessibility
|
|
1060
|
+
- By default the trigger is a select-only combobox and keeps focus while the list is open. Arrow keys move, Home/End jump, typing jumps by label, and Enter/Space choose.
|
|
1061
|
+
- In searchable mode a button opens a dialog with an editable combobox and a listbox. Focus moves to the search input. ArrowUp/ArrowDown move through enabled results and Enter chooses. Escape returns focus to the trigger. Tab or Shift+Tab closes and continues from the trigger.
|
|
1062
|
+
|
|
1063
|
+
## DOM contract (for agents operating the page)
|
|
1064
|
+
|
|
1065
|
+
- Selector: `[data-sw="select"]`
|
|
1066
|
+
- `aria-expanded`: true while the list is open (on the trigger / input)
|
|
1067
|
+
- `aria-activedescendant`: id of the highlighted option while open
|
|
1068
|
+
- `aria-selected`: on each [role=option]: whether it is chosen
|
|
1069
|
+
- `data-value`: on each option: its value
|
|
1070
|
+
- `data-state`: root: 'open' | 'closed'
|
|
1071
|
+
- `data-disabled / data-invalid`: present when disabled / invalid
|
|
1072
|
+
- How to operate: Click [data-sw="select-trigger"], optionally type into [data-sw="select-search"], then choose an enabled [role=option]. The popup [data-sw="select-content"] is portaled. Agent bridge: setValue(value | value[] | null), select(value), clear(), open(), close(). Use option IDs or unique full labels. Null clears the selection.
|
|
1073
|
+
|
|
1074
|
+
Related: `combobox`, `listbox`, `segmented-control`, `field`
|
|
1075
|
+
|
|
1076
|
+
---
|
|
1077
|
+
|
|
1078
|
+
# Listbox
|
|
1079
|
+
|
|
1080
|
+
> An always-visible framed list to pick one or several options, with one tab stop and full keyboard support.
|
|
1081
|
+
|
|
1082
|
+
Category: selection · Status: beta · Slug: `listbox`
|
|
1083
|
+
|
|
1084
|
+
```tsx
|
|
1085
|
+
import { Listbox, ListboxItem, ListboxGroup, ListboxSeparator } from '@peerproblem/sw3-ui'
|
|
1086
|
+
```
|
|
1087
|
+
|
|
1088
|
+
## When to use
|
|
1089
|
+
- Picking from a list that should stay visible (sidebar of files, a picker inside a dialog).
|
|
1090
|
+
- Multi-select of a short list where seeing every option matters.
|
|
1091
|
+
|
|
1092
|
+
## Avoid
|
|
1093
|
+
- Saving space — use Select (popup).
|
|
1094
|
+
- Searching many items — use Combobox or Command.
|
|
1095
|
+
- Rich rows with buttons inside — use a list of Cards or a table.
|
|
1096
|
+
|
|
1097
|
+
## Props
|
|
1098
|
+
|
|
1099
|
+
| Prop | Type | Default | Description |
|
|
1100
|
+
| --- | --- | --- | --- |
|
|
1101
|
+
| `items[].meta` | `ReactNode` | | Quiet trailing text (time, count) that gives its place to the actions on hover. |
|
|
1102
|
+
| `items[].actions / items[].menu` | `{ label; icon?; onSelect; destructive?; disabled? }[]` | | Row actions as data. The SDK renders 24px ghost Buttons with tooltips, centred on the row, plus a ⋯ menu. A reorderable list adds Move to top/up/down to that menu. Actions are always shown on touch. |
|
|
1103
|
+
| `framed` | `boolean` | | Default: true on its own (capped at 320px), false inside a Card or Accordion. Unframed, rows sit 6px from the container edge and their content starts on its 12px line. |
|
|
1104
|
+
| `--sw-listbox-max-height` | `CSS length \| none` | `320px framed, none unframed` | Set on an ancestor to change when the list scrolls. `none` never scrolls; a length scrolls inside with the slim scrollbar and keeps the focused row in view. |
|
|
1105
|
+
| `descriptionLayout` | `'below' \| 'inline'` | `'below'` | inline puts the description after the label, for dense data rows. |
|
|
1106
|
+
| `onItemAction` | `(value) => void` | | Enter or double-click: open or drill in. |
|
|
1107
|
+
| `onReorder / reorderable / handle` | `(values, { id, from, to }) => void / boolean / 'hover' \| 'always' \| 'none'` | | Rows drag from their body with a mouse (after 5px) and from the grip by touch, with a drop line and preview. Alt+↑/↓ and the ⋯ menu's Move items also reorder. The 'hover' grip swaps with the row icon. Pass `useListQuery().reorderable` so reordering stops while searching or sorted. |
|
|
1108
|
+
| `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 `<ListboxItem>` children instead. |
|
|
1109
|
+
| `value / defaultValue / onValueChange` | `string \| null (string[] with multiple)` | | Selected value(s). |
|
|
1110
|
+
| `multiple` | `boolean` | `false` | Pick several; Ctrl/⌘+A selects all. |
|
|
1111
|
+
| `activation` | `'automatic' \| 'manual'` | `'automatic' (single), 'manual' (multiple)` | Whether arrow keys select as they move, or only Enter/Space/click selects. |
|
|
1112
|
+
| `deselectable` | `boolean` | `false` | Single: pressing the selected item clears it. |
|
|
1113
|
+
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Which arrow keys move. |
|
|
1114
|
+
| `loop` | `boolean` | `true` | Arrow keys wrap. |
|
|
1115
|
+
| `emptyMessage` | `ReactNode` | `"No options"` | Shown with no options. |
|
|
1116
|
+
| `name` | `string` | | Native form field name; the value submits through hidden inputs (one per value when multiple). |
|
|
1117
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. Inherit from a surrounding `<Field>`. |
|
|
1118
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label or Field. |
|
|
1119
|
+
|
|
1120
|
+
## Examples
|
|
1121
|
+
|
|
1122
|
+
### Single
|
|
1123
|
+
|
|
1124
|
+
```tsx
|
|
1125
|
+
<Listbox aria-label="Environment" defaultValue="staging" items={[
|
|
1126
|
+
{ value: 'prod', label: 'Production' },
|
|
1127
|
+
{ value: 'staging', label: 'Staging' },
|
|
1128
|
+
{ value: 'dev', label: 'Development' },
|
|
1129
|
+
]} />
|
|
1130
|
+
```
|
|
1131
|
+
|
|
1132
|
+
### Multiple with children
|
|
1133
|
+
|
|
1134
|
+
```tsx
|
|
1135
|
+
<Listbox multiple aria-label="Tools" value={tools} onValueChange={setTools}>
|
|
1136
|
+
<ListboxItem value="search">Web search</ListboxItem>
|
|
1137
|
+
<ListboxItem value="code">Code execution</ListboxItem>
|
|
1138
|
+
<ListboxItem value="files" disabled>File system</ListboxItem>
|
|
1139
|
+
</Listbox>
|
|
1140
|
+
```
|
|
1141
|
+
|
|
1142
|
+
## Rules
|
|
1143
|
+
- Row height follows the density preference (`data-density`: compact 28, comfortable 32, spacious 40). Do not set heights per list.
|
|
1144
|
+
- Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
|
|
1145
|
+
- It grows with its options up to 320px, then scrolls inside its frame.
|
|
1146
|
+
- Chosen options use the neutral selected fill and 500-weight labels. Multi-select adds a trailing check so several choices remain easy to scan. Pointer and keyboard highlight one active row at a time.
|
|
1147
|
+
|
|
1148
|
+
## Accessibility
|
|
1149
|
+
- role="listbox" (one tab stop) with aria-activedescendant; options role="option" + aria-selected; aria-multiselectable with multiple.
|
|
1150
|
+
- Arrows move, Home/End jump, typing jumps by label, Enter/Space select.
|
|
1151
|
+
|
|
1152
|
+
## DOM contract (for agents operating the page)
|
|
1153
|
+
|
|
1154
|
+
- Selector: `[data-sw="listbox"]`
|
|
1155
|
+
- `aria-selected`: on each [role=option]
|
|
1156
|
+
- `data-value`: on each option
|
|
1157
|
+
- `aria-activedescendant`: highlighted option id
|
|
1158
|
+
- `data-disabled`: present when disabled
|
|
1159
|
+
- How to operate: Click an option ([data-sw="listbox-item"]). Agent bridge: setValue(value | value[]), select(value) (toggles with multiple), clear(); items = options.
|
|
1160
|
+
|
|
1161
|
+
Related: `select`, `combobox`, `radio`
|
|
1162
|
+
|
|
1163
|
+
---
|
|
1164
|
+
|
|
1165
|
+
# Combobox
|
|
1166
|
+
|
|
1167
|
+
> A searchable select: type to filter a popup list and pick one value, or several shown as chips. Async-friendly.
|
|
1168
|
+
|
|
1169
|
+
Category: selection · Status: beta · Slug: `combobox`
|
|
1170
|
+
|
|
1171
|
+
```tsx
|
|
1172
|
+
import { Combobox, ComboboxItem, ComboboxGroup } from '@peerproblem/sw3-ui'
|
|
1173
|
+
```
|
|
1174
|
+
|
|
1175
|
+
## When to use
|
|
1176
|
+
- Choosing from many options (users, repos, countries) where typing is faster than scrolling.
|
|
1177
|
+
- Several values as chips (`multiple`): labels, reviewers.
|
|
1178
|
+
- Server search: `onInputChange` + `filter={false}` + `loading`.
|
|
1179
|
+
|
|
1180
|
+
## Avoid
|
|
1181
|
+
- Free text where any value is fine — use Autocomplete.
|
|
1182
|
+
- Under ~8 options — use Select.
|
|
1183
|
+
- Running commands — use Command.
|
|
1184
|
+
|
|
1185
|
+
## Props
|
|
1186
|
+
|
|
1187
|
+
| Prop | Type | Default | Description |
|
|
1188
|
+
| --- | --- | --- | --- |
|
|
1189
|
+
| `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. |
|
|
1190
|
+
| `value / defaultValue / onValueChange` | `string \| null (string[] with multiple)` | | Selected value(s). |
|
|
1191
|
+
| `multiple` | `boolean` | `false` | Pick several; chips in the field, Backspace on empty text removes the last. |
|
|
1192
|
+
| `inputValue / defaultInputValue / onInputChange` | `string / (text) => void` | | The typed text. Use `onInputChange` to fetch results. |
|
|
1193
|
+
| `filter` | `'contains' \| 'startsWith' \| false \| (item, query) => boolean` | `'contains'` | How typing narrows the list (label + keywords). `false` for server-filtered results. |
|
|
1194
|
+
| `loading` | `boolean` | `false` | Spinner in the field, a loading row, aria-busy on the list. |
|
|
1195
|
+
| `emptyMessage` | `ReactNode` | `"No results"` | Shown when nothing matches. |
|
|
1196
|
+
| `openOnFocus` | `boolean` | `false` | Open as soon as the field is focused. |
|
|
1197
|
+
| `clearable` | `boolean` | `false` | Show a clear (✕) button while there is a value. |
|
|
1198
|
+
| `placeholder / label / icon` | `string / ReactNode / ReactNode` | | Placeholder, visible label, leading icon. |
|
|
1199
|
+
| `open / defaultOpen / onOpenChange` | `boolean` | | Popup state. |
|
|
1200
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field heights 32 / 40 / 52px, like Input. |
|
|
1201
|
+
| `name` | `string` | | Native form field name; the value submits through hidden inputs (one per value when multiple). |
|
|
1202
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. Inherit from a surrounding `<Field>`. |
|
|
1203
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label or Field. |
|
|
1204
|
+
|
|
1205
|
+
## Anatomy
|
|
1206
|
+
|
|
1207
|
+
```
|
|
1208
|
+
Combobox
|
|
1209
|
+
├─ field text input, chips when multiple, clear and chevron buttons
|
|
1210
|
+
└─ popup PopupPanel
|
|
1211
|
+
└─ list ComboboxGroup / ComboboxGroupLabel / ComboboxItem / ComboboxSeparator
|
|
1212
|
+
```
|
|
1213
|
+
|
|
1214
|
+
Built from: `PopupPanel (usePopup)`, `useListNavigation`, `useSquircle`.
|
|
1215
|
+
|
|
1216
|
+
## Examples
|
|
1217
|
+
|
|
1218
|
+
### Single
|
|
1219
|
+
|
|
1220
|
+
```tsx
|
|
1221
|
+
<Combobox label="Repository" placeholder="Search repos…" items={repos.map((r) => ({ value: r.id, label: r.name }))} onValueChange={setRepo} />
|
|
1222
|
+
```
|
|
1223
|
+
|
|
1224
|
+
### Multiple chips
|
|
1225
|
+
|
|
1226
|
+
```tsx
|
|
1227
|
+
<Combobox multiple aria-label="Reviewers" placeholder="Add reviewers" defaultValue={['ada']} items={[
|
|
1228
|
+
{ value: 'ada', label: 'Ada Lovelace' },
|
|
1229
|
+
{ value: 'grace', label: 'Grace Hopper' },
|
|
1230
|
+
{ value: 'alan', label: 'Alan Turing' },
|
|
1231
|
+
]} />
|
|
1232
|
+
```
|
|
1233
|
+
|
|
1234
|
+
### Async search
|
|
1235
|
+
|
|
1236
|
+
```tsx
|
|
1237
|
+
const [results, setResults] = useState([])
|
|
1238
|
+
const [loading, setLoading] = useState(false)
|
|
1239
|
+
<Combobox
|
|
1240
|
+
aria-label="User"
|
|
1241
|
+
filter={false}
|
|
1242
|
+
loading={loading}
|
|
1243
|
+
items={results}
|
|
1244
|
+
onInputChange={async (q) => { setLoading(true); setResults(await searchUsers(q)); setLoading(false) }}
|
|
1245
|
+
/>
|
|
1246
|
+
```
|
|
1247
|
+
|
|
1248
|
+
## Rules
|
|
1249
|
+
- Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
|
|
1250
|
+
- Keep the chosen option visible as the field text (single) or chips (multiple); never clear what the user picked on blur.
|
|
1251
|
+
|
|
1252
|
+
## Accessibility
|
|
1253
|
+
- Input role="combobox" with aria-autocomplete="list", aria-expanded, aria-controls and aria-activedescendant; focus never leaves the input.
|
|
1254
|
+
- Typing opens + filters; ArrowDown/Up open and move; Enter chooses; Escape closes; Backspace on empty text removes the last chip.
|
|
1255
|
+
|
|
1256
|
+
## DOM contract (for agents operating the page)
|
|
1257
|
+
|
|
1258
|
+
- Selector: `[data-sw="combobox"]`
|
|
1259
|
+
- `aria-expanded`: true while the list is open (on the trigger / input)
|
|
1260
|
+
- `aria-activedescendant`: id of the highlighted option while open
|
|
1261
|
+
- `aria-selected`: on each [role=option]: whether it is chosen
|
|
1262
|
+
- `data-value`: on each option: its value
|
|
1263
|
+
- `data-state`: root: 'open' | 'closed'
|
|
1264
|
+
- `data-disabled / data-invalid`: present when disabled / invalid
|
|
1265
|
+
- `[data-sw="combobox-chip"]`: one per chosen value (multiple), with data-value
|
|
1266
|
+
- 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.
|
|
1267
|
+
|
|
1268
|
+
Related: `select`, `autocomplete`, `command`
|
|
1269
|
+
|
|
1270
|
+
---
|
|
1271
|
+
|
|
1272
|
+
# Autocomplete
|
|
1273
|
+
|
|
1274
|
+
> A text field with suggestions: the value is whatever is typed, and picking a suggestion fills it in.
|
|
1275
|
+
|
|
1276
|
+
Category: selection · Status: beta · Slug: `autocomplete`
|
|
1277
|
+
|
|
1278
|
+
```tsx
|
|
1279
|
+
import { Autocomplete, AutocompleteItem } from '@peerproblem/sw3-ui'
|
|
1280
|
+
```
|
|
1281
|
+
|
|
1282
|
+
## When to use
|
|
1283
|
+
- Search boxes with suggested queries.
|
|
1284
|
+
- Free-text fields with common answers (city, tag, branch name).
|
|
1285
|
+
|
|
1286
|
+
## Avoid
|
|
1287
|
+
- The value must be one of the options — use Combobox or Select.
|
|
1288
|
+
- Many actions — use Command.
|
|
1289
|
+
|
|
1290
|
+
## Props
|
|
1291
|
+
|
|
1292
|
+
| Prop | Type | Default | Description |
|
|
1293
|
+
| --- | --- | --- | --- |
|
|
1294
|
+
| `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 `<AutocompleteItem>` children instead. |
|
|
1295
|
+
| `value / defaultValue / onValueChange` | `string / (text) => void` | | The text. |
|
|
1296
|
+
| `onItemSelect` | `(item) => void` | | Runs when a suggestion is chosen (after the text becomes its label). |
|
|
1297
|
+
| `filter` | `'contains' \| 'startsWith' \| false \| fn` | `'contains'` | How the text narrows suggestions. `false` for server results. |
|
|
1298
|
+
| `autoHighlight` | `boolean` | `false` | Highlight the first suggestion so Enter takes it. Off: Enter keeps the typed text. |
|
|
1299
|
+
| `openOnFocus` | `boolean` | `false` | Show suggestions on focus. |
|
|
1300
|
+
| `loading / emptyMessage` | `boolean / ReactNode` | | Loading row; message when nothing matches (omit to just hide the list). |
|
|
1301
|
+
| `clearable / label / icon / placeholder` | `boolean / ReactNode / ReactNode / string` | | Clear button, visible label, leading icon, placeholder. |
|
|
1302
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field heights 32 / 40 / 52px, like Input. |
|
|
1303
|
+
| `...input props` | `InputHTMLAttributes` | | `name`, `required`, `disabled`, `aria-label`… go to the native input. |
|
|
1304
|
+
|
|
1305
|
+
## Examples
|
|
1306
|
+
|
|
1307
|
+
### Search with suggestions
|
|
1308
|
+
|
|
1309
|
+
```tsx
|
|
1310
|
+
<Autocomplete aria-label="Search docs" icon={<Icon name="search" />} placeholder="Search docs…" items={[
|
|
1311
|
+
{ value: 'streaming', label: 'Streaming responses' },
|
|
1312
|
+
{ value: 'tools', label: 'Tool use' },
|
|
1313
|
+
{ value: 'caching', label: 'Prompt caching' },
|
|
1314
|
+
]} />
|
|
1315
|
+
```
|
|
1316
|
+
|
|
1317
|
+
### Children
|
|
1318
|
+
|
|
1319
|
+
```tsx
|
|
1320
|
+
<Autocomplete label="Branch" name="branch" defaultValue="main">
|
|
1321
|
+
<AutocompleteItem value="main">main</AutocompleteItem>
|
|
1322
|
+
<AutocompleteItem value="dev">dev</AutocompleteItem>
|
|
1323
|
+
</Autocomplete>
|
|
1324
|
+
```
|
|
1325
|
+
|
|
1326
|
+
## Rules
|
|
1327
|
+
- Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
|
|
1328
|
+
- Suggestions help but never restrict: any typed text is a valid value.
|
|
1329
|
+
|
|
1330
|
+
## Accessibility
|
|
1331
|
+
- Input role="combobox", aria-autocomplete="list", aria-activedescendant; ArrowDown opens/moves, Enter takes the highlighted suggestion, Escape closes (again: clears).
|
|
1332
|
+
|
|
1333
|
+
## DOM contract (for agents operating the page)
|
|
1334
|
+
|
|
1335
|
+
- Selector: `[data-sw="autocomplete"]`
|
|
1336
|
+
- `aria-expanded`: on the input while suggestions show
|
|
1337
|
+
- `data-value`: on each [role=option]
|
|
1338
|
+
- How to operate: Type into [data-sw="autocomplete-input"]; optionally click a [role=option]. Agent bridge: setValue(text), select(valueOrLabel), clear(), open(), close(); items = current suggestions.
|
|
1339
|
+
|
|
1340
|
+
Related: `combobox`, `input`, `command`
|
|
1341
|
+
|
|
1342
|
+
---
|
|
1343
|
+
|
|
1344
|
+
# Trigger Menu
|
|
1345
|
+
|
|
1346
|
+
> Suggestions at the caret when a trigger like @, / or # is typed in a textarea, input or Token Input; inserts the chosen item.
|
|
1347
|
+
|
|
1348
|
+
Category: inputs · Status: beta · Slug: `trigger-menu`
|
|
1349
|
+
|
|
1350
|
+
```tsx
|
|
1351
|
+
import { TriggerMenu, TriggerMenuInput } from '@peerproblem/sw3-ui'
|
|
1352
|
+
```
|
|
1353
|
+
|
|
1354
|
+
## When to use
|
|
1355
|
+
- @mentions, /commands and #tags inside a message or prompt box.
|
|
1356
|
+
- Inside a `<TokenInput>` to insert chips instead of text.
|
|
1357
|
+
|
|
1358
|
+
## Avoid
|
|
1359
|
+
- A standalone pick-one field — use Combobox.
|
|
1360
|
+
- Search suggestions for a whole field — use Autocomplete.
|
|
1361
|
+
|
|
1362
|
+
## Props
|
|
1363
|
+
|
|
1364
|
+
| Prop | Type | Default | Description |
|
|
1365
|
+
| --- | --- | --- | --- |
|
|
1366
|
+
| `triggers` * | `Array<{ char: string; items?: ListEntry[] \| (query, signal) => ListEntry[] \| Promise<ListEntry[]>; type?: string; spaces?: boolean; maxLength?: number; boundary?: 'whitespace' \| 'any'; filter?; insert?(item) => string \| Token }>` | | What opens the menu and what it lists. A loader function is called per query (results not filtered again). `type` is the token kind inserted inside a TokenInput. |
|
|
1367
|
+
| `onSelect` | `(value, { trigger, item }) => void` | | Runs after an item is inserted. |
|
|
1368
|
+
| `onQueryChange / onOpenChange` | `(query, { trigger }) => void / (open) => void` | | Text after the trigger; open state. |
|
|
1369
|
+
| `loading / emptyMessage / autoHighlight` | `boolean / ReactNode / boolean` | `false / "No matches" / true` | Loading row; empty text; highlight the first match so Enter/Tab choose it. |
|
|
1370
|
+
| `TriggerMenuInput: value / defaultValue / onValueChange, multiline, label, invalid + textarea props` | `string, boolean = true` | | The squircle field (textarea, or a single-line input with multiline={false}). Leave it out inside a TokenInput. |
|
|
1371
|
+
|
|
1372
|
+
## Examples
|
|
1373
|
+
|
|
1374
|
+
### Mentions and commands in a textarea
|
|
1375
|
+
|
|
1376
|
+
```tsx
|
|
1377
|
+
<TriggerMenu triggers={[
|
|
1378
|
+
{ char: '@', items: [{ value: 'ada', label: 'Ada' }, { value: 'grace', label: 'Grace' }] },
|
|
1379
|
+
{ char: '/', items: [{ value: 'summarize', label: 'summarize' }, { value: 'translate', label: 'translate' }] },
|
|
1380
|
+
]}>
|
|
1381
|
+
<TriggerMenuInput aria-label="Message" placeholder="Type @ to mention, / for commands" />
|
|
1382
|
+
</TriggerMenu>
|
|
1383
|
+
```
|
|
1384
|
+
|
|
1385
|
+
### Inside a Token Input
|
|
1386
|
+
|
|
1387
|
+
```tsx
|
|
1388
|
+
<TokenInput>
|
|
1389
|
+
<TokenInputEditor aria-label="Prompt" placeholder="Ask anything — @ to add a file" />
|
|
1390
|
+
<TriggerMenu triggers={[{ char: '@', type: 'file', items: files }]} />
|
|
1391
|
+
</TokenInput>
|
|
1392
|
+
```
|
|
1393
|
+
|
|
1394
|
+
## Rules
|
|
1395
|
+
- Default insertion is `char + label + space` in text fields, a token inside a TokenInput.
|
|
1396
|
+
- Keep lists short (≤ 8 visible); use a loader for large sets.
|
|
1397
|
+
|
|
1398
|
+
## Accessibility
|
|
1399
|
+
- Focus stays in the field; it gets aria-autocomplete="list", aria-haspopup, aria-controls and aria-activedescendant; an <input> is role="combobox" with aria-expanded.
|
|
1400
|
+
- ArrowUp/Down move, Enter/Tab insert, Escape dismisses the match (typing on does not reopen it).
|
|
1401
|
+
|
|
1402
|
+
## DOM contract (for agents operating the page)
|
|
1403
|
+
|
|
1404
|
+
- Selector: `[data-sw="trigger-menu"]`
|
|
1405
|
+
- `data-state`: 'open' | 'closed'
|
|
1406
|
+
- `data-trigger`: the active trigger char
|
|
1407
|
+
- `[data-sw="trigger-menu-item"]`: suggestions in the portaled [data-sw="trigger-menu-content"]
|
|
1408
|
+
- How to operate: Type the trigger + query into [data-sw="trigger-menu-input"], then click a suggestion. Agent bridge (trigger-menu): select(valueOrLabel) while open, close(); items = current suggestions. (trigger-menu-input): setValue(text), clear().
|
|
1409
|
+
|
|
1410
|
+
Related: `token-input`, `combobox`, `autocomplete`
|
|
1411
|
+
|
|
1412
|
+
---
|
|
1413
|
+
|
|
1414
|
+
# Token Input
|
|
1415
|
+
|
|
1416
|
+
> A text field that mixes editable text with tokens (people, files, tags) shown as chips; tokens come from Enter/comma, a Trigger Menu or code.
|
|
1417
|
+
|
|
1418
|
+
Category: inputs · Status: beta · Slug: `token-input`
|
|
1419
|
+
|
|
1420
|
+
```tsx
|
|
1421
|
+
import { TokenInput, TokenInputEditor, TokenInputToken, TokenInputTokenRemove, TriggerMenu, type TokenInputValue } from '@peerproblem/sw3-ui'
|
|
1422
|
+
```
|
|
1423
|
+
|
|
1424
|
+
## When to use
|
|
1425
|
+
- Prompt boxes that reference files, people or skills inline.
|
|
1426
|
+
- Tag / recipient fields: `createToken` turns typed words into chips on Enter or comma.
|
|
1427
|
+
|
|
1428
|
+
## Avoid
|
|
1429
|
+
- Plain text — use Textarea / Input.
|
|
1430
|
+
- Choosing from a fixed list only — use Combobox multiple.
|
|
1431
|
+
|
|
1432
|
+
## Props
|
|
1433
|
+
|
|
1434
|
+
| Prop | Type | Default | Description |
|
|
1435
|
+
| --- | --- | --- | --- |
|
|
1436
|
+
| `value / defaultValue / onValueChange` | `Array<string \| { type, value, label, id?, status?, data? }>` | | Text and tokens in order. Give controlled tokens stable `id`s (or reuse the same objects). |
|
|
1437
|
+
| `onSubmit` | `(value) => void` | | Runs on the submit shortcut (not while a trigger menu is open). Without it the shortcut submits the surrounding form. |
|
|
1438
|
+
| `submitShortcut` | `'enter' \| 'mod+enter'` | `'enter'` | Enter submits (Shift+Enter = new line), or ⌘/Ctrl+Enter submits. |
|
|
1439
|
+
| `createToken` | `(text) => Token \| null` | | Turn the word before the caret into a token on Enter or comma. |
|
|
1440
|
+
| `renderToken` | `(token) => ReactNode` | | Custom chip; usually `<TokenInputToken icon={…} />`. Default: icon by type + label + remove. |
|
|
1441
|
+
| `format` | `(token) => string` | ``[label](type:value)`` | How tokens are written in the submitted `name` text. |
|
|
1442
|
+
| `placeholder` | `string` | | For the default editor (or set it on TokenInputEditor). |
|
|
1443
|
+
| `name / form / disabled / readOnly / required / invalid` | `string / boolean` | | Form + states; inherit from Field. |
|
|
1444
|
+
| `children` | `ReactNode` | | `<TokenInputEditor placeholder aria-label />` and optionally a `<TriggerMenu>` for suggestions. |
|
|
1445
|
+
|
|
1446
|
+
## Examples
|
|
1447
|
+
|
|
1448
|
+
### Prompt with @files
|
|
1449
|
+
|
|
1450
|
+
```tsx
|
|
1451
|
+
<TokenInput defaultValue={['Explain ', { type: 'file', value: 'src/routes.ts', label: 'routes.ts' }, ' ']} onSubmit={send}>
|
|
1452
|
+
<TokenInputEditor aria-label="Prompt" placeholder="Ask anything — @ to add a file" />
|
|
1453
|
+
<TriggerMenu triggers={[{ char: '@', type: 'file', items: files }]} />
|
|
1454
|
+
</TokenInput>
|
|
1455
|
+
```
|
|
1456
|
+
|
|
1457
|
+
### Tags from Enter / comma
|
|
1458
|
+
|
|
1459
|
+
```tsx
|
|
1460
|
+
<TokenInput aria-label="Tags" name="tags" placeholder="Add tags…" createToken={(text) => ({ type: 'tag', value: text, label: text })} />
|
|
1461
|
+
```
|
|
1462
|
+
|
|
1463
|
+
## Rules
|
|
1464
|
+
- Each token moves and deletes as one piece; label tokens with what people read (file name, person name).
|
|
1465
|
+
- Use `type` consistently: mention, file, tag, skill.
|
|
1466
|
+
|
|
1467
|
+
## Accessibility
|
|
1468
|
+
- Editor role="textbox" aria-multiline; tokens read as "label type"; the ✕ is hidden from assistive tech because Backspace/Delete remove a token in one press.
|
|
1469
|
+
- Enter submits (or inserts the highlighted suggestion), Shift+Enter is a new line; arrows step over a token.
|
|
1470
|
+
|
|
1471
|
+
## DOM contract (for agents operating the page)
|
|
1472
|
+
|
|
1473
|
+
- Selector: `[data-sw="token-input"]`
|
|
1474
|
+
- `data-empty`: present while empty
|
|
1475
|
+
- `[data-sw="token-input-token"]`: one per token: data-type, data-value
|
|
1476
|
+
- `[data-sw="token-input-editor"]`: the contenteditable textbox
|
|
1477
|
+
- How to operate: Click into [data-sw="token-input-editor"] and type; type a trigger (e.g. @) to pick a token. Agent bridge: setValue(value | text), add(tokenOrText), remove(valueOrId), clear(); state.text = readable text, state.tokens = token list.
|
|
1478
|
+
|
|
1479
|
+
Related: `trigger-menu`, `combobox`, `textarea`
|
|
1480
|
+
|
|
1481
|
+
---
|
|
1482
|
+
|
|
1483
|
+
# Calendar
|
|
1484
|
+
|
|
1485
|
+
> An inline month grid for picking one date, several dates or a range, with full grid keyboard support. Values are ISO date strings.
|
|
1486
|
+
|
|
1487
|
+
Category: dates · Status: beta · Slug: `calendar`
|
|
1488
|
+
|
|
1489
|
+
```tsx
|
|
1490
|
+
import { Calendar, CalendarHeader, CalendarPrevious, CalendarHeading, CalendarNext, CalendarGrid } from '@peerproblem/sw3-ui'
|
|
1491
|
+
```
|
|
1492
|
+
|
|
1493
|
+
## When to use
|
|
1494
|
+
- Dates that should stay visible on the page: a booking flow, a schedule, an availability view.
|
|
1495
|
+
- Picking several separate days (`mode="multiple"`) or a span (`mode="range"`, often with `months={2}`).
|
|
1496
|
+
|
|
1497
|
+
## Avoid
|
|
1498
|
+
- A form field for a single date → use DatePicker (typing + popup) or DateInput (typing only).
|
|
1499
|
+
- Passing Date objects → values are ISO strings like "2026-11-14"; use the exported helpers (addDays, formatDate…) for arithmetic.
|
|
1500
|
+
- Disabling days you only want to mark as booked → use `unavailable`/`isDateUnavailable` so they stay focusable and readable.
|
|
1501
|
+
|
|
1502
|
+
## Props
|
|
1503
|
+
|
|
1504
|
+
| Prop | Type | Default | Description |
|
|
1505
|
+
| --- | --- | --- | --- |
|
|
1506
|
+
| `mode` | `'single' \| 'multiple' \| 'range'` | `'single'` | How many dates it selects. |
|
|
1507
|
+
| `value` | `string \| null · string[] · [start, end] \| null` | | Selected value for the mode: an ISO date, a sorted list, or an inclusive [start, end] range. Pass to control. |
|
|
1508
|
+
| `defaultValue` | `same as value` | | Initial value when uncontrolled. |
|
|
1509
|
+
| `onValueChange` | `(value) => void` | | Runs when a day is picked. A range reports once both ends are chosen. |
|
|
1510
|
+
| `month` | `string ("YYYY-MM")` | | First month shown. Pass to control it. |
|
|
1511
|
+
| `defaultMonth` | `string ("YYYY-MM")` | | Initial month. Defaults to the selection, else today. |
|
|
1512
|
+
| `onMonthChange` | `(month: string) => void` | | Runs when Previous/Next or keyboard paging changes the month. |
|
|
1513
|
+
| `min` | `string (ISO date)` | | Earliest date that can be picked, e.g. "2026-11-01". |
|
|
1514
|
+
| `max` | `string (ISO date)` | | Latest date that can be picked. |
|
|
1515
|
+
| `isDateUnavailable` | `(date: string) => boolean` | | Return true for dates that cannot be picked (booked days). They stay focusable so keyboard users hear them. |
|
|
1516
|
+
| `unavailable` | `DateMatcher \| DateMatcher[]` | | The same as data: ISO dates, `{ from, to }`, `{ before }`, `{ after }`, `{ weekday: [0, 6] }` (weekends) or a function. |
|
|
1517
|
+
| `locale` | `string` | `page lang, then browser` | BCP 47 locale for names, order and week start. |
|
|
1518
|
+
| `weekStartsOn` | `number (0–6)` | `locale's (Intl weekInfo)` | First day of the week, 0 = Sunday. |
|
|
1519
|
+
| `months` | `number` | `1` | Months side by side, each its own grid. They wrap on narrow screens. |
|
|
1520
|
+
| `weekdayFormat` | `'narrow' \| 'short' \| 'long'` | `'short'` | Weekday header style. |
|
|
1521
|
+
| `fixedWeeks` | `boolean` | `false` | Always render six weeks so the height never changes. |
|
|
1522
|
+
| `showOutsideDays` | `boolean` | `true with 1 month, false with more` | Show neighbouring months' days at the edges. |
|
|
1523
|
+
| `disabled` | `boolean` | `false` | Nothing can be picked or focused. |
|
|
1524
|
+
| `readOnly` | `boolean` | `false` | Days can be focused but not picked. |
|
|
1525
|
+
| `deselectable` | `boolean` | `false` | Single mode: pressing the selected day clears it. |
|
|
1526
|
+
| `minDays` | `number` | | Range: fewest days in a range, ends included. |
|
|
1527
|
+
| `maxDays` | `number` | | Range: most days in a range, ends included. |
|
|
1528
|
+
| `allowUnavailable` | `boolean` | `false` | Range: allow a range to cross unavailable days. |
|
|
1529
|
+
| `today` | `string (ISO date)` | | Override today (marker + starting month). Useful for tests and demos. |
|
|
1530
|
+
| `timeZone` | `string` | `browser's` | IANA zone that decides what day today is. |
|
|
1531
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Day cell size 32 / 38 / 44px. |
|
|
1532
|
+
| `framed` | `boolean` | `true` | Draw its own squircle frame. Pass false only when it already sits on a surface (a popup, a Card it shares with other content). |
|
|
1533
|
+
| `autoFocus` | `boolean` | `false` | Focus the tab-stop day on mount. |
|
|
1534
|
+
| `renderDay` | `(day: CalendarDayState) => ReactNode` | | Custom content inside each day button (e.g. a price or a dot). Keep the day number visible. |
|
|
1535
|
+
| `children` | `ReactNode` | | Custom layout from parts: <CalendarHeader/> (or <CalendarPrevious/>, <CalendarHeading/>, <CalendarNext/>) and <CalendarGrid offset={n}/>. Empty = default layout. |
|
|
1536
|
+
| `CalendarGrid.offset` | `number` | `0` | Which of the shown months this grid renders, from 0. |
|
|
1537
|
+
| `CalendarPrevious / CalendarNext aria-label` | `string` | | Override "Previous month" / "Next month". |
|
|
1538
|
+
|
|
1539
|
+
## Examples
|
|
1540
|
+
|
|
1541
|
+
### Single date
|
|
1542
|
+
|
|
1543
|
+
```tsx
|
|
1544
|
+
const [date, setDate] = useState<string | null>('2026-11-14')
|
|
1545
|
+
<Calendar value={date} onValueChange={setDate} />
|
|
1546
|
+
```
|
|
1547
|
+
|
|
1548
|
+
### Range over two months, weekends unavailable
|
|
1549
|
+
|
|
1550
|
+
```tsx
|
|
1551
|
+
<Calendar
|
|
1552
|
+
mode="range"
|
|
1553
|
+
months={2}
|
|
1554
|
+
defaultValue={['2026-11-16', '2026-11-20']}
|
|
1555
|
+
min="2026-11-01"
|
|
1556
|
+
unavailable={{ weekday: [0, 6] }}
|
|
1557
|
+
onValueChange={(range) => console.log(range)} // ['2026-11-16', '2026-11-20'] | null
|
|
1558
|
+
/>
|
|
1559
|
+
```
|
|
1560
|
+
|
|
1561
|
+
### Several days, Monday first
|
|
1562
|
+
|
|
1563
|
+
```tsx
|
|
1564
|
+
<Card padding="md">
|
|
1565
|
+
<Text>Pick review days</Text>
|
|
1566
|
+
<Calendar mode="multiple" weekStartsOn={1} defaultValue={['2026-11-03', '2026-11-10']} framed={false} />
|
|
1567
|
+
</Card>
|
|
1568
|
+
```
|
|
1569
|
+
|
|
1570
|
+
## Rules
|
|
1571
|
+
- All values are ISO strings ("YYYY-MM-DD", months "YYYY-MM"). Never pass Date objects.
|
|
1572
|
+
- Selection is the one accent fill; do not add other accent elements next to it.
|
|
1573
|
+
- Framed by default — do not wrap it in a Card just to frame it (that double-frames it). Use `framed={false}` inside a popup or a shared surface.
|
|
1574
|
+
- Today is marked by a dot only (normal weight). Days have an even 2px gutter and concentric squircle corners (host radius − inset).
|
|
1575
|
+
- For booked or blocked days use `unavailable` (still focusable); `min`/`max` for hard bounds.
|
|
1576
|
+
|
|
1577
|
+
## Accessibility
|
|
1578
|
+
- Each month is a role="grid" table named by its month; weekday headers carry full names; each day is a gridcell (aria-selected) holding a button named by its full date, with aria-current="date" on today.
|
|
1579
|
+
- One Tab stop: the selected day, else today, else the first available day.
|
|
1580
|
+
- Keys: arrows move by day/week, Home/End to week start/end, PageUp/PageDown by month, Shift+PageUp/PageDown by year, Enter/Space selects, Escape cancels an unfinished range.
|
|
1581
|
+
- The heading is aria-live so month changes are announced.
|
|
1582
|
+
|
|
1583
|
+
## DOM contract (for agents operating the page)
|
|
1584
|
+
|
|
1585
|
+
- Selector: `[data-sw="calendar"]`
|
|
1586
|
+
- `data-mode`: single | multiple | range
|
|
1587
|
+
- `[data-sw="calendar-day"][data-value]`: each day's ISO date
|
|
1588
|
+
- `data-selected / aria-selected (on the gridcell)`: selected days (every day of a range)
|
|
1589
|
+
- `data-range-start / data-range-middle / data-range-end`: range parts
|
|
1590
|
+
- `data-today`: today
|
|
1591
|
+
- `data-unavailable / data-disabled / data-outside`: unpickable / out of bounds / neighbouring month
|
|
1592
|
+
- `[data-sw="calendar-grid"][data-month]`: the month a grid shows ("YYYY-MM")
|
|
1593
|
+
- `data-range-pending`: on the root while a range start is chosen but not its end
|
|
1594
|
+
- How to operate: Click `[data-sw="calendar-day"][data-value="2026-11-14"]` to pick it (range: click start, then end). Use `[data-sw="calendar-next"]` / `calendar-previous` to change month. Agent bridge: setValue(iso | "start/end" | "a,b,c"), select(iso), clear(), setMonth("YYYY-MM"), previous(), next(); state = { mode, value, month, min, max, disabled, readOnly, rangeStart }.
|
|
1595
|
+
|
|
1596
|
+
Related: `date-picker`, `date-input`
|
|
1597
|
+
|
|
1598
|
+
---
|
|
1599
|
+
|
|
1600
|
+
# DateInput
|
|
1601
|
+
|
|
1602
|
+
> 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".
|
|
1603
|
+
|
|
1604
|
+
Category: dates · Status: beta · Slug: `date-input`
|
|
1605
|
+
|
|
1606
|
+
```tsx
|
|
1607
|
+
import { DateInput, Field } from '@peerproblem/sw3-ui'
|
|
1608
|
+
```
|
|
1609
|
+
|
|
1610
|
+
## When to use
|
|
1611
|
+
- Dates people know by heart and type faster than they pick: birthdays, document dates, an exact deadline.
|
|
1612
|
+
|
|
1613
|
+
## Avoid
|
|
1614
|
+
- Dates people browse for (trip dates, "next Tuesday") → use DatePicker, which adds the calendar.
|
|
1615
|
+
- A plain <Input type="text"> for dates → you lose locale order, validation and ISO output.
|
|
1616
|
+
- Parsing the displayed text → read `value` / the hidden input; it is always ISO or null.
|
|
1617
|
+
|
|
1618
|
+
## Props
|
|
1619
|
+
|
|
1620
|
+
| Prop | Type | Default | Description |
|
|
1621
|
+
| --- | --- | --- | --- |
|
|
1622
|
+
| `value` | `string \| null` | | ISO date. Stays null until every segment is filled. Pass to control. |
|
|
1623
|
+
| `defaultValue` | `string \| null` | `null` | Initial value (and what a form reset restores). |
|
|
1624
|
+
| `onValueChange` | `(value: string \| null) => void` | | Runs with the ISO date once complete, and with null when a segment is cleared. |
|
|
1625
|
+
| `min` | `string (ISO date)` | | Earliest date that is valid, e.g. "2026-11-01". |
|
|
1626
|
+
| `max` | `string (ISO date)` | | Latest date that is valid. |
|
|
1627
|
+
| `isDateUnavailable` | `(date: string) => boolean` | | Return true for dates that are invalid (booked days). They stay focusable so keyboard users hear them. |
|
|
1628
|
+
| `unavailable` | `DateMatcher \| DateMatcher[]` | | The same as data: ISO dates, `{ from, to }`, `{ before }`, `{ after }`, `{ weekday: [0, 6] }` (weekends) or a function. |
|
|
1629
|
+
| `locale` | `string` | `page lang, then browser` | BCP 47 locale for names, order and week start. |
|
|
1630
|
+
| `label` | `ReactNode` | | Visible label. Omit inside <Field> (the Field labels it) or pass aria-label. |
|
|
1631
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
1632
|
+
| `error` | `ReactNode` | | Error text; also marks the field invalid. |
|
|
1633
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
1634
|
+
| `inline` | `boolean` | `false` | Shrink the box to its content. By default it fills the width, like Input. |
|
|
1635
|
+
| `disabled` | `boolean` | `false` | Cannot be focused or changed. |
|
|
1636
|
+
| `readOnly` | `boolean` | `false` | Value is visible but cannot change. |
|
|
1637
|
+
| `required` | `boolean` | `false` | Blocks form submit while empty. |
|
|
1638
|
+
| `invalid` | `boolean` | | Force the invalid look (also set automatically when out of range). |
|
|
1639
|
+
| `name` | `string` | | Submits the ISO value under this name through a hidden input. |
|
|
1640
|
+
| `form` | `string` | | id of the form it belongs to when outside it. |
|
|
1641
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label. |
|
|
1642
|
+
| `suffix` | `ReactNode` | | Content inside the box after the segments (an icon). |
|
|
1643
|
+
| `id` | `string` | | id for the first segment (so <label for> focuses it). |
|
|
1644
|
+
|
|
1645
|
+
## Examples
|
|
1646
|
+
|
|
1647
|
+
### In a Field
|
|
1648
|
+
|
|
1649
|
+
```tsx
|
|
1650
|
+
<Field label="Start date">
|
|
1651
|
+
<DateInput name="start" defaultValue="2026-11-14" />
|
|
1652
|
+
</Field>
|
|
1653
|
+
```
|
|
1654
|
+
|
|
1655
|
+
### Controlled with bounds
|
|
1656
|
+
|
|
1657
|
+
```tsx
|
|
1658
|
+
const [due, setDue] = useState<string | null>(null)
|
|
1659
|
+
<DateInput label="Due date" value={due} onValueChange={setDue} min="2026-11-14" hint="Today or later" />
|
|
1660
|
+
```
|
|
1661
|
+
|
|
1662
|
+
### German order (TT.MM.JJJJ)
|
|
1663
|
+
|
|
1664
|
+
```tsx
|
|
1665
|
+
<DateInput aria-label="Geburtsdatum" locale="de-DE" />
|
|
1666
|
+
```
|
|
1667
|
+
|
|
1668
|
+
## Rules
|
|
1669
|
+
- Value is ISO or null — never a partial date. A partly filled date blocks form submit.
|
|
1670
|
+
- Let the locale decide the order; do not hard-code MM/DD/YYYY.
|
|
1671
|
+
- Uses the same size and corner scale as Input. Pass `inline` to size it to its content.
|
|
1672
|
+
|
|
1673
|
+
## Accessibility
|
|
1674
|
+
- 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).
|
|
1675
|
+
- 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.
|
|
1676
|
+
|
|
1677
|
+
## DOM contract (for agents operating the page)
|
|
1678
|
+
|
|
1679
|
+
- Selector: `[data-sw="date-input"]`
|
|
1680
|
+
- `data-invalid`: out of range / unavailable / error
|
|
1681
|
+
- `[data-sw="date-input-group"][data-empty]`: every segment empty
|
|
1682
|
+
- `[data-sw="date-input-segment"][data-type]`: year | month | day; aria-valuenow holds its number
|
|
1683
|
+
- `input[name] (hidden)`: the ISO value submitted with the form
|
|
1684
|
+
- 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 }.
|
|
1685
|
+
|
|
1686
|
+
Related: `date-picker`, `time-input`, `calendar`
|
|
1687
|
+
|
|
1688
|
+
---
|
|
1689
|
+
|
|
1690
|
+
# DatePicker
|
|
1691
|
+
|
|
1692
|
+
> DateInput plus Calendar in a popup: type a date or pick it from the month grid. Single date or a range, optional presets; submits ISO.
|
|
1693
|
+
|
|
1694
|
+
Category: dates · Status: beta · Slug: `date-picker`
|
|
1695
|
+
|
|
1696
|
+
```tsx
|
|
1697
|
+
import { DatePicker, todayISO, addDays } from '@peerproblem/sw3-ui'
|
|
1698
|
+
```
|
|
1699
|
+
|
|
1700
|
+
## When to use
|
|
1701
|
+
- Any form field for a date where people may want to see the calendar: due dates, scheduling, filters.
|
|
1702
|
+
- Date ranges (`mode="range"`, two inputs) such as report periods or stays, with `presets` for "Last 7 days".
|
|
1703
|
+
|
|
1704
|
+
## Avoid
|
|
1705
|
+
- Always-visible dates → use Calendar inline.
|
|
1706
|
+
- Birthdays and other known dates far in the past → DateInput is faster than paging through months.
|
|
1707
|
+
- Computing presets with Date math in local time → use the ISO helpers (addDays, todayISO).
|
|
1708
|
+
|
|
1709
|
+
## Props
|
|
1710
|
+
|
|
1711
|
+
| Prop | Type | Default | Description |
|
|
1712
|
+
| --- | --- | --- | --- |
|
|
1713
|
+
| `mode` | `'single' \| 'range'` | `'single'` | One date, or a [start, end] range with an input for each end. |
|
|
1714
|
+
| `value` | `string \| null · [start, end] \| null` | | ISO date, or an inclusive ISO range. Pass to control. |
|
|
1715
|
+
| `defaultValue` | `same as value` | `null` | Initial value (restored on form reset). |
|
|
1716
|
+
| `onValueChange` | `(value) => void` | | Runs when a day is picked, a typed date completes, a preset or Clear is pressed. Ranges report once both ends are set. |
|
|
1717
|
+
| `open` | `boolean` | | Whether the calendar popup is open. Pass to control. |
|
|
1718
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state. |
|
|
1719
|
+
| `onOpenChange` | `(open: boolean) => void` | | Runs when the popup opens or closes. |
|
|
1720
|
+
| `min` | `string (ISO date)` | | Earliest date that can be picked, e.g. "2026-11-01". |
|
|
1721
|
+
| `max` | `string (ISO date)` | | Latest date that can be picked. |
|
|
1722
|
+
| `isDateUnavailable` | `(date: string) => boolean` | | Return true for dates that cannot be picked (booked days). They stay focusable so keyboard users hear them. |
|
|
1723
|
+
| `unavailable` | `DateMatcher \| DateMatcher[]` | | The same as data: ISO dates, `{ from, to }`, `{ before }`, `{ after }`, `{ weekday: [0, 6] }` (weekends) or a function. |
|
|
1724
|
+
| `locale` | `string` | `page lang, then browser` | BCP 47 locale for names, order and week start. |
|
|
1725
|
+
| `weekStartsOn` | `number (0–6)` | `locale's` | First day of the week in the calendar. |
|
|
1726
|
+
| `months` | `number` | `1` | Months shown side by side in the popup. |
|
|
1727
|
+
| `fixedWeeks` | `boolean` | `false` | Calendar always shows six weeks. |
|
|
1728
|
+
| `minDays / maxDays` | `number` | | Range length limits, ends included. |
|
|
1729
|
+
| `today` | `string (ISO date)` | | Override today. |
|
|
1730
|
+
| `timeZone` | `string` | | IANA zone deciding today. |
|
|
1731
|
+
| `closeOnSelect` | `boolean` | `true` | Close after a pick (a range's end) or a preset. |
|
|
1732
|
+
| `presets` | `Array<{ label: ReactNode; value: string \| [string, string] }>` | | Shortcuts shown beside the calendar; the matching one shows aria-pressed. |
|
|
1733
|
+
| `clearable` | `boolean` | `false` | Show a clear (×) button while there is a value. |
|
|
1734
|
+
| `placement` | `Placement` | `'bottom-start'` | Popup placement. |
|
|
1735
|
+
| `label` | `ReactNode` | | Visible label. Omit inside <Field> (the Field labels it) or pass aria-label. |
|
|
1736
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
1737
|
+
| `error` | `ReactNode` | | Error text; also marks the field invalid. |
|
|
1738
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
1739
|
+
| `inline` | `boolean` | `false` | Shrink the box to its content. By default it fills the width, like Input. |
|
|
1740
|
+
| `disabled` | `boolean` | `false` | Cannot be focused or changed. |
|
|
1741
|
+
| `readOnly` | `boolean` | `false` | Value is visible but cannot change. |
|
|
1742
|
+
| `required` | `boolean` | `false` | Blocks form submit while empty. |
|
|
1743
|
+
| `invalid` | `boolean` | | Force the invalid look (also set automatically when out of range). |
|
|
1744
|
+
| `form` | `string` | | id of the form it belongs to when outside it. |
|
|
1745
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label. |
|
|
1746
|
+
| `name` | `string` | | Submit name (ISO). In range mode both ends submit under it unless startName / endName are set. |
|
|
1747
|
+
| `startName / endName` | `string` | | Range: separate submit names for each end. |
|
|
1748
|
+
| `startLabel / endLabel` | `string` | `'Start date' / 'End date'` | Range: accessible names of the two inputs. |
|
|
1749
|
+
|
|
1750
|
+
## Anatomy
|
|
1751
|
+
|
|
1752
|
+
```
|
|
1753
|
+
DatePicker
|
|
1754
|
+
├─ field DateInput's segmented field (month / day / year)
|
|
1755
|
+
├─ calendar button
|
|
1756
|
+
└─ popup PopupPanel
|
|
1757
|
+
├─ presets optional
|
|
1758
|
+
└─ Calendar one month grid, or a range
|
|
1759
|
+
```
|
|
1760
|
+
|
|
1761
|
+
Built from: `DateInput`, `Calendar`, `PopupPanel (usePopup)`.
|
|
1762
|
+
|
|
1763
|
+
## Examples
|
|
1764
|
+
|
|
1765
|
+
### Due date in a form
|
|
1766
|
+
|
|
1767
|
+
```tsx
|
|
1768
|
+
<DatePicker label="Due date" name="due" defaultValue="2026-11-20" min="2026-11-14" clearable />
|
|
1769
|
+
```
|
|
1770
|
+
|
|
1771
|
+
### Report range with presets
|
|
1772
|
+
|
|
1773
|
+
```tsx
|
|
1774
|
+
const today = todayISO()
|
|
1775
|
+
const [range, setRange] = useState<[string, string] | null>(null)
|
|
1776
|
+
<DatePicker
|
|
1777
|
+
mode="range"
|
|
1778
|
+
label="Period"
|
|
1779
|
+
months={2}
|
|
1780
|
+
value={range}
|
|
1781
|
+
onValueChange={setRange}
|
|
1782
|
+
presets={[
|
|
1783
|
+
{ label: 'Last 7 days', value: [addDays(today, -6), today] },
|
|
1784
|
+
{ label: 'Last 30 days', value: [addDays(today, -29), today] },
|
|
1785
|
+
]}
|
|
1786
|
+
/>
|
|
1787
|
+
```
|
|
1788
|
+
|
|
1789
|
+
## Rules
|
|
1790
|
+
- Values are ISO strings; ranges are [start, end] with start ≤ end.
|
|
1791
|
+
- Use a visible label (or Field). The trigger is named "Choose date, selected …" automatically.
|
|
1792
|
+
- Presets are computed by the app (use addDays/todayISO from @peerproblem/sw3-ui). They render as list rows: the matching one gets the neutral selected fill + 500 weight, not accent.
|
|
1793
|
+
- Fills the width like Input; pass `inline` to size it to its content (e.g. next to a TimeInput).
|
|
1794
|
+
|
|
1795
|
+
## Accessibility
|
|
1796
|
+
- Follows the WAI-ARIA date picker dialog: segmented spinbutton input(s), a button with aria-haspopup="dialog" and aria-expanded, and a role="dialog" popup holding the Calendar grid.
|
|
1797
|
+
- Opening focuses the selected day (else today). Picking a day or Escape closes and returns focus to the button. Alt+ArrowDown in the input opens it; Tab out closes it.
|
|
1798
|
+
|
|
1799
|
+
## DOM contract (for agents operating the page)
|
|
1800
|
+
|
|
1801
|
+
- Selector: `[data-sw="date-picker"]`
|
|
1802
|
+
- `data-state`: open | closed
|
|
1803
|
+
- `data-mode`: single | range
|
|
1804
|
+
- `data-invalid`: typed date out of range / unavailable
|
|
1805
|
+
- `[data-sw="date-picker-trigger"][aria-expanded]`: popup open
|
|
1806
|
+
- `[data-sw="date-picker-input"][data-part]`: segment group (start / end in range mode)
|
|
1807
|
+
- `[data-sw="date-picker-content"]`: the popup (portaled to body) containing [data-sw="calendar"]
|
|
1808
|
+
- `[data-sw="date-picker-preset"][aria-pressed]`: preset matching the value
|
|
1809
|
+
- How to operate: Click `[data-sw="date-picker-trigger"]`, then a `[data-sw="calendar-day"][data-value="YYYY-MM-DD"]` in the popup; or type into the segments. Agent bridge: setValue("YYYY-MM-DD" | "start/end"), clear(), open(), close(), toggle(); state = { mode, value, open, min, max, disabled, readOnly, invalid }.
|
|
1810
|
+
|
|
1811
|
+
Related: `calendar`, `date-input`, `time-input`
|
|
1812
|
+
|
|
1813
|
+
---
|
|
1814
|
+
|
|
1815
|
+
# TimeInput
|
|
1816
|
+
|
|
1817
|
+
> Segmented time entry — hour, minute, optional second and AM/PM on 12-hour locales. Value is 24-hour ISO "HH:mm".
|
|
1818
|
+
|
|
1819
|
+
Category: dates · Status: beta · Slug: `time-input`
|
|
1820
|
+
|
|
1821
|
+
```tsx
|
|
1822
|
+
import { TimeInput } from '@peerproblem/sw3-ui'
|
|
1823
|
+
```
|
|
1824
|
+
|
|
1825
|
+
## When to use
|
|
1826
|
+
- A time of day: a meeting start, a cron run time, opening hours.
|
|
1827
|
+
|
|
1828
|
+
## Avoid
|
|
1829
|
+
- Durations ("2h 30m") → use a number input.
|
|
1830
|
+
- Converting the value to 12-hour yourself → the value is always 24-hour "HH:mm"; the display follows the locale.
|
|
1831
|
+
|
|
1832
|
+
## Props
|
|
1833
|
+
|
|
1834
|
+
| Prop | Type | Default | Description |
|
|
1835
|
+
| --- | --- | --- | --- |
|
|
1836
|
+
| `value` | `string \| null` | | 24-hour time "14:30" ("14:30:15" with seconds). Null until complete. Pass to control. |
|
|
1837
|
+
| `defaultValue` | `string \| null` | `null` | Initial value (restored on form reset). |
|
|
1838
|
+
| `onValueChange` | `(value: string \| null) => void` | | Runs with the time once complete, null when cleared. |
|
|
1839
|
+
| `granularity` | `'minute' \| 'second'` | `'minute'` | Smallest unit shown. |
|
|
1840
|
+
| `hourCycle` | `12 \| 24` | `locale's` | Clock to show. |
|
|
1841
|
+
| `min` | `string ("HH:mm")` | | Earliest valid time; earlier marks it invalid. |
|
|
1842
|
+
| `max` | `string ("HH:mm")` | | Latest valid time. |
|
|
1843
|
+
| `locale` | `string` | `page lang, then browser` | Locale for separators, clock and AM/PM labels. |
|
|
1844
|
+
| `label` | `ReactNode` | | Visible label. Omit inside <Field> (the Field labels it) or pass aria-label. |
|
|
1845
|
+
| `hint` | `ReactNode` | | Help text under the field. |
|
|
1846
|
+
| `error` | `ReactNode` | | Error text; also marks the field invalid. |
|
|
1847
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
|
|
1848
|
+
| `inline` | `boolean` | `false` | Shrink the box to its content. By default it fills the width, like Input. |
|
|
1849
|
+
| `disabled` | `boolean` | `false` | Cannot be focused or changed. |
|
|
1850
|
+
| `readOnly` | `boolean` | `false` | Value is visible but cannot change. |
|
|
1851
|
+
| `required` | `boolean` | `false` | Blocks form submit while empty. |
|
|
1852
|
+
| `invalid` | `boolean` | | Force the invalid look (also set automatically when out of range). |
|
|
1853
|
+
| `name` | `string` | | Submits the ISO value under this name through a hidden input. |
|
|
1854
|
+
| `form` | `string` | | id of the form it belongs to when outside it. |
|
|
1855
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label. |
|
|
1856
|
+
| `suffix` | `ReactNode` | | Content inside the box after the segments. |
|
|
1857
|
+
|
|
1858
|
+
## Examples
|
|
1859
|
+
|
|
1860
|
+
### Meeting time
|
|
1861
|
+
|
|
1862
|
+
```tsx
|
|
1863
|
+
<TimeInput label="Starts at" name="start" defaultValue="09:30" />
|
|
1864
|
+
```
|
|
1865
|
+
|
|
1866
|
+
### 24-hour with seconds
|
|
1867
|
+
|
|
1868
|
+
```tsx
|
|
1869
|
+
<TimeInput aria-label="Run at" hourCycle={24} granularity="second" defaultValue="02:00:00" />
|
|
1870
|
+
```
|
|
1871
|
+
|
|
1872
|
+
### Date + time together
|
|
1873
|
+
|
|
1874
|
+
```tsx
|
|
1875
|
+
<div style={{ display: 'flex', gap: 8 }}>
|
|
1876
|
+
<DatePicker aria-label="Date" value={date} onValueChange={setDate} />
|
|
1877
|
+
<TimeInput aria-label="Time" value={time} onValueChange={setTime} />
|
|
1878
|
+
</div>
|
|
1879
|
+
```
|
|
1880
|
+
|
|
1881
|
+
## Rules
|
|
1882
|
+
- Value is 24-hour regardless of the displayed clock.
|
|
1883
|
+
- The AM/PM segment reserves room for the wider localized label.
|
|
1884
|
+
- Pair with DatePicker for a date-time; keep both values as ISO strings.
|
|
1885
|
+
|
|
1886
|
+
## Accessibility
|
|
1887
|
+
- Root is role="group"; each unit is role="spinbutton" ("hour", "minute", "AM/PM") with aria-valuenow/min/max/valuetext.
|
|
1888
|
+
- Same keys as DateInput; on the AM/PM segment, A or P chooses (also the first letter of localized labels), ↑/↓ toggles.
|
|
1889
|
+
|
|
1890
|
+
## DOM contract (for agents operating the page)
|
|
1891
|
+
|
|
1892
|
+
- Selector: `[data-sw="time-input"]`
|
|
1893
|
+
- `data-invalid`: outside min/max or error
|
|
1894
|
+
- `[data-sw="time-input-segment"][data-type]`: hour | minute | second | dayPeriod
|
|
1895
|
+
- `input[name] (hidden)`: 24-hour value submitted with the form
|
|
1896
|
+
- How to operate: Focus the hour segment and type e.g. 0230 then P. Agent bridge: setValue("HH:mm"), clear(); state = { value, min, max, disabled, readOnly, invalid }.
|
|
1897
|
+
|
|
1898
|
+
Related: `date-input`, `date-picker`
|
|
1899
|
+
|
|
1900
|
+
---
|
|
1901
|
+
|
|
1902
|
+
# ColorPicker
|
|
1903
|
+
|
|
1904
|
+
> 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.
|
|
1905
|
+
|
|
1906
|
+
Category: inputs · Status: beta · Slug: `color-picker`
|
|
1907
|
+
|
|
1908
|
+
```tsx
|
|
1909
|
+
import { ColorPicker, ColorPickerPopover } from '@peerproblem/sw3-ui'
|
|
1910
|
+
```
|
|
1911
|
+
|
|
1912
|
+
## When to use
|
|
1913
|
+
- Choosing a brand, label, chart or theme color.
|
|
1914
|
+
- Inline in a settings panel (`ColorPicker`) or behind a swatch button in a form (`ColorPickerPopover`).
|
|
1915
|
+
|
|
1916
|
+
## Avoid
|
|
1917
|
+
- `<input type="color">` — it has no alpha, no presets and looks different per browser.
|
|
1918
|
+
- A picker for a handful of fixed choices only. Use a RadioGroup or SegmentedControl of swatches, or pass `presets` with `showInput={false}`.
|
|
1919
|
+
- Storing `oklch()`/named values and expecting SSR to parse them: during server rendering only hex, rgb() and hsl() parse.
|
|
1920
|
+
|
|
1921
|
+
## Props
|
|
1922
|
+
|
|
1923
|
+
| Prop | Type | Default | Description |
|
|
1924
|
+
| --- | --- | --- | --- |
|
|
1925
|
+
| `value` | `string` | | The color as any CSS color string. Controlled. |
|
|
1926
|
+
| `defaultValue` | `string` | `'#000000'` | Initial color when uncontrolled. |
|
|
1927
|
+
| `onValueChange` | `(value: string) => void` | | Every step of a drag, key, swatch or text commit, written in `format`. |
|
|
1928
|
+
| `onValueCommit` | `(value: string) => void` | | Once an interaction ends (pointer up, key, swatch, text). Save here. |
|
|
1929
|
+
| `format` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | How the value is written. hex becomes #rrggbbaa when translucent. |
|
|
1930
|
+
| `alpha` | `boolean` | `true` | Show the alpha slider. |
|
|
1931
|
+
| `presets` | `string[]` | | Preset swatches as CSS colors (a listbox; arrow keys move). |
|
|
1932
|
+
| `showInput` | `boolean` | `true` | Show the text field (Enter or blur commits; invalid text reverts). |
|
|
1933
|
+
| `name / form` | `string` | | Submit the value with a form (hidden input). |
|
|
1934
|
+
| `disabled / readOnly / required` | `boolean` | | Like native controls. Works with <Field>. |
|
|
1935
|
+
| `aria-label` | `string` | | Names the picker when it is not inside a <Field>. |
|
|
1936
|
+
| `ColorPickerPopover.open / defaultOpen / onOpenChange` | `boolean / (open) => void` | | Popover state (plus every ColorPicker prop). |
|
|
1937
|
+
| `ColorPickerPopover.size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Trigger height 32 / 40 / 52px. |
|
|
1938
|
+
| `ColorPickerPopover.placement` | `Placement` | `'bottom-start'` | Where the popover opens. |
|
|
1939
|
+
|
|
1940
|
+
## Examples
|
|
1941
|
+
|
|
1942
|
+
### Inline with presets
|
|
1943
|
+
|
|
1944
|
+
```tsx
|
|
1945
|
+
const [color, setColor] = useState('#006bff')
|
|
1946
|
+
|
|
1947
|
+
<ColorPicker aria-label="Brand color" value={color} onValueChange={setColor}
|
|
1948
|
+
presets={['#0a0a0a', '#006bff', '#00a74a', '#ff7a00', '#e40014']} />
|
|
1949
|
+
```
|
|
1950
|
+
|
|
1951
|
+
### Popover in a form
|
|
1952
|
+
|
|
1953
|
+
```tsx
|
|
1954
|
+
<form>
|
|
1955
|
+
<ColorPickerPopover aria-label="Label color" name="labelColor" defaultValue="#00a74a" alpha={false} />
|
|
1956
|
+
</form>
|
|
1957
|
+
```
|
|
1958
|
+
|
|
1959
|
+
### Write rgb()
|
|
1960
|
+
|
|
1961
|
+
```tsx
|
|
1962
|
+
<ColorPicker aria-label="Overlay" defaultValue="rgb(0 0 0 / 0.4)" format="rgb" onValueCommit={save} />
|
|
1963
|
+
```
|
|
1964
|
+
|
|
1965
|
+
## Rules
|
|
1966
|
+
- One inner shape: area, swatch, presets and tracks share the panel-concentric squircle (panel lg radius − 12px inset).
|
|
1967
|
+
- Give it a name: `aria-label` or a surrounding <Field label>.
|
|
1968
|
+
- Save in `onValueCommit`, not `onValueChange` (which fires on every drag step).
|
|
1969
|
+
- Use `alpha={false}` when transparency makes no sense (labels, brand colors).
|
|
1970
|
+
|
|
1971
|
+
## Accessibility
|
|
1972
|
+
- 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.
|
|
1973
|
+
- Arrows step 1 (Shift 10), Page Up/Down step 10, Home/End jump. Presets are a listbox named by color ("vivid blue").
|
|
1974
|
+
|
|
1975
|
+
## DOM contract (for agents operating the page)
|
|
1976
|
+
|
|
1977
|
+
- Selector: `[data-sw="color-picker"], [data-sw="color-picker-popover"]`
|
|
1978
|
+
- `data-disabled`: present when disabled
|
|
1979
|
+
- `data-state (popover)`: 'open' | 'closed'
|
|
1980
|
+
- `aria-valuenow (thumbs)`: channel values
|
|
1981
|
+
- 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"].
|
|
1982
|
+
|
|
1983
|
+
Related: `input`, `popover`, `slider`
|
|
1984
|
+
|
|
1985
|
+
---
|
|
1986
|
+
|
|
1987
|
+
# FileInput
|
|
1988
|
+
|
|
1989
|
+
> Choose, drop or paste files; validate type, size and count; list them with remove; submit them with a form through a real file input.
|
|
1990
|
+
|
|
1991
|
+
Category: inputs · Status: beta · Slug: `file-input`
|
|
1992
|
+
|
|
1993
|
+
```tsx
|
|
1994
|
+
import { FileInput, formatFileSize } from '@peerproblem/sw3-ui'
|
|
1995
|
+
```
|
|
1996
|
+
|
|
1997
|
+
## When to use
|
|
1998
|
+
- Attachments, imports and uploads in a form.
|
|
1999
|
+
- Context files for an agent prompt (paste a screenshot, drop a CSV).
|
|
2000
|
+
|
|
2001
|
+
## Avoid
|
|
2002
|
+
- A bare `<input type="file">` — no drop, paste, validation or list.
|
|
2003
|
+
- Uploading inside this component. It only holds files; upload in your submit handler or `onValueChange`, and validate again on the server.
|
|
2004
|
+
- Only a drop zone with no button. Keep the built-in Browse button for keyboard and screen-reader users.
|
|
2005
|
+
|
|
2006
|
+
## Props
|
|
2007
|
+
|
|
2008
|
+
| Prop | Type | Default | Description |
|
|
2009
|
+
| --- | --- | --- | --- |
|
|
2010
|
+
| `accept` | `string \| string[]` | | Like the accept attribute: "image/*", ".pdf", "application/json". |
|
|
2011
|
+
| `multiple` | `boolean` | `false` | Hold more than one file. Without it a new file replaces the current one. |
|
|
2012
|
+
| `maxFiles` | `number` | | Most files held (counts files already held). Extra files are rejected with "too-many-files". |
|
|
2013
|
+
| `maxSize / minSize` | `number` | | Bytes per file. Rejected with "file-too-large" / "file-too-small". |
|
|
2014
|
+
| `validate` | `(file: File) => string \| null \| void` | | Your own check; return a reason to reject. Runs after the built-in checks. |
|
|
2015
|
+
| `value / defaultValue` | `File[]` | | Files, controlled or initial. A form reset returns to defaultValue. |
|
|
2016
|
+
| `onValueChange` | `(files: File[]) => void` | | Files added or removed. |
|
|
2017
|
+
| `onReject` | `(rejected: { file: File; reasons: string[] }[]) => void` | | Files that failed the checks, with every reason. |
|
|
2018
|
+
| `variant` | `'dropzone' \| 'button'` | `'dropzone'` | A drop area with a button, or just the button. |
|
|
2019
|
+
| `title / hint / buttonLabel` | `ReactNode` | | Drop-zone text. The hint is built from accept/maxSize/maxFiles by default. |
|
|
2020
|
+
| `showList` | `boolean` | `true` | Show the file list. |
|
|
2021
|
+
| `renderItem` | `(file: File, index: number) => ReactNode` | | Custom row content (remove button is added). |
|
|
2022
|
+
| `name / form / required / disabled` | `string / boolean` | | Native form behavior via a real <input type="file"> kept in sync. |
|
|
2023
|
+
| `aria-label` | `string` | | Names the control when it is not in a <Field>. |
|
|
2024
|
+
|
|
2025
|
+
## Examples
|
|
2026
|
+
|
|
2027
|
+
### Attachments in a form
|
|
2028
|
+
|
|
2029
|
+
```tsx
|
|
2030
|
+
<form method="post" encType="multipart/form-data">
|
|
2031
|
+
<FileInput name="attachments" aria-label="Attachments" multiple accept="image/*,.pdf" maxSize={5_000_000} maxFiles={4} />
|
|
2032
|
+
<Button type="submit">Send</Button>
|
|
2033
|
+
</form>
|
|
2034
|
+
```
|
|
2035
|
+
|
|
2036
|
+
### One file, button only
|
|
2037
|
+
|
|
2038
|
+
```tsx
|
|
2039
|
+
<FileInput variant="button" aria-label="Avatar" accept="image/png,image/jpeg" buttonLabel="Choose image"
|
|
2040
|
+
onValueChange={([file]) => setFile(file ?? null)} />
|
|
2041
|
+
```
|
|
2042
|
+
|
|
2043
|
+
### Custom validation
|
|
2044
|
+
|
|
2045
|
+
```tsx
|
|
2046
|
+
<FileInput multiple accept=".csv" aria-label="Datasets"
|
|
2047
|
+
validate={(f) => (f.name.includes(' ') ? 'no spaces in names' : null)}
|
|
2048
|
+
onReject={(r) => console.warn(r)} />
|
|
2049
|
+
```
|
|
2050
|
+
|
|
2051
|
+
## Rules
|
|
2052
|
+
- Dropzone shows a bare 20px icon (the dashed zone is the frame). File rows are sm squircles with a 1px frame; thumb and remove button are concentric with them.
|
|
2053
|
+
- Tell people the limits: keep the auto hint or write your own `hint`.
|
|
2054
|
+
- Validate on the server too; `accept` and `validate` are a convenience.
|
|
2055
|
+
- Rejected files are listed in red under the zone; do not add a second error message for them.
|
|
2056
|
+
|
|
2057
|
+
## Accessibility
|
|
2058
|
+
- The Browse button opens the picker; the drop zone also takes pastes while focus is inside it.
|
|
2059
|
+
- The list is one tab stop: arrows move between files, Delete/Backspace removes the focused one. Changes are announced in a polite live region.
|
|
2060
|
+
|
|
2061
|
+
## DOM contract (for agents operating the page)
|
|
2062
|
+
|
|
2063
|
+
- Selector: `[data-sw="file-input"]`
|
|
2064
|
+
- `data-dragging`: files over the zone
|
|
2065
|
+
- `data-drag-accept / data-drag-reject (on dropzone)`: whether the dragged files look acceptable
|
|
2066
|
+
- `data-invalid`: some files were rejected
|
|
2067
|
+
- `data-disabled`: disabled
|
|
2068
|
+
- How to operate: Agent bridge: clear(), remove(fileName), add(files), open(); items = held files (name + size). DOM: set files on the inner input[type=file] and dispatch "change"; remove with [data-sw="file-input-item-remove"].
|
|
2069
|
+
|
|
2070
|
+
Related: `field`, `input`, `image-cropper`
|
|
2071
|
+
|
|
2072
|
+
---
|
|
2073
|
+
|
|
2074
|
+
# ImageCropper
|
|
2075
|
+
|
|
2076
|
+
> Move and resize a crop over an image (or pan and zoom the image under a fixed frame) with pointer and keyboard; the crop is {x, y, width, height} in image pixels, and cropImage() turns it into a Blob.
|
|
2077
|
+
|
|
2078
|
+
Category: inputs · Status: beta · Slug: `image-cropper`
|
|
2079
|
+
|
|
2080
|
+
```tsx
|
|
2081
|
+
import { ImageCropper, cropImage, type CropRect } from '@peerproblem/sw3-ui'
|
|
2082
|
+
```
|
|
2083
|
+
|
|
2084
|
+
## When to use
|
|
2085
|
+
- Avatar and cover-image editors.
|
|
2086
|
+
- Cropping a screenshot before attaching it.
|
|
2087
|
+
- Choosing a region of an image to send to a vision model.
|
|
2088
|
+
|
|
2089
|
+
## Avoid
|
|
2090
|
+
- Cropping with CSS `object-position` and calling it saved — the file is unchanged. Use `cropImage(src, crop)` and upload the Blob.
|
|
2091
|
+
- Cross-origin images without CORS headers: the canvas is tainted and cropImage fails. Use object URLs or same-origin images.
|
|
2092
|
+
|
|
2093
|
+
## Props
|
|
2094
|
+
|
|
2095
|
+
| Prop | Type | Default | Description |
|
|
2096
|
+
| --- | --- | --- | --- |
|
|
2097
|
+
| `src` * | `string` | | Image URL (an object URL for a picked file works well). |
|
|
2098
|
+
| `alt` | `string` | | Describes the image. |
|
|
2099
|
+
| `crop / defaultCrop` | `{ x: number; y: number; width: number; height: number }` | | The crop in image pixels. Starts at 4/5 of the largest crop at the ratio, centered. |
|
|
2100
|
+
| `onCropChange` | `(crop: CropRect) => void` | | Every drag step, key or wheel tick, and once the image loads. |
|
|
2101
|
+
| `onCropCommit` | `(crop: CropRect) => void` | | Once an interaction ends. Save here. |
|
|
2102
|
+
| `mode` | `'box' \| 'frame'` | `'box'` | box: move/resize a selection. frame: the selection stays put, drag/wheel pans and zooms the image (avatar editor). |
|
|
2103
|
+
| `aspectRatio` | `number` | | Lock width/height, e.g. 1 or 16 / 9. Defaults to 1 in frame mode. |
|
|
2104
|
+
| `shape` | `'rect' \| 'circle'` | `'rect'` | circle rounds the selection; pass shape to cropImage too. |
|
|
2105
|
+
| `minWidth / minHeight` | `number` | `16` | Smallest crop in image px. |
|
|
2106
|
+
| `maxZoom` | `number` | `4` | Largest zoom (1 = largest crop the image allows). |
|
|
2107
|
+
| `grid` | `boolean` | `true` | Rule-of-thirds lines. |
|
|
2108
|
+
| `zoomControl` | `boolean` | `true` | Zoom slider under the image. |
|
|
2109
|
+
| `height` | `number` | `320` | Viewport height in px (width fills the container). |
|
|
2110
|
+
| `disabled` | `boolean` | | Stops every change. |
|
|
2111
|
+
| `children` | `ReactNode` | | Extra toolbar controls next to the zoom slider (e.g. a Crop button). |
|
|
2112
|
+
| `cropImage(src, rect, { type?, quality?, shape?, width? })` | `Promise<Blob>` | | Canvas helper: crops (and optionally rounds/resizes) to a Blob. Browser only. |
|
|
2113
|
+
|
|
2114
|
+
## Examples
|
|
2115
|
+
|
|
2116
|
+
### Square crop and save
|
|
2117
|
+
|
|
2118
|
+
```tsx
|
|
2119
|
+
const [crop, setCrop] = useState<CropRect>()
|
|
2120
|
+
|
|
2121
|
+
<ImageCropper src={url} alt="Profile photo" aspectRatio={1} crop={crop} onCropChange={setCrop}>
|
|
2122
|
+
<Button size="sm" onClick={async () => upload(await cropImage(url, crop!, { width: 256 }))}>Save</Button>
|
|
2123
|
+
</ImageCropper>
|
|
2124
|
+
```
|
|
2125
|
+
|
|
2126
|
+
### Avatar editor (frame mode)
|
|
2127
|
+
|
|
2128
|
+
```tsx
|
|
2129
|
+
<ImageCropper src={url} alt="" mode="frame" shape="circle" onCropCommit={setCrop} />
|
|
2130
|
+
// later: cropImage(url, crop, { shape: 'circle', width: 128 })
|
|
2131
|
+
```
|
|
2132
|
+
|
|
2133
|
+
## Rules
|
|
2134
|
+
- Keep the crop in state from onCropChange (or onCropCommit) and pass it to cropImage; never measure the DOM.
|
|
2135
|
+
- Use frame mode + circle for avatars, box mode for free-form crops.
|
|
2136
|
+
|
|
2137
|
+
## Accessibility
|
|
2138
|
+
- The cropper is a group. The selection and each handle are sliders announcing "W by H pixels, at X, Y".
|
|
2139
|
+
- Arrows move the selection (on a handle: its edges); Shift moves 10×; + / − zoom; Escape during a drag restores the crop.
|
|
2140
|
+
|
|
2141
|
+
## DOM contract (for agents operating the page)
|
|
2142
|
+
|
|
2143
|
+
- Selector: `[data-sw="image-cropper"]`
|
|
2144
|
+
- `data-status`: 'loading' | 'ready' | 'error'
|
|
2145
|
+
- `data-dragging`: pointer drag in progress
|
|
2146
|
+
- `data-mode`: 'box' | 'frame'
|
|
2147
|
+
- `data-shape`: 'rect' | 'circle'
|
|
2148
|
+
- How to operate: Agent bridge: setCrop({x,y,width,height}) (also setValue), setZoom(n), reset(); state has crop, zoom and image size. DOM: focus [data-sw="image-cropper-selection"] and press arrow keys.
|
|
2149
|
+
|
|
2150
|
+
Related: `file-input`, `avatar`
|
|
2151
|
+
|
|
2152
|
+
---
|