@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,1749 @@
1
+ # SW3 UI SDK · Actions, layout and display
2
+
3
+ > Buttons, toolbars, cards, accordions, scroll areas, badges, stats, tables, progress, toasts and other building blocks.
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
+ # Button
14
+
15
+ > A squircle button with press motion. Ink, app-brandable accent and quiet variants.
16
+
17
+ Category: actions · Status: stable · Slug: `button`
18
+
19
+ ```tsx
20
+ import { Button, ArrowIcon, Icon, Tooltip } from '@peerproblem/sw3-ui'
21
+ ```
22
+
23
+ ## When to use
24
+ - Any action the user triggers.
25
+ - Pairs of hero CTAs: `size="xl"` primary + accent side by side.
26
+ - Navigation styled as a button: pass `href`.
27
+
28
+ ## Avoid
29
+ - More than one `accent` button in the same view — accent is the single most important action.
30
+ - Icon-only buttons without `aria-label`.
31
+ - Custom border-radius CSS — use `radius`, so the squircle stays consistent.
32
+
33
+ ## Props
34
+
35
+ | Prop | Type | Default | Description |
36
+ | --- | --- | --- | --- |
37
+ | `size` | `'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Heights 20 / 28 / 32 / 40 / 52 / 80px. Use 2xs for row actions and xs for header and toolbar controls. Ghost icon buttons at these sizes use a muted icon that turns ink on hover. xl is the poster-scale hero CTA. |
38
+ | `variant` | `'primary' \| 'accent' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | primary = ink fill, accent = app accent fill (ink by default), secondary = muted fill, outline = framed, ghost = text only. |
39
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `per size: xs / sm / md / lg` | Squircle corner radius (token or px). |
40
+ | `smoothing` | `'none' \| 'soft' \| 'max' \| number` | `'soft' (0.6)` | Corner smoothing from 0 to 1. SW3 uses 0.6 by default. |
41
+ | `leading` | `ReactNode` | | Icon before the label. |
42
+ | `trailing` | `ReactNode` | | Icon after the label. Use <ArrowIcon/> for forward actions. |
43
+ | `iconOnly` | `boolean` | `false` | Opt into a square layout for one icon passed through `leading` or `trailing`. Supply an accessible name. Visible children and `fullWidth` use the regular layout. |
44
+ | `loading` | `boolean` | `false` | Shows a spinner and disables the button. |
45
+ | `fullWidth` | `boolean` | `false` | Stretch to the container width. |
46
+ | `href` | `string` | | Render as an <a> link with button styling. |
47
+ | `data-sw-confirm` | `presence attribute` | | Require app confirmation before agent activation. |
48
+ | `...rest` | `HTMLMotionProps<"button">` | | Any button or motion prop (onClick, disabled, type, whileHover…). |
49
+
50
+ ## Examples
51
+
52
+ ### Variants
53
+
54
+ ```tsx
55
+ <Button>Save</Button>
56
+ <Button variant="secondary">Cancel</Button>
57
+ <Button variant="outline">Preview</Button>
58
+ <Button variant="ghost">Skip</Button>
59
+ ```
60
+
61
+ ### Hero CTA pair
62
+
63
+ ```tsx
64
+ <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
65
+ <Button size="xl" href="/docs" trailing={<ArrowIcon />}>Read the Docs</Button>
66
+ <Button size="xl" variant="outline" onClick={copyPrompt}>Copy prompt</Button>
67
+ </div>
68
+ ```
69
+
70
+ ### Brand accent
71
+
72
+ ```tsx
73
+ <div className="brand-accent">
74
+ {/* Set the app’s accent tokens on this wrapper. See the Color guide. */}
75
+ <Button variant="accent">Publish</Button>
76
+ </div>
77
+ ```
78
+
79
+ ### Loading
80
+
81
+ ```tsx
82
+ <Button loading>Deploying</Button>
83
+ ```
84
+
85
+ ### Text with an icon
86
+
87
+ ```tsx
88
+ <Button variant="secondary" leading={<Icon name="copy" />} onClick={copyLink}>Copy link</Button>
89
+ ```
90
+
91
+ ### Compact copy action
92
+
93
+ ```tsx
94
+ <Tooltip content="Copy code">
95
+ <Button size="sm" variant="ghost" iconOnly aria-label="Copy code" leading={<Icon name="copy" />} onClick={copyCode} />
96
+ </Tooltip>
97
+ ```
98
+
99
+ ## Rules
100
+ - Dense icon actions are `<Button size="2xs" variant="ghost" iconOnly aria-label>` (in rows) or `size="xs"` (in headers and toolbars), wrapped in a Tooltip. In a Listbox, pass row actions as data and let it render them. Do not hand-roll small icon buttons.
101
+ - Labels are verbs in sentence case ("Save changes", not "SAVE").
102
+ - One accent button per view; everything else primary/secondary/ghost.
103
+ - Use `secondary` for a quiet fill without a frame. Set `--sw-button-secondary-bg` on an ancestor when the default fill is too close to the surrounding surface.
104
+ - Choose the label for the context. Use text for primary, unfamiliar or ambiguous actions. Add an icon when it helps users recognize the action. Use an icon alone for familiar utility actions with clear context, such as copying a code block.
105
+ - Pair icon-only actions with an accessible name and a tooltip. For copy actions, keep the name stable, show a check icon after success, and announce the result through a status region.
106
+
107
+ ## Accessibility
108
+ - Renders a native <button type="button"> (or <a> with href).
109
+ - Focus shows a 2px accent squircle ring outside the shape.
110
+
111
+ ## DOM contract (for agents operating the page)
112
+
113
+ - Selector: `[data-sw="button"]`
114
+ - `data-variant`: variant name
115
+ - `data-size`: size
116
+ - `data-icon-only`: present for square icon buttons
117
+ - `data-loading`: present while loading
118
+ - `disabled`: native disabled attribute
119
+ - How to operate: Click the button by its accessible name, including aria-label on icon-only actions.
120
+
121
+ Related: `card`
122
+
123
+ ---
124
+
125
+ # Card
126
+
127
+ > A squircle surface with a 1px frame. Plain by design: no background patterns, no hover movement.
128
+
129
+ Category: layout · Status: stable · Slug: `card`
130
+
131
+ ```tsx
132
+ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@peerproblem/sw3-ui'
133
+ ```
134
+
135
+ ## When to use
136
+ - Grouping related content.
137
+ - Dashboard tiles and settings sections.
138
+ - A clickable tile: set `interactive` and `onClick`.
139
+
140
+ ## Avoid
141
+ - Cards inside cards more than one level deep.
142
+ - Shadows — the system uses 1px frames, not elevation.
143
+ - Setting border-radius in CSS (breaks the squircle).
144
+ - Background decoration (grids, dots, hatching) or hover lift/scale on cards — keep surfaces quiet.
145
+ - Fixed or min heights — let a card be as tall as its content.
146
+
147
+ ## Props
148
+
149
+ | Prop | Type | Default | Description |
150
+ | --- | --- | --- | --- |
151
+ | `title` | `ReactNode` | | Turns on the panel layout: a 40px header bar (6px inset + 28px trigger), then toolbar, body and footer. Use it for every dashboard tile, side panel and list box. |
152
+ | `count / icon / actions` | `ReactNode` | | Header bar pieces. Actions are xs/2xs ghost Buttons, a Menu trigger, or `Pagination variant="compact"`. |
153
+ | `toolbar` | `ReactNode` | | A row under the header, usually `<Toolbar variant="plain" size="sm">` with a ToolbarInput and a sort Menu. |
154
+ | `footer` | `ReactNode` | | A pinned row under the body, with a line above it. |
155
+ | `collapsible / open / defaultOpen / onOpenChange` | `boolean` | | The header folds the card down to its header bar. The count stays visible. |
156
+ | `framed` | `boolean` | | Default: true, or false inside a container that already draws the frame (a joined DashboardGrid, an Accordion, another panel Card). |
157
+ | `padding (panel layout)` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'sm'` | Body padding of 0, 12, 16 or 24px. The header inset follows it, so the title and body text share one line. Use 'none' for lists that reach the edges. |
158
+ | `variant` | `'surface' \| 'muted' \| 'inverse' \| 'ghost'` | `'surface'` | surface = white + frame, muted = grey well, inverse = ink, ghost = no fill. |
159
+ | `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 16 / 24 / 40px. |
160
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'lg' (20px)` | Squircle corner radius (token or px). |
161
+ | `smoothing` | `'none' \| 'soft' \| 'max' \| number` | `'soft' (0.6)` | Corner smoothing from 0 to 1. SW3 uses 0.6 by default. |
162
+ | `bordered` | `boolean` | `true (false for ghost)` | Draw the 1px frame. |
163
+ | `href / target / rel` | `anchor attributes` | | Give the card a native link without intercepting nested controls. |
164
+ | `interactive` | `boolean` | `false` | Whole card clickable: pointer cursor, frame darkens on hover, focus ring. The card never moves. Clicks on controls or on any SW3 component inside it (including its empty space) stay with that component; drags never click. |
165
+ | `clipContent` | `boolean` | `false` | Clip children to the squircle (edge-to-edge images, maps). |
166
+
167
+ ## Examples
168
+
169
+ ### Basic
170
+
171
+ ```tsx
172
+ <Card>
173
+ <CardHeader>
174
+ <CardTitle>Weekly digest</CardTitle>
175
+ <CardDescription>A summary of your week, every Monday.</CardDescription>
176
+ </CardHeader>
177
+ <CardFooter>
178
+ <Button size="sm">Subscribe</Button>
179
+ </CardFooter>
180
+ </Card>
181
+ ```
182
+
183
+ ### Hero poster
184
+
185
+ ```tsx
186
+ <Card padding="lg" radius="xl">
187
+ <Display size="md">Behaviors, <Outline>not</Outline> widgets.</Display>
188
+ </Card>
189
+ ```
190
+
191
+ ## Rules
192
+ - Dashboard tiles and side panels are Cards with `title`. Do not stack framed Cards inside a panel Card: they unframe themselves, so group with an Accordion instead.
193
+ - Use `canvas` (page) behind cards and `background` inside them; never put a card on a white page without the canvas.
194
+ - Keep 12–16px gaps between cards in a grid.
195
+
196
+ ## DOM contract (for agents operating the page)
197
+
198
+ - Selector: `[data-sw="card"]`
199
+ - `data-variant`: variant
200
+ - `data-interactive`: present when clickable
201
+
202
+ Related: `poster-card`, `chart-card`
203
+
204
+ ---
205
+
206
+ # Badge
207
+
208
+ > A small pill label for status, counts and tags.
209
+
210
+ Category: display · Status: stable · Slug: `badge`
211
+
212
+ ```tsx
213
+ import { Badge } from '@peerproblem/sw3-ui'
214
+ ```
215
+
216
+ ## When to use
217
+ - Status (Live, Advisory, Draft, Failed).
218
+ - Version and release labels.
219
+
220
+ ## Avoid
221
+ - Using badges as buttons.
222
+ - Sentences inside badges.
223
+
224
+ ## Props
225
+
226
+ | Prop | Type | Default | Description |
227
+ | --- | --- | --- | --- |
228
+ | `variant` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'outline' \| 'inverse'` | `'neutral'` | Color. Use warning for a status that needs attention. |
229
+ | `leading` | `ReactNode` | | Optional decorative icon before the label. |
230
+ | `pulse` | `boolean` | `false` | Decorative status dot. Static when reduced motion is enabled. |
231
+ | `dot` | `boolean` | `false` | Deprecated. Use leading. Existing success, warning and danger badges use a corresponding status icon. |
232
+ | `mono` | `boolean` | `false` | Opt in to uppercase monospace lettering. Standard badges preserve the original text case. |
233
+
234
+ ## Examples
235
+
236
+ ### Status
237
+
238
+ ```tsx
239
+ import { Badge, Icon } from '@peerproblem/sw3-ui'
240
+
241
+ <Badge variant="success" leading={<Icon name="check" weight={2} />}>Live</Badge>
242
+ <Badge variant="warning" leading={<Icon name="alert" weight={2} />}>Advisory</Badge>
243
+ <Badge variant="outline">Draft</Badge>
244
+ <Badge variant="inverse">v0.1</Badge>
245
+ ```
246
+
247
+ ## Rules
248
+ - Use a leading icon when it helps identify the status. Leave simple labels and version numbers as text.
249
+
250
+ ## Accessibility
251
+ - Use visible child text to communicate the status. The optional decorative icon is hidden from screen readers.
252
+
253
+ ## DOM contract (for agents operating the page)
254
+
255
+ - Selector: `[data-sw="badge"]`
256
+ - `data-variant`: variant
257
+
258
+ ---
259
+
260
+ # Stat
261
+
262
+ > A KPI: mono label, big tabular number, colored delta, optional sparkline.
263
+
264
+ Category: display · Status: stable · Slug: `stat`
265
+
266
+ ```tsx
267
+ import { Stat } from '@peerproblem/sw3-ui'
268
+ import { Sparkline } from '@peerproblem/sw3-ui/charts'
269
+ ```
270
+
271
+ ## When to use
272
+ - Dashboard headline numbers.
273
+ - Map or chart overlays.
274
+
275
+ ## Avoid
276
+ - More than 4–5 stats in a row.
277
+
278
+ ## Props
279
+
280
+ | Prop | Type | Default | Description |
281
+ | --- | --- | --- | --- |
282
+ | `size` | `'sm' \| 'md'` | `'md'` | md is the poster KPI (mono caps label, 32px number). sm is the dashboard metric: a sentence-case 13px label, a 24px tabular number, a tinted delta pill and no warning badge, so cells keep one height. |
283
+ | `caption` | `ReactNode` | | Context under the number, e.g. "vs last week". |
284
+ | `label` * | `ReactNode` | | Short name, rendered mono uppercase. |
285
+ | `value` * | `ReactNode` | | Pre-formatted number, e.g. "12.4k". |
286
+ | `delta` | `string` | | e.g. "+8%". A leading "-" makes it red. |
287
+ | `trend` | `'up' \| 'down' \| 'flat'` | | Override delta color. |
288
+ | `tone` | `'neutral' \| 'warning' \| 'success' \| 'danger'` | `'neutral'` | Colors the value independently of delta. Warning also shows a text badge. |
289
+ | `warningLabel` | `string` | `Warning` | Visible text for a warning, with support for translation or a more specific status. |
290
+ | `children` | `ReactNode` | | Visual under the number (Sparkline). |
291
+
292
+ ## Examples
293
+
294
+ ### With sparkline
295
+
296
+ ```tsx
297
+ <Stat label="Visitors" value="12.4k" delta="+8%">
298
+ <Sparkline data={[4, 8, 6, 9, 12, 10, 14]} />
299
+ </Stat>
300
+ ```
301
+
302
+ ### Capacity warning
303
+
304
+ ```tsx
305
+ <Stat label="Shelter occupancy" value="92%" delta="+8 pp" trend="up" tone="warning" warningLabel="Near capacity" />
306
+ ```
307
+
308
+ ## Rules
309
+ - A dashboard KPI row is `<Tabs variant="metric">` with one `<Stat size="sm">` per tab. The panel plots the chosen metric with a TrendChart. Do not add a spark under every number.
310
+
311
+ ## Accessibility
312
+ - Give warnings meaningful visible text so the status is readable without color. The delta keeps its own trend.
313
+
314
+ ## DOM contract (for agents operating the page)
315
+
316
+ - Selector: `[data-sw="stat"]`
317
+ - `data-tone`: neutral | warning | success | danger
318
+
319
+ ---
320
+
321
+ # Toggle / ToggleGroup
322
+
323
+ > A button that stays pressed (aria-pressed). ToggleGroup is a row of them for toolbars and filters: several on at once, or one that can be cleared. One tab stop, arrow-key focus.
324
+
325
+ Category: actions · Status: beta · Slug: `toggle`
326
+
327
+ ```tsx
328
+ import { Toggle, ToggleGroup } from '@peerproblem/sw3-ui'
329
+ ```
330
+
331
+ ## When to use
332
+ - Formatting buttons in a Toolbar (bold, italic, text alignment).
333
+ - Turning tools or filters on and off in place (`multiple`).
334
+ - Highlighting one item that can also be cleared.
335
+
336
+ ## Avoid
337
+ - Picking one value or view that always has a value (Week / Month, grid / list) — use SegmentedControl. checkDesign reports `toggle-group-choice`.
338
+ - Settings with a label and description — use Switch.
339
+ - Navigation between pages — use Tabs or links.
340
+ - Icon-only toggles without `aria-label`.
341
+
342
+ ## Props
343
+
344
+ | Prop | Type | Default | Description |
345
+ | --- | --- | --- | --- |
346
+ | `pressed` | `boolean` | | Controlled state (standalone). |
347
+ | `defaultPressed` | `boolean` | `false` | Initial state. |
348
+ | `onPressedChange` | `(pressed: boolean) => void` | | Called on press. |
349
+ | `value` | `string` | | Identifies it inside a ToggleGroup. |
350
+ | `icon` | `ReactNode` | | Icon before the label; alone it makes a square icon toggle. |
351
+ | `variant` | `'ghost' \| 'outline'` | `'ghost'` | outline adds a 1px frame at rest. On a ToggleGroup, outline frames the track. |
352
+ | `radius` | `RadiusToken \| number` | | Corner radius. In a group, items default to the concentric track radius − 3px. |
353
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 30 / 36 / 44px. |
354
+ | `ToggleGroup.value` | `string[]` | | Pressed values (controlled). |
355
+ | `ToggleGroup.defaultValue` | `string[]` | `[]` | Initial pressed values. |
356
+ | `ToggleGroup.onValueChange` | `(value: string[]) => void` | | Called on any press. |
357
+ | `ToggleGroup.multiple` | `boolean` | `false` | Allow several pressed at once. |
358
+ | `ToggleGroup.deselectable` | `boolean` | `true` | Single mode: pressing the pressed one releases it. |
359
+ | `ToggleGroup.items` | `{ value, label?, icon?, disabled?, 'aria-label'? }[]` | | Shorthand. |
360
+ | `ToggleGroup.radius` | `RadiusToken \| number` | `'sm'` | Track radius. |
361
+ | `ToggleGroup.orientation / loop / disabled / name` | `'horizontal' \| 'vertical' / boolean / boolean / string` | | Keys, wrapping, state, form name. |
362
+
363
+ ## Examples
364
+
365
+ ### Standalone
366
+
367
+ ```tsx
368
+ <Toggle icon={<Icon name="star" />} aria-label="Pin run" />
369
+ ```
370
+
371
+ ### Multiple
372
+
373
+ ```tsx
374
+ <ToggleGroup multiple aria-label="Sources" value={sources} onValueChange={setSources}>
375
+ <Toggle value="web">Web</Toggle>
376
+ <Toggle value="docs">Docs</Toggle>
377
+ <Toggle value="code">Code</Toggle>
378
+ </ToggleGroup>
379
+ ```
380
+
381
+ ## Rules
382
+ - Pressed items use the foreground as a solid fill and the background for icons and labels. Unpressed hover keeps a quiet fill or emphasizes the label.
383
+ - A ToggleGroup keeps a muted track behind the items. Use SegmentedControl when exactly one option must always be chosen.
384
+
385
+ ## Accessibility
386
+ - Native <button aria-pressed>. Group is role="group" with one tab stop; Arrow/Home/End move focus; Space/Enter press. Disabled toggles in a group stay focusable with aria-disabled.
387
+
388
+ ## DOM contract (for agents operating the page)
389
+
390
+ - Selector: `[data-sw="toggle"]`
391
+ - `aria-pressed`: true when pressed
392
+ - `data-state`: on | off
393
+ - `data-value`: value in a group
394
+ - How to operate: Click it. Agent bridge (toggle): toggle(), setChecked(bool). Group [data-sw="toggle-group"]: setValue(values[]), toggle(value), select(value), clear(); items = toggles.
395
+
396
+ Related: `segmented-control`, `switch`
397
+
398
+ ---
399
+
400
+ # Separator
401
+
402
+ > A 1px hairline between groups of content, horizontal or vertical, optionally with a mono caption ("OR").
403
+
404
+ Category: layout · Status: beta · Slug: `separator`
405
+
406
+ ```tsx
407
+ import { Separator } from '@peerproblem/sw3-ui'
408
+ ```
409
+
410
+ ## When to use
411
+ - Dividing sections of a panel, menu or toolbar.
412
+ - "or" between alternative sign-in methods: `label="or"`.
413
+
414
+ ## Avoid
415
+ - Separating every list row — use spacing.
416
+ - Decorative lines announced to screen readers — set `decorative`.
417
+
418
+ ## Props
419
+
420
+ | Prop | Type | Default | Description |
421
+ | --- | --- | --- | --- |
422
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical needs a flex row parent. |
423
+ | `decorative` | `boolean` | `false` | role="none" — skip it for assistive tech. |
424
+ | `label` | `ReactNode` | | Caption in the middle (horizontal only). |
425
+ | `tone` | `'hairline' \| 'frame'` | `'hairline'` | Line strength. |
426
+
427
+ ## Examples
428
+
429
+ ### Between sections
430
+
431
+ ```tsx
432
+ <Separator />
433
+ ```
434
+
435
+ ### Or
436
+
437
+ ```tsx
438
+ <Button fullWidth>Continue with GitHub</Button>
439
+ <Separator label="or" decorative />
440
+ <Input label="Email" />
441
+ ```
442
+
443
+ ### Vertical
444
+
445
+ ```tsx
446
+ <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
447
+ <span>Docs</span><Separator orientation="vertical" /><span>API</span>
448
+ </div>
449
+ ```
450
+
451
+ ## Accessibility
452
+ - role="separator" with aria-orientation when vertical; never focusable.
453
+
454
+ ## DOM contract (for agents operating the page)
455
+
456
+ - Selector: `[data-sw="separator"]`
457
+ - `data-orientation`: horizontal | vertical
458
+
459
+ Related: `card`
460
+
461
+ ---
462
+
463
+ # Meter
464
+
465
+ > A value in a known range (storage, quota, score), coloured good / so-so / bad from low, high and optimum like a native <meter>.
466
+
467
+ Category: display · Status: beta · Slug: `meter`
468
+
469
+ ```tsx
470
+ import { Meter } from '@peerproblem/sw3-ui'
471
+ ```
472
+
473
+ ## When to use
474
+ - Usage against a limit: tokens, storage, seats.
475
+ - A score where some range is better than others.
476
+
477
+ ## Avoid
478
+ - Task progress over time — use Progress.
479
+ - Colour without a label — always pass `label` (or aria-label) and keep showValue.
480
+
481
+ ## Props
482
+
483
+ | Prop | Type | Default | Description |
484
+ | --- | --- | --- | --- |
485
+ | `value` * | `number` | | The reading. |
486
+ | `min / max` | `number` | `0 / 100` | Range. |
487
+ | `low / high` | `number` | | Region boundaries. |
488
+ | `optimum` | `number` | | Best value. Without low/high/optimum the bar is neutral ink. Regions colour as --sw-success / --sw-warning / --sw-danger. |
489
+ | `label` | `ReactNode` | | Visible name. |
490
+ | `showValue` | `boolean` | `true` | Formatted value at the right. |
491
+ | `formatOptions` | `Intl.NumberFormatOptions` | `{ style: 'percent' }` | Percent shows position in the range; other styles format the value (e.g. unit: gigabyte). |
492
+ | `locale` | `string` | | Formatting locale. |
493
+ | `getValueLabel` | `(value, formatted) => string` | | Screen-reader text, e.g. "42 of 50 GB". |
494
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Bar 4 / 6 / 10px. |
495
+
496
+ ## Examples
497
+
498
+ ### Quota (lower is better)
499
+
500
+ ```tsx
501
+ <Meter label="Token budget" value={82} low={60} high={90} optimum={0} />
502
+ ```
503
+
504
+ ### Units
505
+
506
+ ```tsx
507
+ <Meter label="Storage" value={42} max={50} formatOptions={{ style: 'unit', unit: 'gigabyte' }}
508
+ getValueLabel={(v) => `${v} of 50 GB used`} />
509
+ ```
510
+
511
+ ## Accessibility
512
+ - role="meter" with aria-valuenow/min/max/valuetext; named by its label.
513
+
514
+ ## DOM contract (for agents operating the page)
515
+
516
+ - Selector: `[data-sw="meter"]`
517
+ - `aria-valuenow`: clamped value
518
+ - `data-state`: neutral | optimum | suboptimum | critical
519
+ - How to operate: Read-only. Agent bridge state: value, min, max, state.
520
+
521
+ Related: `progress`, `stat`
522
+
523
+ ---
524
+
525
+ # Progress
526
+
527
+ > Task progress: a bar that fills as work completes (determinate) or slides while the amount is unknown (`value={null}`).
528
+
529
+ Category: display · Status: beta · Slug: `progress`
530
+
531
+ ```tsx
532
+ import { Progress } from '@peerproblem/sw3-ui'
533
+ ```
534
+
535
+ ## When to use
536
+ - Uploads, imports, agent runs with known steps.
537
+ - Work under way with unknown duration: `value={null}`.
538
+
539
+ ## Avoid
540
+ - A static quantity in a range — use Meter.
541
+ - Very short waits (<1s) — show nothing or a spinner on the button.
542
+
543
+ ## Props
544
+
545
+ | Prop | Type | Default | Description |
546
+ | --- | --- | --- | --- |
547
+ | `value` * | `number \| null` | | How far along; null = indeterminate. |
548
+ | `min / max` | `number` | `0 / 100` | Range. |
549
+ | `label` | `ReactNode` | | What is happening ("Indexing docs"). |
550
+ | `showValue` | `boolean` | `true` | Formatted value at the right (hidden while indeterminate). |
551
+ | `formatOptions` | `Intl.NumberFormatOptions` | `{ style: 'percent' }` | Value format. |
552
+ | `locale` | `string` | | Formatting locale. |
553
+ | `getValueLabel` | `(value \| null, formatted) => string` | | Screen-reader text, e.g. "3 of 12 files". |
554
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Bar 4 / 6 / 10px. |
555
+
556
+ ## Examples
557
+
558
+ ### Determinate
559
+
560
+ ```tsx
561
+ <Progress label="Indexing docs" value={64} />
562
+ ```
563
+
564
+ ### Steps
565
+
566
+ ```tsx
567
+ <Progress label="Uploading" value={3} max={12} formatOptions={{ style: 'decimal' }}
568
+ getValueLabel={(v) => `${v} of 12 files`} />
569
+ ```
570
+
571
+ ### Indeterminate
572
+
573
+ ```tsx
574
+ <Progress label="Waiting for the agent" value={null} />
575
+ ```
576
+
577
+ ## Accessibility
578
+ - role="progressbar"; aria-valuenow is omitted while indeterminate; aria-busy until complete.
579
+
580
+ ## DOM contract (for agents operating the page)
581
+
582
+ - Selector: `[data-sw="progress"]`
583
+ - `data-state`: loading | indeterminate | complete
584
+ - `aria-valuenow`: current value
585
+ - How to operate: Read-only. Agent bridge state: value, min, max, state.
586
+
587
+ Related: `meter`
588
+
589
+ ---
590
+
591
+ # Skeleton
592
+
593
+ > A static squircle placeholder that reserves space while content loads.
594
+
595
+ Category: display · Status: beta · Slug: `skeleton`
596
+
597
+ ```tsx
598
+ import { Skeleton } from '@peerproblem/sw3-ui'
599
+ ```
600
+
601
+ ## When to use
602
+ - Reserving space for text, images, or rows while a region loads.
603
+
604
+ ## Avoid
605
+ - Communicating progress or loading status through decorative shapes alone.
606
+
607
+ ## Props
608
+
609
+ | Prop | Type | Default | Description |
610
+ | --- | --- | --- | --- |
611
+ | `width` | `CSSProperties['width']` | `'100%'` | Width in CSS units or pixels. |
612
+ | `height` | `CSSProperties['height']` | `'1em' or '0.7em' inline` | Height in CSS units or pixels. |
613
+ | `inline` | `boolean` | `false` | Use inside the final Heading or Text so line height and spacing come from the same typography. |
614
+ | `radius` | `RadiusValue` | `'xs'` | Squircle radius token or pixels. |
615
+ | `className` | `string` | | Additional class names. |
616
+ | `style` | `CSSProperties` | | Additional inline styles. |
617
+
618
+ ## Examples
619
+
620
+ ### Loading a summary
621
+
622
+ ```tsx
623
+ <>
624
+ <p role="status">{loading ? 'Loading summary…' : 'Summary loaded.'}</p>
625
+ <section aria-label="Summary" aria-busy={loading}>
626
+ <Heading as="h3" size="sm" aria-hidden={loading || undefined}>
627
+ {loading ? <Skeleton inline width="8ch" /> : title}
628
+ </Heading>
629
+ <Text size="sm">{loading ? <Skeleton inline width="22ch" /> : summary}</Text>
630
+ </section>
631
+ </>
632
+ ```
633
+
634
+ ## Rules
635
+ - Keep typography, gaps and padding shared between loading and loaded content.
636
+ - Use inline placeholders for text and reserve the expected number of lines for content that wraps.
637
+
638
+ ## Accessibility
639
+ - Placeholders are decorative, always aria-hidden, and stay out of the tab order.
640
+ - Set aria-busy on the affected region. Keep one persistent role="status" element outside that region for loading and completion announcements.
641
+
642
+ ## DOM contract (for agents operating the page)
643
+
644
+ - Selector: `[data-sw="skeleton"]`
645
+ - `aria-hidden`: true
646
+ - How to operate: Decorative placeholder with no agent action.
647
+
648
+ Related: `progress`, `squircle`
649
+
650
+ ---
651
+
652
+ # EmptyState
653
+
654
+ > A heading and optional action for a view with no content to display.
655
+
656
+ Category: display · Status: beta · Slug: `empty-state`
657
+
658
+ ```tsx
659
+ import { EmptyState } from '@peerproblem/sw3-ui'
660
+ ```
661
+
662
+ ## When to use
663
+ - A completed search with no results or a list with no items.
664
+
665
+ ## Avoid
666
+ - Content that is still loading or failed to load.
667
+
668
+ ## Props
669
+
670
+ | Prop | Type | Default | Description |
671
+ | --- | --- | --- | --- |
672
+ | `title` * | `string` | | Heading that describes the empty result. |
673
+ | `description` | `string` | | Optional context or a brief next step. |
674
+ | `icon` | `ReactNode` | | Optional decorative icon. |
675
+ | `action` | `ReactNode` | | One optional button or link. |
676
+ | `headingLevel` | `2 \| 3 \| 4` | `3` | Native heading level. Match the surrounding outline. |
677
+ | `…div attributes` | `HTMLAttributes<HTMLDivElement>` | | Attributes such as className, style, and id apply to the root. |
678
+
679
+ ## Examples
680
+
681
+ ### No matching road closures
682
+
683
+ ```tsx
684
+ <EmptyState
685
+ title="No matching road closures"
686
+ description="Clear the filters to see all reported closures."
687
+ action={<Button onClick={clearFilters}>Clear filters</Button>}
688
+ />
689
+ ```
690
+
691
+ ## Rules
692
+ - Use a specific heading. Offer one action when it helps the user continue.
693
+
694
+ ## Accessibility
695
+ - The icon is decorative. The optional button or link keeps native keyboard behavior.
696
+ - The empty state is static by default. The host manages announcements for dynamic updates.
697
+
698
+ ## DOM contract (for agents operating the page)
699
+
700
+ - Selector: `[data-sw="empty-state"]`
701
+ - How to operate: Read the heading and description. Use the button or link if an action is present.
702
+
703
+ Related: `skeleton`, `button`
704
+
705
+ ---
706
+
707
+ # Toast
708
+
709
+ > Imperative notifications — `toast("Saved")` — stacked in a <Toaster/> host: actions, promise states, pause on hover, swipe to dismiss, announced politely.
710
+
711
+ Category: display · Status: beta · Slug: `toast`
712
+
713
+ ```tsx
714
+ import { Toaster, OverlayHost, toast } from '@peerproblem/sw3-ui'
715
+ ```
716
+
717
+ ## When to use
718
+ - Confirming something finished: saved, deployed, copied.
719
+ - Offering Undo after an action.
720
+ - Progress of an async task: toast.promise(run(), { loading, success, error }).
721
+
722
+ ## Avoid
723
+ - Errors the user must fix in a form → show them inline (Field / Input error).
724
+ - Questions that need an answer → use AlertDialog / confirm().
725
+ - Long text or several actions → use a Dialog or an inline banner.
726
+ - Mounting several <Toaster/>s — place exactly one (or one <OverlayHost/>).
727
+
728
+ ## Props
729
+
730
+ | Prop | Type | Default | Description |
731
+ | --- | --- | --- | --- |
732
+ | `toast(title, options?)` | `(title: ReactNode, o?: ToastOptions) => string` | | Show a toast; returns its id. Also toast.success / toast.danger (alias toast.error) / toast.loading. |
733
+ | `options.description` | `ReactNode` | | Second line. |
734
+ | `options.variant` | `'default' \| 'success' \| 'danger' \| 'loading'` | `'default'` | Icon + announcement priority (danger is assertive). loading stays until updated. |
735
+ | `options.duration` | `number` | `5000` | ms; Infinity keeps it until dismissed. Pauses while hovered/focused or the tab is hidden. |
736
+ | `options.action` | `{ label: ReactNode; onClick?: (e) => unknown \| Promise<unknown> }` | | One button, e.g. Undo. A returned Promise shows loading; the toast closes when it resolves. |
737
+ | `options.cancel` | `{ label: ReactNode; onClick?: () => void }` | | A quiet button that just closes it. |
738
+ | `options.id` | `string` | | Reuse to update a showing toast in place. |
739
+ | `options.dismissible` | `boolean` | `true` | Whether swipe, Escape and × can close it. |
740
+ | `options.onDismiss` | `(id: string) => void` | | Called once it closes. |
741
+ | `toast.promise(p, { loading, success, error })` | `(Promise \| () => Promise, messages) => string` | | Loading toast that becomes success/danger. Messages: ReactNode, { title, description, action }, or a function of the result/error. |
742
+ | `toast.update(id, patch) / toast.dismiss(id?)` | `functions` | | Change a showing toast; dismiss one or all. |
743
+ | `Toaster.side / align` | `'top' \| 'bottom' / 'start' \| 'center' \| 'end'` | `'bottom' / 'end'` | Corner of the viewport. Full width on phones. |
744
+ | `Toaster.maxVisible` | `number` | `3` | Shown at once; the rest wait with timers stopped. |
745
+ | `Toaster.expanded` | `boolean` | `false` | Keep the stack expanded (otherwise it expands on hover/focus). |
746
+ | `Toaster.duration` | `number` | `5000` | Default duration. |
747
+ | `Toaster.closeButton` | `boolean` | `true` | Show × on dismissible toasts, as a small badge on the top-left corner (on hover/focus; always on touch). It never takes space from the text. |
748
+ | `Toaster.shortcut` | `string \| null` | `'F6'` | Key that moves focus to the newest toast and back. |
749
+ | `OverlayHost` | `ToasterProps` | | <Toaster/> + <ConfirmHost/> in one — the host for toast() and confirm(). |
750
+
751
+ ## Examples
752
+
753
+ ### Host + simple toasts
754
+
755
+ ```tsx
756
+ // once, near the root
757
+ <OverlayHost />
758
+
759
+ toast('Prompt copied')
760
+ toast.success('Deployed to production', { description: 'v42 · 18s' })
761
+ toast('Run archived', { action: { label: 'Undo', onClick: () => restore(runId) } })
762
+ ```
763
+
764
+ ### Promise
765
+
766
+ ```tsx
767
+ toast.promise(api.deploy(), {
768
+ loading: 'Deploying…',
769
+ success: (r) => ({ title: 'Deployed', description: r.url }),
770
+ error: (e) => ({ title: 'Deploy failed', description: String(e), action: { label: 'Retry', onClick: deploy } }),
771
+ })
772
+ ```
773
+
774
+ ## Rules
775
+ - Title ≤ ~6 words, past tense ("Changes saved"); description optional, one line.
776
+ - At most one action; prefer Undo over asking first.
777
+ - Use danger only for failures; don’t toast every success.
778
+
779
+ ## Accessibility
780
+ - Messages are announced once through hidden aria-live regions (polite; assertive for danger) without moving focus.
781
+ - The region is a landmark named "Notifications". F6 moves focus to the newest toast and back; Escape dismisses the focused toast. Timers pause while hovered or focused.
782
+
783
+ ## DOM contract (for agents operating the page)
784
+
785
+ - Selector: `[data-sw="toaster"] [data-sw="toast"]`
786
+ - `data-variant`: default | success | danger | loading
787
+ - `data-front`: newest toast
788
+ - `data-expanded`: on the region while expanded
789
+ - How to operate: Read titles from [data-sw="toast-title"]. Click [data-sw="toast-action"] or [data-sw="toast-close"]. Agent bridge (kind "toaster"): items = visible toasts {value: id, label}; action dismiss(id?) (no id = all).
790
+
791
+ Related: `alert-dialog`, `dialog`
792
+
793
+ ---
794
+
795
+ # Accordion
796
+
797
+ > Stacked sections whose headings expand and collapse their panels, with an animated height.
798
+
799
+ Category: layout · Status: beta · Slug: `accordion`
800
+
801
+ ```tsx
802
+ import { Accordion, AccordionItem, AccordionTrigger, AccordionPanel } from '@peerproblem/sw3-ui'
803
+ ```
804
+
805
+ ## When to use
806
+ - FAQs, settings groups and long pages where readers scan headings and open only what they need.
807
+ - Several related sections of the same weight in a narrow column.
808
+
809
+ ## Avoid
810
+ - Switching between views of the same thing — use Tabs.
811
+ - A single show/hide toggle — use Collapsible.
812
+ - Hiding content everyone must read (errors, required fields) — keep it visible.
813
+ - Putting interactive controls inside AccordionTrigger — the whole trigger is one button.
814
+
815
+ ## Props
816
+
817
+ | Prop | Type | Default | Description |
818
+ | --- | --- | --- | --- |
819
+ | `size` | `'sm' \| 'md'` | `'md'` | sm is for dashboards: 40px header rows (6px inset, 28px trigger), 13px titles and a 14px frame radius. |
820
+ | `fill` | `boolean` | `false` | Fill the parent height. Open items share it and scroll on their own; folded items shrink to their header. Use it for an inspector or a side column. |
821
+ | `AccordionTrigger.actions` | `ReactNode` | | Controls beside the trigger, not inside it, e.g. `Button size="2xs" variant="ghost" iconOnly`. |
822
+ | `items` | `{ value: string; title: ReactNode; content: ReactNode; disabled?: boolean }[]` | | Shorthand: render items from data instead of parts. |
823
+ | `value` | `string[]` | | Open item values (always an array). Controlled. |
824
+ | `defaultValue` | `string[]` | `[]` | Items open at first, when uncontrolled. |
825
+ | `onValueChange` | `(value: string[]) => void` | | Called when items open or close. |
826
+ | `multiple` | `boolean` | `false` | Allow several items open at once. Otherwise opening one closes the others. |
827
+ | `collapsible` | `boolean` | `true` | Single mode: whether the open item can be closed. false keeps one open (its trigger gets aria-disabled). |
828
+ | `disabled` | `boolean` | `false` | Disable every item. Triggers stay focusable. |
829
+ | `keepMounted` | `boolean` | `false` | Keep closed panels in the DOM (hidden), e.g. to preserve form state. |
830
+ | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading element wrapping each trigger. Match the page outline. |
831
+ | `variant` | `'framed' \| 'plain'` | `'framed'` | framed = squircle frame with hairlines between items; plain = hairlines only. |
832
+ | `radius` | `RadiusValue` | `'lg'` | Corner radius of the framed variant. |
833
+ | `AccordionItem.value` * | `string` | | Unique value; listed in `value` while open. |
834
+ | `AccordionItem.disabled` | `boolean` | | Stops this item from opening or closing. |
835
+ | `AccordionTrigger.meta` | `ReactNode` | | Small trailing text before the chevron (count, status). |
836
+ | `AccordionTrigger.headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | | Override the heading level for one item. |
837
+ | `AccordionPanel.keepMounted` | `boolean` | | Override the Accordion's keepMounted for one panel. |
838
+
839
+ ## Examples
840
+
841
+ ### FAQ from data
842
+
843
+ ```tsx
844
+ <Accordion
845
+ defaultValue={['limits']}
846
+ items={[
847
+ { value: 'limits', title: 'What are the rate limits?', content: '600 requests per minute per key.' },
848
+ { value: 'models', title: 'Which models can I use?', content: 'Every model on your plan, switchable per request.' },
849
+ { value: 'data', title: 'Do you train on my data?', content: 'No. Prompts and outputs are never used for training.' },
850
+ ]}
851
+ />
852
+ ```
853
+
854
+ ### Parts, several open
855
+
856
+ ```tsx
857
+ const [open, setOpen] = useState<string[]>(['general'])
858
+
859
+ <Accordion multiple value={open} onValueChange={setOpen} headingLevel={2}>
860
+ <AccordionItem value="general">
861
+ <AccordionTrigger meta="3">General</AccordionTrigger>
862
+ <AccordionPanel>Name, avatar and workspace URL.</AccordionPanel>
863
+ </AccordionItem>
864
+ <AccordionItem value="billing">
865
+ <AccordionTrigger>Billing</AccordionTrigger>
866
+ <AccordionPanel>Plan, invoices and payment method.</AccordionPanel>
867
+ </AccordionItem>
868
+ </Accordion>
869
+ ```
870
+
871
+ ## Rules
872
+ - A stack of foldable dashboard panels is `<Accordion size="sm" variant="plain|framed" multiple fill>`. Do not stack Cards with gaps.
873
+ - Trigger text is a short noun phrase or question; put details in the panel.
874
+ - Keep it to roughly 3–10 items; more becomes a wall of headings.
875
+
876
+ ## Accessibility
877
+ - Each trigger is a <button aria-expanded aria-controls> inside an <h3> (headingLevel).
878
+ - Panels are role="region" labelled by their trigger.
879
+ - Tab moves between triggers; Enter/Space toggles. No arrow-key navigation, per the current APG pattern.
880
+
881
+ ## DOM contract (for agents operating the page)
882
+
883
+ - Selector: `[data-sw="accordion"]`
884
+ - `data-state`: open | closed on accordion-item, accordion-trigger and accordion-panel
885
+ - `aria-expanded`: on [data-sw="accordion-trigger"]
886
+ - `data-disabled`: on the root or item when disabled
887
+ - How to operate: Click [data-sw="accordion-trigger"] to toggle its item. Agent bridge: expand(value), collapse(value), toggle(value), setValue(values[]); state = { value, multiple, disabled }.
888
+
889
+ Related: `collapsible`, `tabs`
890
+
891
+ ---
892
+
893
+ # Collapsible
894
+
895
+ > One trigger that shows and hides one panel, with an animated height.
896
+
897
+ Category: layout · Status: beta · Slug: `collapsible`
898
+
899
+ ```tsx
900
+ import { Collapsible, CollapsibleTrigger, CollapsiblePanel } from '@peerproblem/sw3-ui'
901
+ ```
902
+
903
+ ## When to use
904
+ - "Show more" / "Advanced options" sections.
905
+ - Revealing details (logs, raw JSON) under a summary line.
906
+
907
+ ## Avoid
908
+ - A list of several sections — use Accordion.
909
+ - Floating content over the page — use Popover.
910
+ - Hiding the only way to do a primary task.
911
+
912
+ ## Props
913
+
914
+ | Prop | Type | Default | Description |
915
+ | --- | --- | --- | --- |
916
+ | `open` | `boolean` | | Controlled open state. |
917
+ | `defaultOpen` | `boolean` | `false` | Open at first, when uncontrolled. |
918
+ | `onOpenChange` | `(open: boolean) => void` | | Called when the trigger toggles. |
919
+ | `disabled` | `boolean` | `false` | Disable the trigger. |
920
+ | `keepMounted` | `boolean` | `false` | Keep the panel's contents mounted (hidden) while closed, so their state survives. |
921
+ | `CollapsibleTrigger.indicator` | `boolean` | `true` | Show the rotating chevron. |
922
+ | `CollapsiblePanel.keepMounted` | `boolean` | | Override keepMounted for the panel. |
923
+
924
+ ## Examples
925
+
926
+ ### Advanced options
927
+
928
+ ```tsx
929
+ <Collapsible>
930
+ <CollapsibleTrigger>Advanced options</CollapsibleTrigger>
931
+ <CollapsiblePanel>
932
+ <Input label="Max tokens" defaultValue="4096" />
933
+ </CollapsiblePanel>
934
+ </Collapsible>
935
+ ```
936
+
937
+ ### Controlled, contents kept
938
+
939
+ ```tsx
940
+ const [open, setOpen] = useState(false)
941
+
942
+ <Collapsible open={open} onOpenChange={setOpen} keepMounted>
943
+ <CollapsibleTrigger>{open ? 'Hide' : 'Show'} raw response</CollapsibleTrigger>
944
+ <CollapsiblePanel><pre>{json}</pre></CollapsiblePanel>
945
+ </Collapsible>
946
+ ```
947
+
948
+ ## Rules
949
+ - The trigger label says what is hidden ("Advanced options", "Show 12 more").
950
+
951
+ ## Accessibility
952
+ - The trigger is a <button aria-expanded aria-controls>; Enter/Space toggles.
953
+
954
+ ## DOM contract (for agents operating the page)
955
+
956
+ - Selector: `[data-sw="collapsible"]`
957
+ - `data-state`: open | closed (root, trigger and panel)
958
+ - `aria-expanded`: on [data-sw="collapsible-trigger"]
959
+ - How to operate: Click [data-sw="collapsible-trigger"]. Agent bridge: open(), close(), toggle(); state = { open, disabled }.
960
+
961
+ Related: `accordion`
962
+
963
+ ---
964
+
965
+ # Toolbar
966
+
967
+ > A row of buttons, toggles, links and fields with a single tab stop; arrow keys move between them.
968
+
969
+ Category: actions · Status: beta · Slug: `toolbar`
970
+
971
+ ```tsx
972
+ import { Toolbar, ToolbarButton, ToolbarToggle, ToolbarGroup, ToolbarSeparator, ToolbarLink, ToolbarInput, Icon } from '@peerproblem/sw3-ui'
973
+ ```
974
+
975
+ ## When to use
976
+ - Editor formatting bars (bold, italic, align).
977
+ - Compact action rows above a table, canvas or code view.
978
+
979
+ ## Avoid
980
+ - A page's main call to action — use Button.
981
+ - One or two buttons — plain Buttons are fine.
982
+ - Navigation between pages — use links or NavigationMenu.
983
+
984
+ ## Props
985
+
986
+ | Prop | Type | Default | Description |
987
+ | --- | --- | --- | --- |
988
+ | `aria-label` * | `string` | | Names the toolbar, e.g. "Text formatting". |
989
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Which arrow keys move focus. |
990
+ | `loop` | `boolean` | `true` | Arrow keys wrap. |
991
+ | `disabled` | `boolean` | `false` | Disable every item (they stay focusable with aria-disabled). |
992
+ | `size` | `'sm' \| 'md'` | `'md'` | 28 / 32px items. |
993
+ | `variant` | `'framed' \| 'plain'` | `'framed'` | framed = squircle frame around the bar. |
994
+ | `ToolbarButton.icon` | `ReactNode` | | Icon before the label. Icon-only buttons need aria-label. |
995
+ | `ToolbarButton.disabled` | `boolean` | | aria-disabled; still reachable with arrows. |
996
+ | `ToolbarButton.focusableWhenDisabled` | `boolean` | `true` | false = natively disabled and skipped. |
997
+ | `ToolbarToggle.pressed` | `boolean` | | Controlled pressed state (aria-pressed). |
998
+ | `ToolbarToggle.defaultPressed` | `boolean` | `false` | Initial pressed state. |
999
+ | `ToolbarToggle.onPressedChange` | `(pressed: boolean) => void` | | Called on press. |
1000
+ | `ToolbarGroup.aria-label` | `string` | | Names a set of related items. |
1001
+ | `ToolbarGroup.disabled` | `boolean` | | Disable every item in the group. |
1002
+ | `ToolbarInput.prefix` | `ReactNode` | | Icon inside the field. |
1003
+ | `ToolbarLink.href` | `string` | | A link item. |
1004
+
1005
+ ## Examples
1006
+
1007
+ ### Formatting bar
1008
+
1009
+ ```tsx
1010
+ <Toolbar aria-label="Text formatting">
1011
+ <ToolbarGroup aria-label="Style">
1012
+ <ToolbarToggle aria-label="Bold" defaultPressed>B</ToolbarToggle>
1013
+ <ToolbarToggle aria-label="Italic"><i>I</i></ToolbarToggle>
1014
+ </ToolbarGroup>
1015
+ <ToolbarSeparator />
1016
+ <ToolbarButton icon={<Icon name="copy" />} aria-label="Copy" />
1017
+ <ToolbarButton icon={<Icon name="trash" />} aria-label="Delete" disabled />
1018
+ <ToolbarSeparator />
1019
+ <ToolbarInput aria-label="Search" placeholder="Find…" prefix={<Icon name="search" />} />
1020
+ </Toolbar>
1021
+ ```
1022
+
1023
+ ## Rules
1024
+ - Group related items and separate groups with ToolbarSeparator.
1025
+ - Icon-only items always get aria-label (and ideally a Tooltip).
1026
+ - Buttons, toggles and fields share one concentric squircle radius (toolbar radius − 4px inset). Pressed toggles use the foreground as a solid fill and the background for their labels and icons.
1027
+
1028
+ ## Accessibility
1029
+ - role="toolbar" with aria-orientation; separators have role="separator".
1030
+ - One tab stop with roving focus; Tab returns to the item focused last.
1031
+ - Arrow keys move; Home/End jump (except inside a field, where the caret keeps them). Toggles use aria-pressed; moving focus never presses them.
1032
+
1033
+ ## DOM contract (for agents operating the page)
1034
+
1035
+ - Selector: `[data-sw="toolbar"]`
1036
+ - `aria-pressed`: on [data-sw="toolbar-button"] toggles
1037
+ - `aria-disabled`: on disabled items
1038
+ - How to operate: Click the [data-sw="toolbar-button"] whose aria-label or text matches; type into [data-sw="toolbar-input"]. Items are native buttons/inputs, so the bridge reads them through the DOM fallback.
1039
+
1040
+ Related: `button`, `segmented-control`
1041
+
1042
+ ---
1043
+
1044
+ # Tree
1045
+
1046
+ > A hierarchy with expandable branches, folder/file icons and single or multiple selection (APG tree view).
1047
+
1048
+ Category: display · Status: beta · Slug: `tree`
1049
+
1050
+ ```tsx
1051
+ import { Tree, type TreeItemData } from '@peerproblem/sw3-ui'
1052
+ ```
1053
+
1054
+ ## When to use
1055
+ - File and folder browsers.
1056
+ - Nested categories, org charts, outline navigation in docs.
1057
+
1058
+ ## Avoid
1059
+ - Flat lists — use a Listbox or a table.
1060
+ - Two levels of simple sections — use Accordion.
1061
+ - Hiding everything behind deep nesting; flatten when you can.
1062
+
1063
+ ## Props
1064
+
1065
+ | Prop | Type | Default | Description |
1066
+ | --- | --- | --- | --- |
1067
+ | `items` * | `{ id: string; label: string; children?: TreeItemData[]; icon?: ReactNode; disabled?: boolean; meta?: ReactNode }[]` | | The hierarchy. An item with `children` (even []) is a branch. |
1068
+ | `aria-label` | `string` | | Names the tree, e.g. "Project files". Or aria-labelledby. |
1069
+ | `multiple` | `boolean` | `false` | Several items can be selected; value becomes string[]. |
1070
+ | `value` | `string \| null (string[] when multiple)` | | Selected id(s). Controlled. |
1071
+ | `defaultValue` | `string \| null (string[] when multiple)` | | Initial selection. |
1072
+ | `onValueChange` | `(value: string \| null) => void (string[] when multiple)` | | Called when the selection changes. |
1073
+ | `expanded` | `string[]` | | Expanded branch ids. Controlled. |
1074
+ | `defaultExpanded` | `string[]` | `[]` | Branches expanded at first. |
1075
+ | `onExpandedChange` | `(expanded: string[]) => void` | | Called when branches expand or collapse. |
1076
+ | `onAction` | `(id: string, item: TreeItemData) => void` | | Runs on press or Enter, e.g. open the file. |
1077
+ | `selectionFollowsFocus` | `boolean` | `false` | Single mode: arrow keys select as they move. |
1078
+ | `expandOnPress` | `boolean` | `true` | Pressing a branch row toggles it (the chevron always does). |
1079
+ | `showIcons` | `boolean` | `true` | Folder / file icons. |
1080
+ | `renderLabel` | `(item, { expanded, selected, level }) => ReactNode` | | Custom row content. |
1081
+ | `size` | `'sm' \| 'md'` | `'md'` | 28 / 32px rows. |
1082
+ | `disabled` | `boolean` | `false` | Disable every item (still focusable). |
1083
+ | `framed` | `boolean` | `true` | Own 1px squircle frame with a 4px inset; rows are concentric with it. Set false inside a pane that already frames it. |
1084
+ | `radius` | `RadiusToken \| number` | `'md'` | Frame radius. |
1085
+
1086
+ ## Examples
1087
+
1088
+ ### File browser
1089
+
1090
+ ```tsx
1091
+ const files: TreeItemData[] = [
1092
+ { id: 'src', label: 'src', children: [
1093
+ { id: 'src/agent.ts', label: 'agent.ts' },
1094
+ { id: 'src/tools', label: 'tools', children: [{ id: 'src/tools/search.ts', label: 'search.ts' }] },
1095
+ ] },
1096
+ { id: 'package.json', label: 'package.json' },
1097
+ ]
1098
+
1099
+ <Tree aria-label="Project files" items={files} defaultExpanded={['src']} defaultValue="src/agent.ts"
1100
+ onAction={(id) => openFile(id)} />
1101
+ ```
1102
+
1103
+ ### Multiple selection, controlled
1104
+
1105
+ ```tsx
1106
+ const [picked, setPicked] = useState<string[]>([])
1107
+
1108
+ <Tree aria-label="Sources" items={sources} multiple value={picked} onValueChange={setPicked} />
1109
+ ```
1110
+
1111
+ ## Rules
1112
+ - Ids are unique across the whole tree (paths make good ids).
1113
+ - Labels are plain text so typeahead works; use renderLabel for decoration.
1114
+ - Framed by default — do not wrap it in a Card. Use framed={false} inside a Resizable pane or sidebar.
1115
+ - Selected rows are a neutral fill + 500 weight; accent is only the focus ring and the multi-select check.
1116
+
1117
+ ## Accessibility
1118
+ - role="tree" > role="treeitem" (aria-level, aria-setsize, aria-posinset, aria-expanded on branches, aria-selected) > role="group".
1119
+ - One tab stop. Up/Down move, Right expands or enters, Left collapses or goes to the parent, Home/End, * expands siblings, Alt+Right/Left expand/collapse all below, typing jumps.
1120
+ - Enter selects and runs onAction; Space selects (toggles when multiple); Shift+Up/Down extends and Ctrl/Cmd+A selects all visible when multiple.
1121
+
1122
+ ## DOM contract (for agents operating the page)
1123
+
1124
+ - Selector: `[data-sw="tree"]`
1125
+ - `aria-expanded`: on branch [data-sw="tree-item"]
1126
+ - `aria-selected`: on each [data-sw="tree-item"]
1127
+ - `data-id`: the item id on each [data-sw="tree-item"]
1128
+ - How to operate: Click the [data-sw="tree-item-label"] row inside [data-sw="tree-item"][data-id="…"]. Agent bridge: select(id), setValue(id | ids), expand(id), collapse(id), toggle(id); items = every node; state = { value, expanded, multiple }.
1129
+
1130
+ Related: `accordion`, `collapsible`
1131
+
1132
+ ---
1133
+
1134
+ # ScrollArea
1135
+
1136
+ > Native scrolling with slim overlay scrollbars, edge fades, and an optional stick-to-bottom mode for chat logs.
1137
+
1138
+ Category: layout · Status: beta · Slug: `scroll-area`
1139
+
1140
+ ```tsx
1141
+ import { ScrollArea } from '@peerproblem/sw3-ui'
1142
+ ```
1143
+
1144
+ ## When to use
1145
+ - Fixed-height panes: sidebars, popover lists, code and log output.
1146
+ - Chat transcripts and streamed agent output (followEnd).
1147
+ - Horizontal rails of cards (orientation="horizontal").
1148
+
1149
+ ## Avoid
1150
+ - The whole page — let the document scroll.
1151
+ - Tiny boxes where the fade hides most content — set fades={false}.
1152
+ - Nesting scroll areas on the same axis.
1153
+
1154
+ ## Props
1155
+
1156
+ | Prop | Type | Default | Description |
1157
+ | --- | --- | --- | --- |
1158
+ | `orientation` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which axes scroll. |
1159
+ | `type` | `'hover' \| 'scroll' \| 'auto' \| 'always'` | `'hover'` | When scrollbars show: on hover or scroll, only while scrolling, whenever it overflows, or always. |
1160
+ | `fades` | `boolean` | `true` | Fade edges that have more content beyond them. |
1161
+ | `followEnd` | `boolean` | `false` | Start at the end and stay there as content grows; scrolling up lets go, returning to the end sticks again. |
1162
+ | `scrollToEndButton` | `boolean` | `true` | With followEnd: a "Jump to latest" pill while away from the end. |
1163
+ | `scrollToEndLabel` | `string` | `'Jump to latest'` | Text of that pill. |
1164
+ | `scrollHideDelay` | `number` | `700` | ms the bars linger after scrolling. |
1165
+ | `maxHeight` | `CSS length` | | Cap the height (or set height via style/className). |
1166
+ | `aria-label` | `string` | | Makes the viewport a named region. |
1167
+ | `role` | `string` | | Role for the viewport, e.g. "log" for a chat. |
1168
+ | `viewportProps` | `HTMLAttributes<HTMLDivElement>` | | Extra props for the native scrolling element. |
1169
+ | `ref` | `Ref<{ viewport; scrollToEnd(behavior?); scrollToStart(behavior?) }>` | | Imperative handle. |
1170
+
1171
+ ## Examples
1172
+
1173
+ ### Fixed-height list
1174
+
1175
+ ```tsx
1176
+ <ScrollArea maxHeight={280} aria-label="Recent runs">
1177
+ {runs.map((r) => <RunRow key={r.id} run={r} />)}
1178
+ </ScrollArea>
1179
+ ```
1180
+
1181
+ ### Chat log that follows new messages
1182
+
1183
+ ```tsx
1184
+ <ScrollArea followEnd role="log" aria-label="Conversation" style={{ height: 360 }}>
1185
+ {messages.map((m) => <Message key={m.id} {...m} />)}
1186
+ </ScrollArea>
1187
+ ```
1188
+
1189
+ ### Horizontal rail
1190
+
1191
+ ```tsx
1192
+ <ScrollArea orientation="horizontal">
1193
+ <div style={{ display: 'flex', gap: 12 }}>{cards}</div>
1194
+ </ScrollArea>
1195
+ ```
1196
+
1197
+ ## Rules
1198
+ - Give it a height (height, maxHeight or a flex parent); otherwise it just grows.
1199
+ - Keep keyboard access: the viewport becomes a tab stop when it scrolls and holds nothing focusable.
1200
+
1201
+ ## Accessibility
1202
+ - The viewport is the real, native scroller: wheel, touch, keys and screen-reader scrolling all work.
1203
+ - Overlay scrollbars are aria-hidden.
1204
+ - Use role="log" for chat transcripts.
1205
+
1206
+ ## DOM contract (for agents operating the page)
1207
+
1208
+ - Selector: `[data-sw="scroll-area"]`
1209
+ - `data-overflow-y / data-overflow-x`: present while content overflows
1210
+ - `data-at-start / data-at-end`: present at the edges
1211
+ - `data-sticking`: present while followEnd is holding the end
1212
+ - How to operate: Scroll [data-sw="scroll-area-viewport"] (element.scrollTop). Agent bridge: scrollToEnd(), scrollToStart(); state = { atStart, atEnd, sticking }.
1213
+
1214
+ Related: `resizable`
1215
+
1216
+ ---
1217
+
1218
+ # Resizable
1219
+
1220
+ > Panel groups split by draggable, keyboard-operable handles, with min/max, collapsible panels and saved layouts.
1221
+
1222
+ Category: layout · Status: beta · Slug: `resizable`
1223
+
1224
+ ```tsx
1225
+ import { Resizable, ResizablePanel, ResizableHandle } from '@peerproblem/sw3-ui'
1226
+ ```
1227
+
1228
+ ## When to use
1229
+ - IDE-style layouts: file tree | editor | preview, editor above terminal.
1230
+ - Letting people trade space between a list and its detail view.
1231
+
1232
+ ## Avoid
1233
+ - Phone-first layouts — stack the panes instead (or use orientation="vertical").
1234
+ - Decorative splits that nobody needs to resize — use a CSS grid.
1235
+
1236
+ ## Props
1237
+
1238
+ | Prop | Type | Default | Description |
1239
+ | --- | --- | --- | --- |
1240
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Side by side or stacked. |
1241
+ | `layout` | `number[]` | | Panel sizes in percent, in order. Controlled. |
1242
+ | `defaultLayout` | `number[]` | | Initial sizes (otherwise each panel's defaultSize). |
1243
+ | `onLayoutChange` | `(layout: number[]) => void` | | Every drag frame and key press. |
1244
+ | `onLayoutCommit` | `(layout: number[]) => void` | | Once an interaction ends. Save here. |
1245
+ | `autoSaveId` | `string` | | Persist the layout to localStorage under this key and restore it on mount. |
1246
+ | `step` | `number` | `5` | Arrow-key step in percent. |
1247
+ | `largeStep` | `number` | `20` | Shift+Arrow step in percent. |
1248
+ | `disabled` | `boolean` | `false` | Freeze every handle. |
1249
+ | `framed` | `boolean` | `true` | Own 1px squircle frame; panels are clipped to it. Set false on nested groups or inside a framed surface. |
1250
+ | `radius` | `RadiusToken \| number` | `'md'` | Frame radius. |
1251
+ | `ResizablePanel.id` | `string` | | Stable id (aria-controls, agent actions). |
1252
+ | `ResizablePanel.defaultSize` | `number` | | Starting size in percent; panels without one share the rest. |
1253
+ | `ResizablePanel.minSize` | `number` | `0` | Minimum percent while open. |
1254
+ | `ResizablePanel.maxSize` | `number` | `100` | Maximum percent. |
1255
+ | `ResizablePanel.collapsible` | `boolean` | `false` | Can collapse to collapsedSize (drag past halfway below min, Enter or double-click the handle). |
1256
+ | `ResizablePanel.collapsedSize` | `number` | `0` | Size when collapsed. At 0 its content is inert. |
1257
+ | `ResizableHandle.aria-label` | `string` | | Names the handle, e.g. "Resize sidebar". |
1258
+ | `ResizableHandle.disabled` | `boolean` | | Freeze this handle. |
1259
+ | `ResizableHandle.withGrip` | `boolean` | `true` | Show the small grip. |
1260
+
1261
+ ## Examples
1262
+
1263
+ ### Sidebar | editor | preview, saved
1264
+
1265
+ ```tsx
1266
+ <Resizable autoSaveId="editor-layout">
1267
+ <ResizablePanel id="files" defaultSize={22} minSize={14} collapsible>…</ResizablePanel>
1268
+ <ResizableHandle aria-label="Resize file list" />
1269
+ <ResizablePanel id="editor" minSize={30}>…</ResizablePanel>
1270
+ <ResizableHandle aria-label="Resize preview" />
1271
+ <ResizablePanel id="preview" defaultSize={30} minSize={20}>…</ResizablePanel>
1272
+ </Resizable>
1273
+ ```
1274
+
1275
+ ### Editor above terminal
1276
+
1277
+ ```tsx
1278
+ <Resizable orientation="vertical" style={{ height: 220 }}>
1279
+ <ResizablePanel defaultSize={70}>…</ResizablePanel>
1280
+ <ResizableHandle aria-label="Resize terminal" />
1281
+ <ResizablePanel minSize={15} collapsible>…</ResizablePanel>
1282
+ </Resizable>
1283
+ ```
1284
+
1285
+ ## Rules
1286
+ - Panels and handles must be direct children of <Resizable> (no fragments or wrappers).
1287
+ - The group is framed by default — do not wrap it in a Card. Nested groups take framed={false}.
1288
+ - Keep panel content transparent (no opaque pane backgrounds); the group supplies the surface.
1289
+ - Horizontal groups are as tall as their content. Vertical groups need a height — size it to the content (≈180–240px), not a tall empty pane.
1290
+ - Name every handle with aria-label.
1291
+
1292
+ ## Accessibility
1293
+ - Handles are APG window splitters: focusable role="separator" with aria-valuenow (size of the panel before), aria-valuemin/max and aria-controls.
1294
+ - Arrow keys along the axis move by step (Shift = largeStep), Home/End go to the limits, Enter collapses/restores a collapsible neighbour.
1295
+
1296
+ ## DOM contract (for agents operating the page)
1297
+
1298
+ - Selector: `[data-sw="resizable"]`
1299
+ - `aria-valuenow`: on each [data-sw="resizable-handle"]: percent size of the panel before it
1300
+ - `data-size`: rounded percent on each [data-sw="resizable-panel"]
1301
+ - `data-collapsed`: on collapsed panels
1302
+ - How to operate: Focus a [data-sw="resizable-handle"] and press arrow keys, or drag it. Agent bridge: setSizes(number[]), collapse(panelId), expand(panelId); state = { layout, orientation, panels }.
1303
+
1304
+ Related: `scroll-area`
1305
+
1306
+ ---
1307
+
1308
+ # Carousel
1309
+
1310
+ > Slides on native scroll-snap with Previous / Next, page dots, keyboard paging and optional autoplay with a pause control.
1311
+
1312
+ Category: display · Status: beta · Slug: `carousel`
1313
+
1314
+ ```tsx
1315
+ import { Carousel, CarouselItem, CarouselViewport, CarouselControls, CarouselPrevious, CarouselNext, CarouselIndicators, CarouselPlayToggle } from '@peerproblem/sw3-ui'
1316
+ ```
1317
+
1318
+ ## When to use
1319
+ - Showcasing a handful of templates, screenshots or testimonials in limited space.
1320
+ - Several cards per page on desktop (slidesPerPage).
1321
+
1322
+ ## Avoid
1323
+ - Hiding important content in later slides — most people never see them.
1324
+ - Autoplay for anything people need to read carefully.
1325
+ - Long lists — use a grid or a horizontal ScrollArea.
1326
+
1327
+ ## Props
1328
+
1329
+ | Prop | Type | Default | Description |
1330
+ | --- | --- | --- | --- |
1331
+ | `aria-label` * | `string` | | Names the carousel, e.g. "Featured templates". |
1332
+ | `page` | `number` | | Current page, from 1. Controlled. |
1333
+ | `defaultPage` | `number` | `1` | Starting page. |
1334
+ | `onPageChange` | `(page: number) => void` | | Called when the page changes (buttons, dots, keys, swipe, autoplay). |
1335
+ | `slidesPerPage` | `number` | `1` | Slides visible per page; Next moves this many. |
1336
+ | `loop` | `boolean` | `false` | Next on the last page wraps to the first. |
1337
+ | `playing` | `boolean` | | Autoplay. Controlled. |
1338
+ | `defaultPlaying` | `boolean` | `false` | Start rotating (skipped when the user prefers reduced motion). Shows a play/pause button. |
1339
+ | `onPlayingChange` | `(playing: boolean) => void` | | Rotation started or stopped (keyboard focus and manual paging stop it). |
1340
+ | `interval` | `number` | `5000` | ms per page while rotating. |
1341
+ | `controls` | `boolean` | `true` | Default layout: Previous / Next buttons. |
1342
+ | `indicators` | `boolean` | `true` | Default layout: page dots (a tablist). |
1343
+ | `gap` | `number` | `12` | Gap between slides in px. |
1344
+ | `labels` | `{ previous?; next?; play?; pause?; page?(n); slide?(n, total) }` | | Translate control and slide labels. |
1345
+ | `CarouselItem` | `HTMLAttributes<HTMLDivElement>` | | One slide. Direct child of Carousel (default layout) or of CarouselViewport. |
1346
+ | `Parts` | `CarouselViewport, CarouselControls, CarouselPlayToggle, CarouselIndicators, CarouselPrevious, CarouselNext` | | For your own layout, pass parts instead of slides: any child that is not a CarouselItem switches Carousel to custom layout. The parts read state from the Carousel, so they work in any order and wrapper. |
1347
+
1348
+ ## Anatomy
1349
+
1350
+ ```
1351
+ Carousel root: state, keyboard, autoplay, agent binding
1352
+ ├─ CarouselViewport scroll-snap area (focusable)
1353
+ │ └─ CarouselItem × n one slide
1354
+ └─ CarouselControls the row under the slides
1355
+ ├─ CarouselPlayToggle when it can autoplay
1356
+ ├─ CarouselIndicators page dots (tablist)
1357
+ ├─ CarouselPrevious
1358
+ └─ CarouselNext
1359
+ ```
1360
+
1361
+ Built from: `useSquircle (round buttons)`, `Icon`.
1362
+
1363
+ ## Examples
1364
+
1365
+ ### Custom layout from parts
1366
+
1367
+ ```tsx
1368
+ <Carousel aria-label="Release highlights" loop>
1369
+ <CarouselControls>
1370
+ <Heading as="h3" size="sm">Highlights</Heading>
1371
+ <span style={{ marginLeft: 'auto', display: 'flex', gap: 6 }}>
1372
+ <CarouselPrevious />
1373
+ <CarouselNext />
1374
+ </span>
1375
+ </CarouselControls>
1376
+ <CarouselViewport>
1377
+ {releases.map((r) => <CarouselItem key={r.id}><Card>{r.title}</Card></CarouselItem>)}
1378
+ </CarouselViewport>
1379
+ <CarouselIndicators />
1380
+ </Carousel>
1381
+ ```
1382
+
1383
+ ### Templates, two per page
1384
+
1385
+ ```tsx
1386
+ <Carousel aria-label="Templates" slidesPerPage={2}>
1387
+ {templates.map((t) => (
1388
+ <CarouselItem key={t.id}><Card>{t.name}</Card></CarouselItem>
1389
+ ))}
1390
+ </Carousel>
1391
+ ```
1392
+
1393
+ ### Autoplay with pause
1394
+
1395
+ ```tsx
1396
+ <Carousel aria-label="Release highlights" defaultPlaying interval={6000} loop>
1397
+ <CarouselItem>…</CarouselItem>
1398
+ <CarouselItem>…</CarouselItem>
1399
+ <CarouselItem>…</CarouselItem>
1400
+ </Carousel>
1401
+ ```
1402
+
1403
+ ## Rules
1404
+ - 3–8 slides. Each slide makes sense on its own.
1405
+ - Autoplay only with loop, and only for non-essential content.
1406
+
1407
+ ## Accessibility
1408
+ - APG carousel: region with aria-roledescription="carousel"; slides are groups labelled "n of N"; off-page slides are inert.
1409
+ - Arrow keys page in the focused viewport, Home/End go to the ends; dots are a tablist with arrow-key roving.
1410
+ - Rotation stops when keyboard focus enters, pauses on hover, and the live region is polite only while not rotating.
1411
+
1412
+ ## DOM contract (for agents operating the page)
1413
+
1414
+ - Selector: `[data-sw="carousel"]`
1415
+ - `data-active`: on [data-sw="carousel-item"] slides of the current page
1416
+ - `aria-selected`: on the current [data-sw="carousel-indicator"]
1417
+ - `data-playing`: on the root while rotating
1418
+ - How to operate: Click [data-sw="carousel-next"] / [data-sw="carousel-previous"] or [data-sw="carousel-indicator"][data-page="N"]. Agent bridge: setValue(page), setPage(page), next(), prev(), play(), pause(); state = { page, pageCount, playing }.
1419
+
1420
+ Related: `scroll-area`, `pagination`
1421
+
1422
+ ---
1423
+
1424
+ # Table
1425
+
1426
+ > Read structured rows and columns with sortable headers and keyboard-accessible horizontal scrolling.
1427
+
1428
+ Category: display · Status: beta · Slug: `table`
1429
+
1430
+ ```tsx
1431
+ import { Table, type TableColumn, type TableRow } from '@peerproblem/sw3-ui'
1432
+ ```
1433
+
1434
+ ## When to use
1435
+ - Road closures, inventories, reports and other data with shared column headers.
1436
+
1437
+ ## Avoid
1438
+ - Page layout or spreadsheet-style cell editing.
1439
+
1440
+ ## Props
1441
+
1442
+ | Prop | Type | Default | Description |
1443
+ | --- | --- | --- | --- |
1444
+ | `caption` * | `string` | | Visible name for the table and its scroll region. |
1445
+ | `columns` * | `readonly TableColumn[]` | | Ordered columns with unique ids, labels, optional end alignment, and optional row headers. |
1446
+ | `rows` * | `readonly TableRow[]` | | Rows with stable ids and ReactNode cells keyed by column id. |
1447
+ | `TableColumn.compare` | `(a: TableRow, b: TableRow) => number` | | Compare underlying values to make a column sortable. |
1448
+ | `sort / defaultSort` | `TableSort \| null` | | Controlled or initial order with columnId and direction. |
1449
+ | `onSortChange` | `(sort: TableSort) => void` | | Runs on sort header activation. |
1450
+ | `emptyMessage` | `ReactNode` | `No rows` | Content shown in a full-width cell when there are no rows. |
1451
+
1452
+ ## Examples
1453
+
1454
+ ### Road closures
1455
+
1456
+ ```tsx
1457
+ <Table
1458
+ caption="Road closures"
1459
+ columns={[
1460
+ { id: 'road', label: 'Road', rowHeader: true },
1461
+ { id: 'status', label: 'Status' },
1462
+ ]}
1463
+ rows={[{ id: 'espoo-1', cells: { road: 'Ring I', status: 'One lane closed' } }]}
1464
+ emptyMessage="No closures reported"
1465
+ />
1466
+ ```
1467
+
1468
+ ## Rules
1469
+ - Provide a descriptive caption and clear column labels. Use end alignment for comparable figures.
1470
+
1471
+ ## Accessibility
1472
+ - Native caption, column headers and optional row headers preserve table navigation for screen readers.
1473
+ - When the table overflows horizontally, Tab enters the named scroll region. Left and Right scroll it, and Tab continues to links, buttons or the next part of the page.
1474
+
1475
+ ## DOM contract (for agents operating the page)
1476
+
1477
+ - Selector: `[data-sw="table"]`
1478
+ - `tabindex="0"`: on [data-sw="table-viewport"] when the table overflows horizontally
1479
+ - How to operate: Read rows and headers from the native table. Agent bridge state includes rowCount and columnCount. Operate links and buttons in cells through their own bindings.
1480
+
1481
+ Related: `scroll-area`, `badge`
1482
+
1483
+ ---
1484
+
1485
+ # Avatar
1486
+
1487
+ > A person or team picture that shows initials (or an icon) while the image loads and if it fails; AvatarGroup overlaps several with a "+N" count.
1488
+
1489
+ Category: display · Status: beta · Slug: `avatar`
1490
+
1491
+ ```tsx
1492
+ import { Avatar, AvatarGroup, AvatarImage, AvatarFallback } from '@peerproblem/sw3-ui'
1493
+ ```
1494
+
1495
+ ## When to use
1496
+ - A person, team, workspace or bot next to their content: comments, member lists, account menus, activity feeds.
1497
+ - A stack of collaborators or reviewers: `<AvatarGroup max={4}>`.
1498
+
1499
+ ## Avoid
1500
+ - Hand-rolled `<img>` circles — they flash a broken image on error. Use Avatar with `name` so initials take over.
1501
+ - Circle for non-people. Use `shape="squircle"` for teams, workspaces, apps and bots.
1502
+ - A missing name. Without `name` (or `alt`) screen readers announce nothing; pass `alt=""` only when a visible name sits beside it.
1503
+ - Using it as a button by itself. Wrap it in a Button or link with an accessible name instead.
1504
+
1505
+ ## Props
1506
+
1507
+ | Prop | Type | Default | Description |
1508
+ | --- | --- | --- | --- |
1509
+ | `src` | `string` | | Image URL. Shorthand that renders AvatarImage + AvatarFallback for you. |
1510
+ | `name` | `string` | | Person or team name. Gives the fallback initials and the accessible name. |
1511
+ | `alt` | `string` | `name` | Image alt text. `""` when a visible name already identifies the person. |
1512
+ | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | `'md' (group: the group's size)` | 20 / 28 / 36 / 48 / 64px, or px. |
1513
+ | `shape` | `'circle' \| 'squircle'` | `'circle'` | circle for people, squircle for teams, workspaces and bots. |
1514
+ | `presence` | `'online' \| 'away' \| 'busy' \| 'offline'` | | Status dot in the corner. |
1515
+ | `delay` | `number` | | ms before the fallback shows, so a fast image does not flash initials. |
1516
+ | `onLoadingStatusChange` | `(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void` | | Runs when the image status changes. |
1517
+ | `children` | `ReactNode` | | Compound use: <AvatarImage src alt/> + <AvatarFallback>…</AvatarFallback>. Overrides the shorthand. |
1518
+ | `AvatarImage.src / alt` * | `string` | | A real <img>, hidden until it loads. |
1519
+ | `AvatarFallback.delay` | `number` | | Wait before showing the fallback. |
1520
+ | `AvatarGroup.max` | `number` | | Show at most this many, then a "+N" bubble. |
1521
+ | `AvatarGroup.size / shape` | `AvatarSize \| number / AvatarShape` | `'sm'` | Applied to every avatar inside. |
1522
+ | `AvatarGroup.overlap` | `number` | `0.28` | Overlap as a share of the avatar size. |
1523
+ | `AvatarGroup.aria-label` | `string` | | Names the group, e.g. "Reviewers". |
1524
+
1525
+ ## Examples
1526
+
1527
+ ### With fallback
1528
+
1529
+ ```tsx
1530
+ <Avatar src="/ada.png" name="Ada Lovelace" />
1531
+ <Avatar name="Grace Hopper" presence="online" />
1532
+ <Avatar name="Deploy Bot" shape="squircle" size="lg" />
1533
+ ```
1534
+
1535
+ ### Group
1536
+
1537
+ ```tsx
1538
+ <AvatarGroup aria-label="Reviewers" max={3} size="sm">
1539
+ <Avatar name="Ada Lovelace" src="/ada.png" />
1540
+ <Avatar name="Grace Hopper" src="/grace.png" />
1541
+ <Avatar name="Alan Turing" />
1542
+ <Avatar name="Linus Torvalds" />
1543
+ </AvatarGroup>
1544
+ ```
1545
+
1546
+ ### Compound parts
1547
+
1548
+ ```tsx
1549
+ <Avatar size="lg">
1550
+ <AvatarImage src="/team.png" alt="Platform team" />
1551
+ <AvatarFallback delay={300}>PT</AvatarFallback>
1552
+ </Avatar>
1553
+ ```
1554
+
1555
+ ## Rules
1556
+ - Always pass `name` (or alt) so the fallback has initials and screen readers a name.
1557
+ - One size per row or group. Use `xs`/`sm` in dense lists, `md` in comments, `lg`/`xl` on profile headers.
1558
+ - Avatars never carry the accent color; presence dots use success / orange / danger tokens.
1559
+
1560
+ ## Accessibility
1561
+ - The image has alt text (the name by default); the fallback includes the name as visually hidden text.
1562
+ - AvatarGroup is role="group"; the "+N" bubble reads "N more".
1563
+
1564
+ ## DOM contract (for agents operating the page)
1565
+
1566
+ - Selector: `[data-sw="avatar"]`
1567
+ - `data-loading-status`: 'idle' | 'loading' | 'loaded' | 'error'
1568
+ - `data-shape`: 'circle' | 'squircle'
1569
+ - `data-presence`: 'online' | 'away' | 'busy' | 'offline'
1570
+ - How to operate: Display only. Read the person from the img alt or the visually hidden name; groups are [data-sw="avatar-group"] with a [data-sw="avatar-group-more"] count.
1571
+
1572
+ Related: `badge`, `timeline`
1573
+
1574
+ ---
1575
+
1576
+ # Timeline
1577
+
1578
+ > Dated events in order — activity feeds, changelogs, run or order progress — with complete/current/upcoming markers and one tab stop that arrow keys move.
1579
+
1580
+ Category: display · Status: beta · Slug: `timeline`
1581
+
1582
+ ```tsx
1583
+ import { Timeline, TimelineItem, TimelineMarker, TimelineConnector, TimelineContent, TimelineTitle, TimelineTime, TimelineDescription } from '@peerproblem/sw3-ui'
1584
+ ```
1585
+
1586
+ ## When to use
1587
+ - An activity feed or audit log.
1588
+ - Progress of a multi-step process (agent run, order, deploy) with `status`.
1589
+ - A roadmap or changelog: `orientation="horizontal"`.
1590
+
1591
+ ## Avoid
1592
+ - A step-by-step form wizard the user drives. Use a Stepper/Tabs instead; Timeline is a record, not navigation.
1593
+ - Tables of events with many columns. Use a Table; Timeline is for title + time + short description.
1594
+ - Timing data (durations, overlaps). Use Waterfall.
1595
+
1596
+ ## Props
1597
+
1598
+ | Prop | Type | Default | Description |
1599
+ | --- | --- | --- | --- |
1600
+ | `items` | `{ value?, title, time?, dateTime?, description?, status?, importance?, icon?, content? }[]` | | Shorthand: one event per entry. |
1601
+ | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Vertical feed or horizontal roadmap. Changes the arrow keys too. |
1602
+ | `loop` | `boolean` | `true` | Arrow keys wrap from last to first. |
1603
+ | `size` | `'sm' \| 'md'` | `'md'` | Marker 14 / 22px. |
1604
+ | `aria-label` * | `string` | | Names the list, e.g. "Deploy activity". |
1605
+ | `TimelineItem.status` | `'complete' \| 'current' \| 'upcoming'` | | current sets aria-current="step" and takes the tab stop first. |
1606
+ | `TimelineItem.importance` | `'normal' \| 'high'` | `'normal'` | High importance adds a visible label independently of status. |
1607
+ | `TimelineItem.value` | `string` | | Names the event (generated when omitted). |
1608
+ | `TimelineMarker.children` | `ReactNode` | | Icon or tiny avatar inside the marker; default is a dot (check when complete). |
1609
+ | `TimelineTime.dateTime` | `string` | | Machine-readable time; the text stays friendly. |
1610
+
1611
+ ## Examples
1612
+
1613
+ ### Run progress
1614
+
1615
+ ```tsx
1616
+ <Timeline aria-label="Run #4821" items={[
1617
+ { title: 'Queued', time: '14:02', status: 'complete' },
1618
+ { title: 'Running tests', time: '14:03', description: '128 of 412 passed', status: 'current' },
1619
+ { title: 'Deploy', time: 'Pending', status: 'upcoming' },
1620
+ ]} />
1621
+ ```
1622
+
1623
+ ### Compound parts
1624
+
1625
+ ```tsx
1626
+ <Timeline aria-label="Activity">
1627
+ <TimelineItem>
1628
+ <TimelineMarker />
1629
+ <TimelineConnector />
1630
+ <TimelineContent>
1631
+ <TimelineTitle>Deployed to production</TimelineTitle>
1632
+ <TimelineTime dateTime="2026-11-10T14:32">2:32 PM</TimelineTime>
1633
+ <TimelineDescription>Version 2.4.1 is live.</TimelineDescription>
1634
+ </TimelineContent>
1635
+ </TimelineItem>
1636
+ </Timeline>
1637
+ ```
1638
+
1639
+ ### Roadmap
1640
+
1641
+ ```tsx
1642
+ <Timeline aria-label="Roadmap" orientation="horizontal" size="sm" items={[
1643
+ { title: 'v2.4', time: 'Nov', status: 'complete' },
1644
+ { title: 'v2.5', time: 'Dec', status: 'current' },
1645
+ { title: 'v3.0', time: 'Jan', status: 'upcoming' },
1646
+ ]} />
1647
+ ```
1648
+
1649
+ ## Rules
1650
+ - Order events consistently (newest first for feeds, chronological for processes) and keep one `current` at most.
1651
+ - Keep titles short; put detail in the description, and links/buttons in `content`.
1652
+ - The accent appears only on the current marker.
1653
+
1654
+ ## Accessibility
1655
+ - role="list" of role="listitem" events; each event is named by its title and described by its time and description.
1656
+ - One tab stop: the current event, else the first, then the last focused. Up/Down (Left/Right when horizontal), Home/End move; Tab enters links inside an event.
1657
+
1658
+ ## DOM contract (for agents operating the page)
1659
+
1660
+ - Selector: `[data-sw="timeline"]`
1661
+ - `data-orientation`: 'vertical' | 'horizontal'
1662
+ - `data-status (item)`: 'complete' | 'current' | 'upcoming'
1663
+ - `aria-current="step"`: the current event
1664
+ - How to operate: Display only. Read events from [data-sw="timeline-item"] (title in [data-sw="timeline-title"], time in time[datetime]).
1665
+
1666
+ Related: `waterfall`, `avatar`, `badge`
1667
+
1668
+ ---
1669
+
1670
+ # Waterfall
1671
+
1672
+ > Trace or network spans as bars on one shared time axis; nested spans expand and collapse (treegrid), bars are colored by kind with the chart palette, and hover shows details.
1673
+
1674
+ Category: display · Status: beta · Slug: `waterfall`
1675
+
1676
+ ```tsx
1677
+ import { Waterfall, type WaterfallSpan } from '@peerproblem/sw3-ui'
1678
+ ```
1679
+
1680
+ ## When to use
1681
+ - Agent run traces (LLM calls, tool calls, DB queries).
1682
+ - Network request waterfalls.
1683
+ - Any set of timed, possibly nested operations.
1684
+
1685
+ ## Avoid
1686
+ - Values over time (traffic, latency trends). Use a LineChart or AreaChart in a ChartCard.
1687
+ - Ordered events without durations. Use Timeline.
1688
+ - More than a few hundred visible rows. Collapse by default (the default) or filter first.
1689
+
1690
+ ## Props
1691
+
1692
+ | Prop | Type | Default | Description |
1693
+ | --- | --- | --- | --- |
1694
+ | `items` * | `WaterfallSpan[] ({ value, label, start, duration, kind?, detail?, children? })` | | Spans in ms on one clock; `children` are nested spans. |
1695
+ | `aria-label` * | `string` | | Names the grid, e.g. "Trace for run 42". |
1696
+ | `range` | `[number, number]` | | Axis start/end in ms. Default: earliest start (or 0) to latest end. Change it to zoom. |
1697
+ | `value / defaultValue / onValueChange` | `string \| null` | | Selected span (click, Enter or Space). |
1698
+ | `expanded / defaultExpanded / onExpandedChange` | `string[] (defaultExpanded also 'all')` | `[] (collapsed)` | Which spans show their children. |
1699
+ | `kinds` | `Record<string, number \| string>` | | kind → chart color index 1–8 (var(--sw-chart-N)) or a CSS color. Unlisted kinds get the next color. |
1700
+ | `columns` | `{ key, header, render(span), width? }[]` | | Extra columns between the name and the bars. |
1701
+ | `marks` | `{ time: number; label: string }[]` | | Dashed vertical lines, e.g. first token. |
1702
+ | `maxTicks` | `number` | `5` | Most axis ticks (round times). |
1703
+ | `format` | `(ms: number) => string` | `"820 ms" / "1.24 s"` | Time formatting for the axis, labels and details. |
1704
+ | `nameHeader` | `ReactNode` | `'Span'` | Header of the name column. |
1705
+ | `legend` | `boolean` | `when >1 kind` | Legend of kinds under the grid. |
1706
+ | `framed` | `boolean` | `true` | Own 1px squircle frame with a 4px inset; row hover/selected fills are concentric with it. Set false inside a surface that already frames it. |
1707
+
1708
+ ## Examples
1709
+
1710
+ ### Agent trace
1711
+
1712
+ ```tsx
1713
+ <Waterfall aria-label="Trace for run 4821" defaultExpanded="all"
1714
+ kinds={{ llm: 1, db: 3, http: 4, tool: 5 }}
1715
+ items={[{ value: 'run', label: 'agent.run', start: 0, duration: 2840, children: [
1716
+ { value: 'plan', label: 'plan', start: 12, duration: 620, kind: 'llm' },
1717
+ { value: 'q', label: 'SELECT docs', start: 650, duration: 380, kind: 'db', detail: { Rows: '24' } },
1718
+ ] }]} />
1719
+ ```
1720
+
1721
+ ### Network requests with a column
1722
+
1723
+ ```tsx
1724
+ <Waterfall aria-label="Network" items={requests}
1725
+ columns={[{ key: 'status', header: 'Status', width: '48px', render: (r) => r.detail?.Status }]}
1726
+ marks={[{ time: 820, label: 'DOMContentLoaded' }]} />
1727
+ ```
1728
+
1729
+ ## Rules
1730
+ - Colors come from the chart palette by `kind`; keep kinds few (≤ 6) and map them with `kinds` so colors stay stable.
1731
+ - Put it full width; the bars need room. On phones the name column narrows automatically.
1732
+ - Use `detail` for extra facts (status, rows, tokens) instead of long labels.
1733
+ - Framed by default — do not wrap it in a Card. The selected row is a neutral fill + 500 label, not accent.
1734
+
1735
+ ## Accessibility
1736
+ - WAI-ARIA treegrid: rows have aria-level, aria-posinset, aria-setsize, aria-expanded (branches) and aria-selected. Each bar cell reads "Starts at X, lasts Y".
1737
+ - One tab stop. Up/Down, Home/End, Page Up/Down move; Right expands then moves to the first child; Left collapses then moves to the parent; Enter/Space selects; typing jumps by label.
1738
+
1739
+ ## DOM contract (for agents operating the page)
1740
+
1741
+ - Selector: `[data-sw="waterfall"]`
1742
+ - `data-state (row)`: 'open' | 'closed' on spans with children
1743
+ - `data-selected / aria-selected (row)`: the selected span
1744
+ - `data-value (row)`: span value
1745
+ - How to operate: Agent bridge: expand(value), collapse(value), toggle(value), expandAll(), collapseAll(), select(value) / setValue(value); items = every span with start + duration. DOM: rows are [data-sw="waterfall-row"][data-value]; click [data-sw="waterfall-indicator"] to toggle.
1746
+
1747
+ Related: `timeline`, `line-chart`, `chart-card`
1748
+
1749
+ ---