@peerproblem/sw3-ui 0.0.0-stage → 0.3.0

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