@peerproblem/sw3-ui 0.0.0-stage → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +109 -2
- package/agent/components/accordion.md +95 -0
- package/agent/components/action-square.md +106 -0
- package/agent/components/agent-bridge.md +87 -0
- package/agent/components/agent-console.md +123 -0
- package/agent/components/alert-dialog.md +82 -0
- package/agent/components/app-shell.md +105 -0
- package/agent/components/area-chart.md +56 -0
- package/agent/components/async-options.md +47 -0
- package/agent/components/autocomplete.md +69 -0
- package/agent/components/avatar.md +88 -0
- package/agent/components/badge.md +51 -0
- package/agent/components/bar-chart.md +56 -0
- package/agent/components/bar-list.md +49 -0
- package/agent/components/breadcrumbs.md +43 -0
- package/agent/components/button.md +109 -0
- package/agent/components/calendar.md +114 -0
- package/agent/components/canvas.md +105 -0
- package/agent/components/card.md +78 -0
- package/agent/components/carousel.md +113 -0
- package/agent/components/chart-card.md +41 -0
- package/agent/components/chart-surface.md +56 -0
- package/agent/components/checkbox.md +88 -0
- package/agent/components/citation-chip.md +61 -0
- package/agent/components/collapsible.md +69 -0
- package/agent/components/color-picker.md +82 -0
- package/agent/components/combobox.md +104 -0
- package/agent/components/command.md +92 -0
- package/agent/components/dashboard-grid.md +73 -0
- package/agent/components/date-input.md +87 -0
- package/agent/components/date-picker.md +122 -0
- package/agent/components/dialog.md +97 -0
- package/agent/components/donut-chart.md +50 -0
- package/agent/components/drawer.md +101 -0
- package/agent/components/empty-state.md +52 -0
- package/agent/components/field.md +80 -0
- package/agent/components/file-input.md +84 -0
- package/agent/components/hover-card.md +64 -0
- package/agent/components/image-cropper.md +77 -0
- package/agent/components/input.md +49 -0
- package/agent/components/label.md +53 -0
- package/agent/components/line-chart.md +60 -0
- package/agent/components/listbox.md +84 -0
- package/agent/components/map-view.md +104 -0
- package/agent/components/menu.md +117 -0
- package/agent/components/menubar.md +67 -0
- package/agent/components/meter.md +59 -0
- package/agent/components/navigation-menu.md +98 -0
- package/agent/components/number-input.md +81 -0
- package/agent/components/otp-input.md +67 -0
- package/agent/components/pagination.md +80 -0
- package/agent/components/password-input.md +67 -0
- package/agent/components/pill-button.md +116 -0
- package/agent/components/popover.md +85 -0
- package/agent/components/poster-card.md +61 -0
- package/agent/components/preferences.md +92 -0
- package/agent/components/progress.md +63 -0
- package/agent/components/provider.md +47 -0
- package/agent/components/radio.md +91 -0
- package/agent/components/rating.md +66 -0
- package/agent/components/reorder.md +61 -0
- package/agent/components/resizable.md +87 -0
- package/agent/components/scatter-chart.md +49 -0
- package/agent/components/scroll-area.md +81 -0
- package/agent/components/segmented-control.md +56 -0
- package/agent/components/select.md +130 -0
- package/agent/components/separator.md +60 -0
- package/agent/components/shortcuts.md +50 -0
- package/agent/components/sidebar-nav.md +68 -0
- package/agent/components/skeleton.md +58 -0
- package/agent/components/slider.md +79 -0
- package/agent/components/sparkline.md +39 -0
- package/agent/components/squircle.md +58 -0
- package/agent/components/stat.md +58 -0
- package/agent/components/switch.md +48 -0
- package/agent/components/table.md +58 -0
- package/agent/components/tabs.md +108 -0
- package/agent/components/textarea.md +68 -0
- package/agent/components/time-input.md +84 -0
- package/agent/components/timeline.md +91 -0
- package/agent/components/toast.md +85 -0
- package/agent/components/toggle.md +76 -0
- package/agent/components/token-input.md +66 -0
- package/agent/components/toolbar.md +76 -0
- package/agent/components/tooltip.md +83 -0
- package/agent/components/tracker.md +47 -0
- package/agent/components/tree.md +87 -0
- package/agent/components/treemap.md +72 -0
- package/agent/components/trend-chart.md +80 -0
- package/agent/components/trigger-menu.md +67 -0
- package/agent/components/typography.md +51 -0
- package/agent/components/waterfall.md +78 -0
- package/agent/components/week-schedule.md +113 -0
- package/agent/llms/actions-and-layout.txt +1749 -0
- package/agent/llms/agents.txt +505 -0
- package/agent/llms/charts.txt +778 -0
- package/agent/llms/dashboards.txt +457 -0
- package/agent/llms/extend.txt +132 -0
- package/agent/llms/extras.txt +527 -0
- package/agent/llms/forms.txt +2152 -0
- package/agent/llms/foundations.txt +674 -0
- package/agent/llms/hooks.txt +178 -0
- package/agent/llms/maps.txt +229 -0
- package/agent/llms/overlays-and-navigation.txt +1167 -0
- package/agent/llms-full.txt +8717 -0
- package/agent/llms.txt +145 -0
- package/agent/registry.json +11289 -0
- package/agent/tokens.md +66 -0
- package/dist/agent/index.d.ts +235 -0
- package/dist/agent/index.js +21 -0
- package/dist/card-Ipm-Cj5f.d.ts +490 -0
- package/dist/charts/index.d.ts +289 -0
- package/dist/charts/index.js +815 -0
- package/dist/check/cli.d.ts +1 -0
- package/dist/check/cli.js +48 -0
- package/dist/check/rendered.d.ts +11 -0
- package/dist/check/rendered.js +77 -0
- package/dist/check/source.d.ts +13 -0
- package/dist/check/source.js +182 -0
- package/dist/chunk-3DXBM65D.js +65 -0
- package/dist/chunk-3H5X4ZP6.js +55 -0
- package/dist/chunk-6XC4BC5C.js +92 -0
- package/dist/chunk-7H6TEAWD.js +507 -0
- package/dist/chunk-I63ZTJOI.js +1089 -0
- package/dist/chunk-JCIRUM4W.js +33 -0
- package/dist/chunk-LTBEHZ3P.js +25 -0
- package/dist/chunk-QDPPLO4U.js +60 -0
- package/dist/chunk-U2XFBPU4.js +56 -0
- package/dist/chunk-UY2WH5AY.js +681 -0
- package/dist/extras.d.ts +203 -0
- package/dist/extras.js +904 -0
- package/dist/icons-BJiGEAnU.d.ts +68 -0
- package/dist/index.d.ts +3737 -0
- package/dist/index.js +14477 -0
- package/dist/map/index.d.ts +115 -0
- package/dist/map/index.js +394 -0
- package/dist/meta/index.d.ts +3314 -0
- package/dist/meta/index.js +5106 -0
- package/dist/rules-1RIZ_JZr.d.ts +38 -0
- package/dist/styles.css +4037 -0
- package/dist/themes/calm.css +42 -0
- package/dist/themes/frost.css +40 -0
- package/package.json +142 -4
|
@@ -0,0 +1,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
|
+
---
|