@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,81 @@
|
|
|
1
|
+
# ScrollArea
|
|
2
|
+
|
|
3
|
+
> Native scrolling with slim overlay scrollbars, edge fades, and an optional stick-to-bottom mode for chat logs.
|
|
4
|
+
|
|
5
|
+
Category: layout · Status: beta · Slug: `scroll-area`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { ScrollArea } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Fixed-height panes: sidebars, popover lists, code and log output.
|
|
13
|
+
- Chat transcripts and streamed agent output (followEnd).
|
|
14
|
+
- Horizontal rails of cards (orientation="horizontal").
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- The whole page — let the document scroll.
|
|
18
|
+
- Tiny boxes where the fade hides most content — set fades={false}.
|
|
19
|
+
- Nesting scroll areas on the same axis.
|
|
20
|
+
|
|
21
|
+
## Props
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which axes scroll. |
|
|
26
|
+
| `type` | `'hover' \| 'scroll' \| 'auto' \| 'always'` | `'hover'` | When scrollbars show: on hover or scroll, only while scrolling, whenever it overflows, or always. |
|
|
27
|
+
| `fades` | `boolean` | `true` | Fade edges that have more content beyond them. |
|
|
28
|
+
| `followEnd` | `boolean` | `false` | Start at the end and stay there as content grows; scrolling up lets go, returning to the end sticks again. |
|
|
29
|
+
| `scrollToEndButton` | `boolean` | `true` | With followEnd: a "Jump to latest" pill while away from the end. |
|
|
30
|
+
| `scrollToEndLabel` | `string` | `'Jump to latest'` | Text of that pill. |
|
|
31
|
+
| `scrollHideDelay` | `number` | `700` | ms the bars linger after scrolling. |
|
|
32
|
+
| `maxHeight` | `CSS length` | | Cap the height (or set height via style/className). |
|
|
33
|
+
| `aria-label` | `string` | | Makes the viewport a named region. |
|
|
34
|
+
| `role` | `string` | | Role for the viewport, e.g. "log" for a chat. |
|
|
35
|
+
| `viewportProps` | `HTMLAttributes<HTMLDivElement>` | | Extra props for the native scrolling element. |
|
|
36
|
+
| `ref` | `Ref<{ viewport; scrollToEnd(behavior?); scrollToStart(behavior?) }>` | | Imperative handle. |
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
40
|
+
### Fixed-height list
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
<ScrollArea maxHeight={280} aria-label="Recent runs">
|
|
44
|
+
{runs.map((r) => <RunRow key={r.id} run={r} />)}
|
|
45
|
+
</ScrollArea>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Chat log that follows new messages
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
<ScrollArea followEnd role="log" aria-label="Conversation" style={{ height: 360 }}>
|
|
52
|
+
{messages.map((m) => <Message key={m.id} {...m} />)}
|
|
53
|
+
</ScrollArea>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Horizontal rail
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
<ScrollArea orientation="horizontal">
|
|
60
|
+
<div style={{ display: 'flex', gap: 12 }}>{cards}</div>
|
|
61
|
+
</ScrollArea>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Rules
|
|
65
|
+
- Give it a height (height, maxHeight or a flex parent); otherwise it just grows.
|
|
66
|
+
- Keep keyboard access: the viewport becomes a tab stop when it scrolls and holds nothing focusable.
|
|
67
|
+
|
|
68
|
+
## Accessibility
|
|
69
|
+
- The viewport is the real, native scroller: wheel, touch, keys and screen-reader scrolling all work.
|
|
70
|
+
- Overlay scrollbars are aria-hidden.
|
|
71
|
+
- Use role="log" for chat transcripts.
|
|
72
|
+
|
|
73
|
+
## DOM contract (for agents operating the page)
|
|
74
|
+
|
|
75
|
+
- Selector: `[data-sw="scroll-area"]`
|
|
76
|
+
- `data-overflow-y / data-overflow-x`: present while content overflows
|
|
77
|
+
- `data-at-start / data-at-end`: present at the edges
|
|
78
|
+
- `data-sticking`: present while followEnd is holding the end
|
|
79
|
+
- How to operate: Scroll [data-sw="scroll-area-viewport"] (element.scrollTop). Agent bridge: scrollToEnd(), scrollToStart(); state = { atStart, atEnd, sticking }.
|
|
80
|
+
|
|
81
|
+
Related: `resizable`
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# SegmentedControl
|
|
2
|
+
|
|
3
|
+
> Pick one of 2–5 options; the active pill glides between segments (motion layout animation).
|
|
4
|
+
|
|
5
|
+
Category: selection · Status: stable · Slug: `segmented-control`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { SegmentedControl } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Switching between mutually exclusive views.
|
|
13
|
+
- Time ranges on charts (Week / Month / Year).
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- More than 5 options or long labels — use Tabs or a select.
|
|
17
|
+
- Formatting buttons in a toolbar, or a choice that can be empty — use ToggleGroup.
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `options` * | `Array<{ value: string; label: ReactNode; disabled?: boolean }>` | | The segments. |
|
|
24
|
+
| `value` * | `string` | | Selected value. |
|
|
25
|
+
| `onValueChange` * | `(value) => void` | | |
|
|
26
|
+
| `aria-label` * | `string` | | Names the control. |
|
|
27
|
+
| `size` | `'sm' \| 'md'` | `'md'` | |
|
|
28
|
+
| `appearance` | `'default' \| 'icon-capsule'` | `'default'` | Icon-only options use a smooth capsule track and a circular selected marker. Give each icon an accessible text label. |
|
|
29
|
+
| `fullWidth` | `boolean` | `false` | Equal-width segments filling the container. |
|
|
30
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'sm'` | Squircle corner radius (token or px). |
|
|
31
|
+
|
|
32
|
+
## Examples
|
|
33
|
+
|
|
34
|
+
### Chart range
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
<SegmentedControl
|
|
38
|
+
aria-label="Range"
|
|
39
|
+
value={range}
|
|
40
|
+
onValueChange={setRange}
|
|
41
|
+
options={[{ value: 'week', label: 'Week' }, { value: 'month', label: 'Month' }, { value: 'year', label: 'Year' }]}
|
|
42
|
+
/>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Rules
|
|
46
|
+
- The default pill is concentric with the track (track radius − 3px). Both appearances show a focus ring on the selected marker.
|
|
47
|
+
- Set `--sw-segmented-track-bg` on an ancestor to distinguish the track from the surrounding surface. Keep the selected marker distinct from the track.
|
|
48
|
+
|
|
49
|
+
## Accessibility
|
|
50
|
+
- role="radiogroup"; Arrow keys move and select.
|
|
51
|
+
|
|
52
|
+
## DOM contract (for agents operating the page)
|
|
53
|
+
|
|
54
|
+
- Selector: `[data-sw="segmented-control"]`
|
|
55
|
+
- `[role=radio][aria-checked=true]`: the selected segment
|
|
56
|
+
- How to operate: Click the segment button with the matching text.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Select
|
|
2
|
+
|
|
3
|
+
> Pick one or several options from a popup list, with groups, optional search inside the dropdown, and a native form value.
|
|
4
|
+
|
|
5
|
+
Category: selection · Status: beta · Slug: `select`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectSeparator } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Choosing from known options such as models, regions, or roles.
|
|
13
|
+
- Use `searchable` when search belongs inside the dropdown and the closed trigger should show the selected value.
|
|
14
|
+
- Inside forms: pass `name` and it submits like a native select.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Search that starts in the field itself, or server-filtered options — use Combobox.
|
|
18
|
+
- 2–4 options always visible — use SegmentedControl or a Radio group.
|
|
19
|
+
- Running actions — use Menu.
|
|
20
|
+
- Free text — use Autocomplete or Input.
|
|
21
|
+
|
|
22
|
+
## Props
|
|
23
|
+
|
|
24
|
+
| Prop | Type | Default | Description |
|
|
25
|
+
| --- | --- | --- | --- |
|
|
26
|
+
| `items` | `Array<{ value: string; label: string; keywords?: string[]; disabled?: boolean; icon?: ReactNode; description?: ReactNode } \| { type: 'group'; label: string; items: [...] } \| { type: 'separator' }>` | | Options as data — the one-line way. Or pass `<SelectItem>` children instead. |
|
|
27
|
+
| `value / defaultValue / onValueChange` | `string \| null (string[] with multiple)` | | Selected value(s). `onValueChange(null)` when cleared. |
|
|
28
|
+
| `multiple` | `boolean` | `false` | Pick several; the list stays open while toggling; the trigger shows "A, B +2". |
|
|
29
|
+
| `searchable` | `boolean` | `false` | Show a search input inside the dropdown. Filters option labels and keywords and clears the query when closed. |
|
|
30
|
+
| `searchPlaceholder / searchLabel` | `string / string` | `"Search options…" / "Search options"` | Search input placeholder and accessible name. |
|
|
31
|
+
| `placeholder` | `string` | | Shown while nothing is selected. |
|
|
32
|
+
| `label` | `ReactNode` | | Visible label above the trigger (leave out inside Field). |
|
|
33
|
+
| `open / defaultOpen / onOpenChange` | `boolean` | | Popup state. |
|
|
34
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field heights 32 / 40 / 52px, like Input. |
|
|
35
|
+
| `name` | `string` | | Native form field name; the value submits through hidden inputs (one per value when multiple). |
|
|
36
|
+
| `disabled / readOnly / required / invalid` | `boolean` | | States. Inherit from a surrounding `<Field>`. |
|
|
37
|
+
| `aria-label` | `string` | | Accessible name when there is no visible label or Field. |
|
|
38
|
+
| `form` | `string` | | Id of a form the hidden inputs belong to. |
|
|
39
|
+
| `SelectItem: value, label?, disabled?, icon?, description?` | `props` | | `label` is what the trigger shows when children are not plain text. |
|
|
40
|
+
| `SelectGroup: label` | `ReactNode` | | Heading of a group of SelectItems. |
|
|
41
|
+
| `SelectTrigger: asChild?, icon?` | `props` | | Customise the trigger (leading icon) or clone your own element. |
|
|
42
|
+
| `SelectValue: placeholder?, maxLabels?` | `props` | | What the trigger shows. `maxLabels` (default 2) before "+N". |
|
|
43
|
+
| `SelectContent: placement?, emptyMessage?` | `props` | | Popup placement (default bottom-start, matches trigger width). |
|
|
44
|
+
|
|
45
|
+
## Anatomy
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
Select
|
|
49
|
+
├─ trigger shows the value, opens the popup
|
|
50
|
+
└─ popup PopupPanel
|
|
51
|
+
├─ search optional
|
|
52
|
+
└─ list groups and items
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Built from: `PopupPanel (usePopup)`, `useListNavigation`, `useSquircle`.
|
|
56
|
+
|
|
57
|
+
## Examples
|
|
58
|
+
|
|
59
|
+
### One line with items
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
<Select
|
|
63
|
+
label="Model"
|
|
64
|
+
name="model"
|
|
65
|
+
placeholder="Choose a model"
|
|
66
|
+
defaultValue="sonnet"
|
|
67
|
+
items={[
|
|
68
|
+
{ value: 'opus', label: 'Opus', description: 'Most capable' },
|
|
69
|
+
{ value: 'sonnet', label: 'Sonnet' },
|
|
70
|
+
{ value: 'haiku', label: 'Haiku' },
|
|
71
|
+
]}
|
|
72
|
+
/>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Search inside the dropdown
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
<Select label="Model" searchable searchLabel="Search models" searchPlaceholder="Search models…" items={[
|
|
79
|
+
{ value: 'opus', label: 'Opus' },
|
|
80
|
+
{ value: 'sonnet', label: 'Sonnet' },
|
|
81
|
+
{ value: 'haiku', label: 'Haiku' },
|
|
82
|
+
]} />
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Children with groups
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
<Select aria-label="Region" value={region} onValueChange={setRegion} placeholder="Region">
|
|
89
|
+
<SelectGroup label="Europe">
|
|
90
|
+
<SelectItem value="fra">Frankfurt</SelectItem>
|
|
91
|
+
<SelectItem value="hel">Helsinki</SelectItem>
|
|
92
|
+
</SelectGroup>
|
|
93
|
+
<SelectSeparator />
|
|
94
|
+
<SelectItem value="iad">Washington, D.C.</SelectItem>
|
|
95
|
+
</Select>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Multiple inside a Field
|
|
99
|
+
|
|
100
|
+
```tsx
|
|
101
|
+
<Field label="Notify on">
|
|
102
|
+
<Select multiple name="events" defaultValue={['fail']} items={[
|
|
103
|
+
{ value: 'start', label: 'Run started' },
|
|
104
|
+
{ value: 'fail', label: 'Run failed' },
|
|
105
|
+
{ value: 'done', label: 'Run finished' },
|
|
106
|
+
]} />
|
|
107
|
+
</Field>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Rules
|
|
111
|
+
- Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
|
|
112
|
+
- Option labels are nouns in sentence case; keep them short so the trigger never truncates.
|
|
113
|
+
- Always give a placeholder or a default value.
|
|
114
|
+
|
|
115
|
+
## Accessibility
|
|
116
|
+
- By default the trigger is a select-only combobox and keeps focus while the list is open. Arrow keys move, Home/End jump, typing jumps by label, and Enter/Space choose.
|
|
117
|
+
- In searchable mode a button opens a dialog with an editable combobox and a listbox. Focus moves to the search input. ArrowUp/ArrowDown move through enabled results and Enter chooses. Escape returns focus to the trigger. Tab or Shift+Tab closes and continues from the trigger.
|
|
118
|
+
|
|
119
|
+
## DOM contract (for agents operating the page)
|
|
120
|
+
|
|
121
|
+
- Selector: `[data-sw="select"]`
|
|
122
|
+
- `aria-expanded`: true while the list is open (on the trigger / input)
|
|
123
|
+
- `aria-activedescendant`: id of the highlighted option while open
|
|
124
|
+
- `aria-selected`: on each [role=option]: whether it is chosen
|
|
125
|
+
- `data-value`: on each option: its value
|
|
126
|
+
- `data-state`: root: 'open' | 'closed'
|
|
127
|
+
- `data-disabled / data-invalid`: present when disabled / invalid
|
|
128
|
+
- How to operate: Click [data-sw="select-trigger"], optionally type into [data-sw="select-search"], then choose an enabled [role=option]. The popup [data-sw="select-content"] is portaled. Agent bridge: setValue(value | value[] | null), select(value), clear(), open(), close(). Use option IDs or unique full labels. Null clears the selection.
|
|
129
|
+
|
|
130
|
+
Related: `combobox`, `listbox`, `segmented-control`, `field`
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Separator
|
|
2
|
+
|
|
3
|
+
> A 1px hairline between groups of content, horizontal or vertical, optionally with a mono caption ("OR").
|
|
4
|
+
|
|
5
|
+
Category: layout · Status: beta · Slug: `separator`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Separator } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Dividing sections of a panel, menu or toolbar.
|
|
13
|
+
- "or" between alternative sign-in methods: `label="or"`.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Separating every list row — use spacing.
|
|
17
|
+
- Decorative lines announced to screen readers — set `decorative`.
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical needs a flex row parent. |
|
|
24
|
+
| `decorative` | `boolean` | `false` | role="none" — skip it for assistive tech. |
|
|
25
|
+
| `label` | `ReactNode` | | Caption in the middle (horizontal only). |
|
|
26
|
+
| `tone` | `'hairline' \| 'frame'` | `'hairline'` | Line strength. |
|
|
27
|
+
|
|
28
|
+
## Examples
|
|
29
|
+
|
|
30
|
+
### Between sections
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
<Separator />
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Or
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
<Button fullWidth>Continue with GitHub</Button>
|
|
40
|
+
<Separator label="or" decorative />
|
|
41
|
+
<Input label="Email" />
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Vertical
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
<div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
|
|
48
|
+
<span>Docs</span><Separator orientation="vertical" /><span>API</span>
|
|
49
|
+
</div>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Accessibility
|
|
53
|
+
- role="separator" with aria-orientation when vertical; never focusable.
|
|
54
|
+
|
|
55
|
+
## DOM contract (for agents operating the page)
|
|
56
|
+
|
|
57
|
+
- Selector: `[data-sw="separator"]`
|
|
58
|
+
- `data-orientation`: horizontal | vertical
|
|
59
|
+
|
|
60
|
+
Related: `card`
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# useShortcut
|
|
2
|
+
|
|
3
|
+
> Keyboard shortcuts with platform-aware hints. `mod` is ⌘ on Apple and Ctrl elsewhere. `shortcuts.list()` exposes them to agents.
|
|
4
|
+
|
|
5
|
+
Category: hooks · Status: beta · Slug: `shortcuts`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { useShortcut, useShortcutHint, shortcuts, formatShortcut } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- App-level actions: save, new, search (⌘K), toggle sidebar.
|
|
13
|
+
- Showing the key next to a button or menu item.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Single-letter shortcuts that fire while typing. They are skipped in fields unless `allowInInput`.
|
|
17
|
+
- Overriding browser shortcuts people rely on (⌘W, ⌘T, ⌘L).
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `useShortcut(keys, handler, options?)` | `(keys: string \| null, handler, { description?, allowInInput?, when?, scope?, preventDefault? })` | | Keys like "mod+s", "shift+?", "escape". Unregisters on unmount; null keys = off. |
|
|
24
|
+
| `useShortcutHint(keys)` | `{ text: string; ariaKeyshortcuts: string }` | | ⌘S / Ctrl+S plus the aria-keyshortcuts value. |
|
|
25
|
+
| `shortcuts.setScope(name, active)` | `void` | | Turn scoped shortcuts on while an area has focus. |
|
|
26
|
+
| `shortcuts.list()` | `{ keys, text, description, scope, active }[]` | | All registered shortcuts (help dialog, agents). |
|
|
27
|
+
|
|
28
|
+
## Examples
|
|
29
|
+
|
|
30
|
+
### Save with a hint
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
function SaveButton({ onSave }: { onSave(): void }) {
|
|
34
|
+
useShortcut('mod+s', onSave, { description: 'Save' })
|
|
35
|
+
const hint = useShortcutHint('mod+s')
|
|
36
|
+
return (
|
|
37
|
+
<Button onClick={onSave} aria-keyshortcuts={hint.ariaKeyshortcuts} trailing={<Kbd>{hint.text}</Kbd>}>Save</Button>
|
|
38
|
+
)
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Rules
|
|
43
|
+
- Always show the shortcut somewhere (button hint, menu item, help). Hidden shortcuts help nobody.
|
|
44
|
+
|
|
45
|
+
## DOM contract (for agents operating the page)
|
|
46
|
+
|
|
47
|
+
- Selector: `[aria-keyshortcuts]`
|
|
48
|
+
- How to operate: Agents can read shortcuts.list() or aria-keyshortcuts; prefer the bridge actions over synthesizing key events.
|
|
49
|
+
|
|
50
|
+
Related: `command`, `menu`, `kbd`
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# SidebarNav
|
|
2
|
+
|
|
3
|
+
> Dense sidebar navigation: 28px rows with icons, counts and hover actions, plus groups that fold. In the rail it becomes icon buttons with tooltips.
|
|
4
|
+
|
|
5
|
+
Category: navigation · Status: beta · Slug: `sidebar-nav`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { SidebarNav, SidebarGroup, SidebarItem } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Primary navigation in an AppShellSidebar.
|
|
13
|
+
- Lists of saved views, projects or teams with counts.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- More than 2 levels. Use a Tree in a panel, or a drill-in page.
|
|
17
|
+
- Rows without icons in a sidebar that folds to a rail. Rows without an icon are hidden in the rail.
|
|
18
|
+
- Putting the only path to an action in hover-only row actions.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `SidebarItem.label` * | `string` | | Row text. In the rail it becomes the tooltip and accessible name. |
|
|
25
|
+
| `SidebarItem.icon` | `ReactNode` | | 15px icon. Required for the row to show in the rail. |
|
|
26
|
+
| `SidebarItem.active` | `boolean` | | Current page: neutral fill, weight 500, aria-current="page". |
|
|
27
|
+
| `SidebarItem.count` | `ReactNode` | | Trailing count (mono, tabular). Hover actions take its place. |
|
|
28
|
+
| `SidebarItem.actions` | `ReactNode` | | One or two `Button size="2xs" variant="ghost" iconOnly` (in a Tooltip), shown on hover or focus and always on touch. |
|
|
29
|
+
| `SidebarItem.level` | `0 \| 1 \| 2` | `0` | Indent to line up under a parent label. |
|
|
30
|
+
| `SidebarItem.href / onClick` | `string / function` | | Renders a link with href, otherwise a button. Choosing an item closes the sheet on narrow layouts. |
|
|
31
|
+
| `SidebarGroup.label` * | `string` | | 11px group label. It is the fold button. |
|
|
32
|
+
| `SidebarGroup.count` | `ReactNode` | | Shown while folded. |
|
|
33
|
+
| `SidebarGroup.actions` | `ReactNode` | | Hover actions on the group row, e.g. "New project". |
|
|
34
|
+
| `SidebarGroup.collapsible / open / defaultOpen / onOpenChange` | `boolean` | `true / – / true` | Fold state. |
|
|
35
|
+
|
|
36
|
+
## Examples
|
|
37
|
+
|
|
38
|
+
### Groups, counts and hover actions
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
<SidebarNav aria-label="Workspace">
|
|
42
|
+
<SidebarItem icon={<Icon name="home" />} label="Overview" active href="#/" />
|
|
43
|
+
<SidebarItem icon={<Icon name="inbox" />} label="Inbox" count={12} href="#/inbox" />
|
|
44
|
+
<SidebarGroup label="Projects" count={3} actions={<Tooltip content="New project"><Button size="2xs" variant="ghost" iconOnly aria-label="New project" leading={<Icon name="plus" />} /></Tooltip>}>
|
|
45
|
+
<SidebarItem icon={<Icon name="folder" />} label="API" href="#/api" />
|
|
46
|
+
<SidebarItem icon={<Icon name="folder" />} label="Billing" href="#/billing" />
|
|
47
|
+
</SidebarGroup>
|
|
48
|
+
</SidebarNav>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Rules
|
|
52
|
+
- Rows are 28px with 13px labels. Groups are 12px apart and rows 1px apart.
|
|
53
|
+
- Selection is a neutral fill with weight 500. Never use color or bold alone.
|
|
54
|
+
- Hover actions replace the count in the same slot. Nothing shifts on hover.
|
|
55
|
+
|
|
56
|
+
## Accessibility
|
|
57
|
+
- Rendered as <nav> with an aria-label. Group labels are buttons with aria-expanded. Folded groups are inert.
|
|
58
|
+
- In the rail each icon button is named by its label.
|
|
59
|
+
|
|
60
|
+
## DOM contract (for agents operating the page)
|
|
61
|
+
|
|
62
|
+
- Selector: `[data-sw="sidebar-nav"]`
|
|
63
|
+
- `data-active`: on the current [data-sw="sidebar-item"]
|
|
64
|
+
- `data-state`: open | closed on [data-sw="sidebar-group"]
|
|
65
|
+
- `data-collapsed`: on the nav while in the rail
|
|
66
|
+
- How to operate: Click [data-sw="sidebar-item"]. Agent bridge on groups: open(), close(), toggle().
|
|
67
|
+
|
|
68
|
+
Related: `app-shell`, `tree`, `navigation-menu`
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Skeleton
|
|
2
|
+
|
|
3
|
+
> A static squircle placeholder that reserves space while content loads.
|
|
4
|
+
|
|
5
|
+
Category: display · Status: beta · Slug: `skeleton`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Skeleton } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Reserving space for text, images, or rows while a region loads.
|
|
13
|
+
|
|
14
|
+
## Avoid
|
|
15
|
+
- Communicating progress or loading status through decorative shapes alone.
|
|
16
|
+
|
|
17
|
+
## Props
|
|
18
|
+
|
|
19
|
+
| Prop | Type | Default | Description |
|
|
20
|
+
| --- | --- | --- | --- |
|
|
21
|
+
| `width` | `CSSProperties['width']` | `'100%'` | Width in CSS units or pixels. |
|
|
22
|
+
| `height` | `CSSProperties['height']` | `'1em' or '0.7em' inline` | Height in CSS units or pixels. |
|
|
23
|
+
| `inline` | `boolean` | `false` | Use inside the final Heading or Text so line height and spacing come from the same typography. |
|
|
24
|
+
| `radius` | `RadiusValue` | `'xs'` | Squircle radius token or pixels. |
|
|
25
|
+
| `className` | `string` | | Additional class names. |
|
|
26
|
+
| `style` | `CSSProperties` | | Additional inline styles. |
|
|
27
|
+
|
|
28
|
+
## Examples
|
|
29
|
+
|
|
30
|
+
### Loading a summary
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
<>
|
|
34
|
+
<p role="status">{loading ? 'Loading summary…' : 'Summary loaded.'}</p>
|
|
35
|
+
<section aria-label="Summary" aria-busy={loading}>
|
|
36
|
+
<Heading as="h3" size="sm" aria-hidden={loading || undefined}>
|
|
37
|
+
{loading ? <Skeleton inline width="8ch" /> : title}
|
|
38
|
+
</Heading>
|
|
39
|
+
<Text size="sm">{loading ? <Skeleton inline width="22ch" /> : summary}</Text>
|
|
40
|
+
</section>
|
|
41
|
+
</>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Rules
|
|
45
|
+
- Keep typography, gaps and padding shared between loading and loaded content.
|
|
46
|
+
- Use inline placeholders for text and reserve the expected number of lines for content that wraps.
|
|
47
|
+
|
|
48
|
+
## Accessibility
|
|
49
|
+
- Placeholders are decorative, always aria-hidden, and stay out of the tab order.
|
|
50
|
+
- Set aria-busy on the affected region. Keep one persistent role="status" element outside that region for loading and completion announcements.
|
|
51
|
+
|
|
52
|
+
## DOM contract (for agents operating the page)
|
|
53
|
+
|
|
54
|
+
- Selector: `[data-sw="skeleton"]`
|
|
55
|
+
- `aria-hidden`: true
|
|
56
|
+
- How to operate: Decorative placeholder with no agent action.
|
|
57
|
+
|
|
58
|
+
Related: `progress`, `squircle`
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Slider
|
|
2
|
+
|
|
3
|
+
> Pick a number or a range by dragging or with the keyboard. Steps, marks, Intl-formatted value and onValueCommit for saving.
|
|
4
|
+
|
|
5
|
+
Category: inputs · Status: beta · Slug: `slider`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Slider } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Approximate values where position matters more than the exact number (temperature, volume, budget range).
|
|
13
|
+
- A min–max range filter: `defaultValue={[20, 80]}`.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Exact numbers people type — use NumberInput.
|
|
17
|
+
- Saving on every drag step — use `onValueCommit`.
|
|
18
|
+
- Huge ranges with tiny steps — use NumberInput or add marks.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `value` | `number \| [number, number]` | | Controlled value; a tuple makes a range with two thumbs. |
|
|
25
|
+
| `defaultValue` | `number \| [number, number]` | `min` | Initial value. |
|
|
26
|
+
| `onValueChange` | `(value) => void` | | Every step of a drag or key press. |
|
|
27
|
+
| `onValueCommit` | `(value) => void` | | Once when the drag or key press ends. |
|
|
28
|
+
| `min / max / step` | `number` | `0 / 100 / 1` | Bounds and step. |
|
|
29
|
+
| `largeStep` | `number` | `10 × step` | PageUp/PageDown and Shift+Arrow. |
|
|
30
|
+
| `minStepsBetweenThumbs` | `number` | `0` | Range: minimum gap in steps. |
|
|
31
|
+
| `label` | `ReactNode` | | Label above the track (or use Field). |
|
|
32
|
+
| `showValue` | `boolean` | `!!label` | Show the formatted value at the top right. |
|
|
33
|
+
| `marks` | `Array<number \| { value, label? }>` | | Ticks; labelled ones show text under the track. |
|
|
34
|
+
| `formatOptions` | `Intl.NumberFormatOptions` | | Value text, e.g. `{ style: "currency", currency: "USD" }`. Percent = position in the range. |
|
|
35
|
+
| `locale` | `string` | | Formatting locale (default: page lang after mount). |
|
|
36
|
+
| `thumbLabels` | `[string, string]` | `['Minimum', 'Maximum']` | Range thumb names. |
|
|
37
|
+
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical grows upward. |
|
|
38
|
+
| `name` | `string` | | Form name; submits the number (range "start/end"). |
|
|
39
|
+
| `disabled / readOnly` | `boolean` | | States. |
|
|
40
|
+
| `size` | `'sm' \| 'md'` | `'md'` | Thumb 16 / 20px. |
|
|
41
|
+
| `aria-label` | `string` | | Name when there is no label/Field. |
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
### Single
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
<Slider label="Temperature" defaultValue={0.7} min={0} max={2} step={0.1} />
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Range with currency
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
<Slider label="Monthly budget" defaultValue={[200, 800]} min={0} max={1000} step={50}
|
|
55
|
+
formatOptions={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }} onValueCommit={save} />
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Marks
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
<Slider aria-label="Reasoning effort" defaultValue={2} min={1} max={3}
|
|
62
|
+
marks={[{ value: 1, label: 'Low' }, { value: 2, label: 'Med' }, { value: 3, label: 'High' }]} />
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Rules
|
|
66
|
+
- Always show the value (label + showValue) when the exact number matters.
|
|
67
|
+
|
|
68
|
+
## Accessibility
|
|
69
|
+
- Each thumb is role="slider" with aria-valuenow/min/max/valuetext. Arrows ±step, Shift/PageUp/PageDown ±largeStep, Home/End to the ends. The root is role="group".
|
|
70
|
+
|
|
71
|
+
## DOM contract (for agents operating the page)
|
|
72
|
+
|
|
73
|
+
- Selector: `[data-sw="slider"]`
|
|
74
|
+
- `aria-valuenow`: on each [data-sw="slider-thumb"]
|
|
75
|
+
- `data-range`: present for two thumbs
|
|
76
|
+
- `data-dragging`: present while dragging
|
|
77
|
+
- How to operate: Focus a [data-sw="slider-thumb"] and press arrow keys, or click the track. Agent bridge: setValue(number | [a, b]), increment(), decrement().
|
|
78
|
+
|
|
79
|
+
Related: `number-input`, `field`
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Sparkline
|
|
2
|
+
|
|
3
|
+
> A tiny axis-less trend line for Stats and table cells.
|
|
4
|
+
|
|
5
|
+
Category: charts · Status: beta · Slug: `sparkline`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Sparkline } from '@peerproblem/sw3-ui/charts'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Inside <Stat> or a table cell to show direction.
|
|
13
|
+
|
|
14
|
+
## Avoid
|
|
15
|
+
- As the main chart — it has no axes.
|
|
16
|
+
|
|
17
|
+
## Props
|
|
18
|
+
|
|
19
|
+
| Prop | Type | Default | Description |
|
|
20
|
+
| --- | --- | --- | --- |
|
|
21
|
+
| `data` * | `number[]` | | |
|
|
22
|
+
| `color` | `string` | | Default --sw-chart-1. |
|
|
23
|
+
| `height` | `number` | `36` | |
|
|
24
|
+
| `area` | `boolean` | `true` | Soft fill under the line. |
|
|
25
|
+
|
|
26
|
+
## Examples
|
|
27
|
+
|
|
28
|
+
### In a Stat
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
<Stat label="Visitors" value="12.4k" delta="+8%"><Sparkline data={[4, 8, 6, 9, 12]} /></Stat>
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## DOM contract (for agents operating the page)
|
|
35
|
+
|
|
36
|
+
- Selector: `[data-sw="chart"]`
|
|
37
|
+
- `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
|
|
38
|
+
- `aria-label`: the summary
|
|
39
|
+
- How to operate: Read aria-label for the meaning; charts are not interactive controls.
|