@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,1167 @@
|
|
|
1
|
+
# SW3 UI SDK · Overlays and navigation
|
|
2
|
+
|
|
3
|
+
> Dialogs, drawers, popovers, menus, tooltips; tabs, command palette, pagination, breadcrumbs, navigation menus.
|
|
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
|
+
# Popover
|
|
14
|
+
|
|
15
|
+
> A small non-modal dialog anchored to its trigger for a quick task with form content: share a link, rename, filter with fields.
|
|
16
|
+
|
|
17
|
+
Category: overlays · Status: beta · Slug: `popover`
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose } from '@peerproblem/sw3-ui'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## When to use
|
|
24
|
+
- A short task tied to one control (share, rename, filter) that should not leave the page.
|
|
25
|
+
- Form content beside a trigger: text fields, a filter panel with inputs, Apply/Cancel buttons.
|
|
26
|
+
|
|
27
|
+
## Avoid
|
|
28
|
+
- Plain-text hints → use Tooltip.
|
|
29
|
+
- A link preview on hover → use HoverCard.
|
|
30
|
+
- Long forms or anything needing full attention → use Dialog (or Drawer on phones).
|
|
31
|
+
- A list of commands → use a Menu.
|
|
32
|
+
- Only on/off settings, with no text field or buttons → use a Menu with MenuCheckboxItem (it stays open while people toggle several).
|
|
33
|
+
|
|
34
|
+
## Props
|
|
35
|
+
|
|
36
|
+
| Prop | Type | Default | Description |
|
|
37
|
+
| --- | --- | --- | --- |
|
|
38
|
+
| `open` | `boolean` | | Controlled open state of the popover. |
|
|
39
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
40
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
41
|
+
| `modal` | `boolean` | `false` | Trap focus and lock page scroll. By default Tab out or a press outside closes it. |
|
|
42
|
+
| `PopoverTrigger.…ButtonProps` | `ButtonProps` | | Default trigger is an outline Button; any Button prop works. |
|
|
43
|
+
| `PopoverTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default Button. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
|
|
44
|
+
| `PopoverContent.side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Side of the trigger. Flips when there is no room. |
|
|
45
|
+
| `PopoverContent.align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along that side. |
|
|
46
|
+
| `PopoverContent.sideOffset` | `number` | `6` | Gap to the trigger in px. |
|
|
47
|
+
| `PopoverContent.padding` | `'none' \| 'sm' \| 'md'` | `'md'` | Inner padding 0 / 12 / 16px; blocks 16px apart (12 for sm), title → description 6px. Width is 20rem; override with --sw-popover-width. |
|
|
48
|
+
| `PopoverContent.initialFocus` | `RefObject<HTMLElement>` | | Element focused on open. Default: [data-autofocus], else the first focusable, else the panel. |
|
|
49
|
+
| `PopoverTitle / PopoverDescription` | `ReactNode` | | h2 / p; wired to aria-labelledby / aria-describedby automatically. |
|
|
50
|
+
| `PopoverClose.…ButtonProps` | `ButtonProps` | | Closes the popover. Secondary Button by default; `render` to change. |
|
|
51
|
+
|
|
52
|
+
## Examples
|
|
53
|
+
|
|
54
|
+
### Share link
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
<Popover>
|
|
58
|
+
<PopoverTrigger leading={<Icon name="user" />}>Share</PopoverTrigger>
|
|
59
|
+
<PopoverContent align="end">
|
|
60
|
+
<PopoverTitle>Share this run</PopoverTitle>
|
|
61
|
+
<PopoverDescription>Anyone with the link can view the trace.</PopoverDescription>
|
|
62
|
+
<Input readOnly defaultValue="sw3.dev/r/8f2c" aria-label="Link" />
|
|
63
|
+
<PopoverClose variant="primary">Copy link</PopoverClose>
|
|
64
|
+
</PopoverContent>
|
|
65
|
+
</Popover>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Controlled, custom trigger element
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
const [open, setOpen] = useState(false)
|
|
72
|
+
|
|
73
|
+
<Popover open={open} onOpenChange={setOpen}>
|
|
74
|
+
<PopoverTrigger render={<button className="chip" />}>Filters</PopoverTrigger>
|
|
75
|
+
<PopoverContent side="right" padding="sm">…</PopoverContent>
|
|
76
|
+
</Popover>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Rules
|
|
80
|
+
- Trigger and Close parts render an SW3 <Button> (trigger variant "outline", close variant "secondary") and accept every Button prop (variant, size, leading…). To use your own element pass `render={<a href="…"/>}`.
|
|
81
|
+
- Always give the content a PopoverTitle (or aria-label on PopoverContent).
|
|
82
|
+
- Mount PopoverContent unconditionally; it portals and animates itself.
|
|
83
|
+
- Keep it small: one task, ≤ ~6 controls.
|
|
84
|
+
|
|
85
|
+
## Accessibility
|
|
86
|
+
- Trigger: aria-haspopup="dialog", aria-expanded, aria-controls. Content: role="dialog", labelled by its title.
|
|
87
|
+
- Opening moves focus into the content; Escape, a Close part or a press outside closes it and returns focus to the trigger. Tab leaving a non-modal popover closes it.
|
|
88
|
+
|
|
89
|
+
## DOM contract (for agents operating the page)
|
|
90
|
+
|
|
91
|
+
- Selector: `[data-sw="popover-trigger"], [data-sw="popover-content"]`
|
|
92
|
+
- `aria-expanded`: on the trigger: true while open
|
|
93
|
+
- `data-state`: open | closed (trigger and content)
|
|
94
|
+
- `data-side`: on the content: side it landed on
|
|
95
|
+
- How to operate: Click the trigger to open; the panel is [data-sw="popover-content"][role="dialog"] at the end of <body>. Press Escape or click [data-sw="popover-close"] to close. Agent bridge (kind "popover"): state {open}; actions open(), close(), toggle().
|
|
96
|
+
|
|
97
|
+
Related: `tooltip`, `hover-card`, `dialog`, `drawer`
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
# Tooltip
|
|
102
|
+
|
|
103
|
+
> A short plain-text hint that names or describes a control on hover and keyboard focus.
|
|
104
|
+
|
|
105
|
+
Category: overlays · Status: beta · Slug: `tooltip`
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
import { Tooltip, TooltipTrigger, TooltipContent } from '@peerproblem/sw3-ui'
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## When to use
|
|
112
|
+
- Naming icon-only buttons.
|
|
113
|
+
- A few words of extra context or a keyboard shortcut for a control.
|
|
114
|
+
|
|
115
|
+
## Avoid
|
|
116
|
+
- Links, buttons or anything interactive inside → use Popover or HoverCard.
|
|
117
|
+
- Essential information (touch users never see tooltips) → put it in the page.
|
|
118
|
+
- Wrapping a disabled native button (it gets no hover/focus) → wrap a span, or keep the button enabled with aria-disabled.
|
|
119
|
+
|
|
120
|
+
## Props
|
|
121
|
+
|
|
122
|
+
| Prop | Type | Default | Description |
|
|
123
|
+
| --- | --- | --- | --- |
|
|
124
|
+
| `content` | `ReactNode` | | Shorthand: the tip text. The single child element becomes the trigger: <Tooltip content="Copy"><Button/></Tooltip>. |
|
|
125
|
+
| `open` | `boolean` | | Controlled open state of the tooltip. |
|
|
126
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
127
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
128
|
+
| `delay` | `number` | `600` | ms the pointer rests before opening. Once one tooltip is open, neighbours open instantly (grouping is automatic). |
|
|
129
|
+
| `closeDelay` | `number` | `100` | ms before closing after the pointer leaves trigger and tip. |
|
|
130
|
+
| `disabled` | `boolean` | `false` | Never open; the trigger keeps working. |
|
|
131
|
+
| `type` | `'label' \| 'description'` | | Whether the tip names the trigger (aria-labelledby) or describes it (aria-describedby). Default: label when the trigger has no name of its own. |
|
|
132
|
+
| `closeOnPress` | `boolean` | `true` | Close when the trigger is pressed. |
|
|
133
|
+
| `side / align / sideOffset` | `Side / Align / number` | `'top' / 'center' / 6` | Placement (on Tooltip for the shorthand, on TooltipContent when composing). |
|
|
134
|
+
| `TooltipTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default outline Button. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
|
|
135
|
+
| `TooltipContent.shortcut` | `ReactNode` | | Keyboard hint shown after the text, e.g. "⌘C". |
|
|
136
|
+
|
|
137
|
+
## Examples
|
|
138
|
+
|
|
139
|
+
### Icon button
|
|
140
|
+
|
|
141
|
+
```tsx
|
|
142
|
+
<Tooltip content="Copy code">
|
|
143
|
+
<Button variant="ghost" size="sm" iconOnly aria-label="Copy code" leading={<Icon name="copy" />} />
|
|
144
|
+
</Tooltip>
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Composed, with shortcut
|
|
148
|
+
|
|
149
|
+
```tsx
|
|
150
|
+
<Tooltip delay={300}>
|
|
151
|
+
<TooltipTrigger variant="secondary">Run</TooltipTrigger>
|
|
152
|
+
<TooltipContent side="bottom" shortcut="⌘↵">Run the agent</TooltipContent>
|
|
153
|
+
</Tooltip>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### On a popover trigger
|
|
157
|
+
|
|
158
|
+
```tsx
|
|
159
|
+
<Popover>
|
|
160
|
+
<Tooltip content="Share with your team">
|
|
161
|
+
<PopoverTrigger>Share</PopoverTrigger>
|
|
162
|
+
</Tooltip>
|
|
163
|
+
<PopoverContent>…</PopoverContent>
|
|
164
|
+
</Popover>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Rules
|
|
168
|
+
- A few words of plain text. No sentences, no links. (Surface: radius xs, 4×8px padding, 12px text.)
|
|
169
|
+
- The child must be one element that forwards its ref and accepts event props (SW3 Button, native button, a).
|
|
170
|
+
- Icon-only triggers still need aria-label; the tooltip adds the visible hint.
|
|
171
|
+
|
|
172
|
+
## Accessibility
|
|
173
|
+
- Content has role="tooltip"; a hidden copy is always in the page so the trigger is labelled/described before it opens.
|
|
174
|
+
- Keyboard focus opens it at once, Escape closes it without closing a dialog or popover under it, pressing the trigger closes it.
|
|
175
|
+
|
|
176
|
+
## DOM contract (for agents operating the page)
|
|
177
|
+
|
|
178
|
+
- Selector: `[data-sw="tooltip-trigger"], [data-sw="tooltip-content"][role="tooltip"]`
|
|
179
|
+
- `data-state`: open | closed (on the trigger when it is a plain tooltip trigger)
|
|
180
|
+
- `data-instant`: on the content when it opened without delay
|
|
181
|
+
- How to operate: Read the tip without opening it via the trigger's aria-describedby / aria-labelledby target. Hover or focus the trigger to show it. No agent bridge actions (it is a hint, not a control).
|
|
182
|
+
|
|
183
|
+
Related: `popover`, `hover-card`
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
# HoverCard
|
|
188
|
+
|
|
189
|
+
> A preview card for a link (person, repo, doc) on hover or keyboard focus; the link still navigates.
|
|
190
|
+
|
|
191
|
+
Category: overlays · Status: beta · Slug: `hover-card`
|
|
192
|
+
|
|
193
|
+
```tsx
|
|
194
|
+
import { HoverCard, HoverCardTrigger, HoverCardContent } from '@peerproblem/sw3-ui'
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## When to use
|
|
198
|
+
- Previewing where a link goes: a profile, a PR, a model card.
|
|
199
|
+
|
|
200
|
+
## Avoid
|
|
201
|
+
- Content only available in the card — touch users never see it; it must exist on the linked page.
|
|
202
|
+
- Opening on click → use Popover.
|
|
203
|
+
- Plain hints on buttons → use Tooltip.
|
|
204
|
+
|
|
205
|
+
## Props
|
|
206
|
+
|
|
207
|
+
| Prop | Type | Default | Description |
|
|
208
|
+
| --- | --- | --- | --- |
|
|
209
|
+
| `open` | `boolean` | | Controlled open state of the card. |
|
|
210
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
211
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
212
|
+
| `delay` | `number` | `600` | ms the pointer or keyboard focus rests on the link before opening. |
|
|
213
|
+
| `closeDelay` | `number` | `300` | ms before closing once the pointer leaves link and card. The pointer can cross the gap. |
|
|
214
|
+
| `disabled` | `boolean` | `false` | Never open; a plain link remains. |
|
|
215
|
+
| `HoverCardTrigger.href` * | `string` | | The trigger is an <a>; give it an href. |
|
|
216
|
+
| `HoverCardTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default <a>. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
|
|
217
|
+
| `HoverCardContent.side / align / sideOffset` | `Side / Align / number` | `'bottom' / 'center' / 8` | Placement. Width 19rem (--sw-hover-card-width). |
|
|
218
|
+
|
|
219
|
+
## Examples
|
|
220
|
+
|
|
221
|
+
### Author preview
|
|
222
|
+
|
|
223
|
+
```tsx
|
|
224
|
+
<Text>
|
|
225
|
+
Reviewed by{' '}
|
|
226
|
+
<HoverCard>
|
|
227
|
+
<HoverCardTrigger href="/people/mara">@mara</HoverCardTrigger>
|
|
228
|
+
<HoverCardContent>
|
|
229
|
+
<Text size="sm"><strong>Mara Lind</strong> — infra lead, owns the eval pipeline.</Text>
|
|
230
|
+
<Caption>Joined March 2024</Caption>
|
|
231
|
+
</HoverCardContent>
|
|
232
|
+
</HoverCard>
|
|
233
|
+
</Text>
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## Rules
|
|
237
|
+
- Keep it a preview: avatar, name, one line, a stat or two.
|
|
238
|
+
- Use inside running text or lists of links.
|
|
239
|
+
|
|
240
|
+
## Accessibility
|
|
241
|
+
- The trigger stays a plain link (Enter follows it). Escape closes the card and leaves focus on the link.
|
|
242
|
+
- Focus via keyboard opens after `delay`; a click-focus does not.
|
|
243
|
+
|
|
244
|
+
## DOM contract (for agents operating the page)
|
|
245
|
+
|
|
246
|
+
- Selector: `[data-sw="hover-card-trigger"], [data-sw="hover-card-content"]`
|
|
247
|
+
- `data-state`: open | closed
|
|
248
|
+
- How to operate: Hover or focus the link and wait `delay` ms; the card is [data-sw="hover-card-content"] at the end of <body>. Agent bridge (kind "hover-card"): state {open}; actions open(), close(), toggle().
|
|
249
|
+
|
|
250
|
+
Related: `tooltip`, `popover`
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
# Dialog
|
|
255
|
+
|
|
256
|
+
> A modal squircle panel over a dimmed page for a focused task, with focus trap, scroll lock, Escape and backdrop dismissal.
|
|
257
|
+
|
|
258
|
+
Category: overlays · Status: beta · Slug: `dialog`
|
|
259
|
+
|
|
260
|
+
```tsx
|
|
261
|
+
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter, DialogClose } from '@peerproblem/sw3-ui'
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
## When to use
|
|
265
|
+
- A task that needs full attention: edit a record, create an API key, review terms.
|
|
266
|
+
- Forms of a few fields that should not navigate away.
|
|
267
|
+
|
|
268
|
+
## Avoid
|
|
269
|
+
- Confirming a destructive action → use AlertDialog (or confirm()).
|
|
270
|
+
- A quick edit next to a control → use Popover.
|
|
271
|
+
- Phone-first sheets that should be swiped away → use Drawer.
|
|
272
|
+
- Status messages → use toast().
|
|
273
|
+
|
|
274
|
+
## Props
|
|
275
|
+
|
|
276
|
+
| Prop | Type | Default | Description |
|
|
277
|
+
| --- | --- | --- | --- |
|
|
278
|
+
| `open` | `boolean` | | Controlled open state of the dialog. |
|
|
279
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
280
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
281
|
+
| `modal` | `boolean` | `true` | Trap focus, lock scroll and show the backdrop. false = a panel beside the page. |
|
|
282
|
+
| `dismissible` | `boolean` | `true` | Whether Escape and backdrop presses close it. Close parts always can. Set false while a form is dirty. |
|
|
283
|
+
| `closeOnOutsidePress` | `boolean` | `true` | Whether pressing the backdrop closes it. |
|
|
284
|
+
| `DialogTrigger.…ButtonProps` | `ButtonProps` | | Outline Button by default. |
|
|
285
|
+
| `DialogTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default Button. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
|
|
286
|
+
| `DialogContent.size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Max width 400 / 520 / 720px. Under 640px it is full width, docked 8px above the bottom. |
|
|
287
|
+
| `DialogContent.closeButton` | `boolean` | `true` | Show the × in the corner. |
|
|
288
|
+
| `DialogContent.initialFocus` | `RefObject<HTMLElement>` | | Element focused on open. Default [data-autofocus], else the first focusable. |
|
|
289
|
+
| `DialogHeader / DialogBody / DialogFooter` | `div` | | Layout: header (title + description), scrollable body, right-aligned action row (stacked on phones). |
|
|
290
|
+
| `DialogTitle / DialogDescription` | `ReactNode` | | h2 / p; wired to aria-labelledby / aria-describedby. |
|
|
291
|
+
| `DialogClose.…ButtonProps` | `ButtonProps` | | Closes the dialog. Secondary Button by default. |
|
|
292
|
+
|
|
293
|
+
## Examples
|
|
294
|
+
|
|
295
|
+
### Create API key
|
|
296
|
+
|
|
297
|
+
```tsx
|
|
298
|
+
<Dialog>
|
|
299
|
+
<DialogTrigger variant="primary">New key</DialogTrigger>
|
|
300
|
+
<DialogContent size="sm">
|
|
301
|
+
<DialogHeader>
|
|
302
|
+
<DialogTitle>Create API key</DialogTitle>
|
|
303
|
+
<DialogDescription>Keys can call every agent in this workspace.</DialogDescription>
|
|
304
|
+
</DialogHeader>
|
|
305
|
+
<DialogBody>
|
|
306
|
+
<Input label="Name" placeholder="ci-runner" data-autofocus />
|
|
307
|
+
</DialogBody>
|
|
308
|
+
<DialogFooter>
|
|
309
|
+
<DialogClose>Cancel</DialogClose>
|
|
310
|
+
<Button variant="accent" onClick={create}>Create key</Button>
|
|
311
|
+
</DialogFooter>
|
|
312
|
+
</DialogContent>
|
|
313
|
+
</Dialog>
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Controlled, opened from code
|
|
317
|
+
|
|
318
|
+
```tsx
|
|
319
|
+
const [open, setOpen] = useState(false)
|
|
320
|
+
|
|
321
|
+
<Button onClick={() => setOpen(true)}>Review changes</Button>
|
|
322
|
+
<Dialog open={open} onOpenChange={setOpen}>
|
|
323
|
+
<DialogContent size="lg">
|
|
324
|
+
<DialogHeader><DialogTitle>Review changes</DialogTitle></DialogHeader>
|
|
325
|
+
<DialogBody>{/* long diff scrolls here */}</DialogBody>
|
|
326
|
+
<DialogFooter><DialogClose variant="primary">Done</DialogClose></DialogFooter>
|
|
327
|
+
</DialogContent>
|
|
328
|
+
</Dialog>
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
## Rules
|
|
332
|
+
- Trigger and Close parts render an SW3 <Button> (trigger variant "outline", close variant "secondary") and accept every Button prop (variant, size, leading…). To use your own element pass `render={<a href="…"/>}`.
|
|
333
|
+
- Overlay spacing scale: padding 24 (Dialog) / 20 (Drawer) / 16 (Popover, Hover Card); blocks 16px apart; title → description 6px.
|
|
334
|
+
- Always include a DialogTitle.
|
|
335
|
+
- Put long content in DialogBody so the title and actions stay visible.
|
|
336
|
+
- One accent button in the footer; the cancel/close action comes first.
|
|
337
|
+
|
|
338
|
+
## Accessibility
|
|
339
|
+
- role="dialog" + aria-modal, labelled by the title, described by the description. Focus moves in, Tab is trapped, focus returns to the trigger on close.
|
|
340
|
+
- Escape closes the top-most layer only (a Select inside closes first). Toasts stay usable while it is open.
|
|
341
|
+
|
|
342
|
+
## DOM contract (for agents operating the page)
|
|
343
|
+
|
|
344
|
+
- Selector: `[data-sw="dialog-trigger"], [data-sw="dialog-content"][role="dialog"]`
|
|
345
|
+
- `aria-expanded`: on the trigger
|
|
346
|
+
- `data-state`: open | closed
|
|
347
|
+
- `data-size`: sm | md | lg
|
|
348
|
+
- How to operate: Click the trigger; the panel is [data-sw="dialog-content"] at the end of <body>. Close with [data-sw="dialog-close"] or Escape. Agent bridge (kind "dialog"): state {open}; actions open(), close(), toggle().
|
|
349
|
+
|
|
350
|
+
Related: `alert-dialog`, `drawer`, `popover`
|
|
351
|
+
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
# AlertDialog
|
|
355
|
+
|
|
356
|
+
> A modal question that needs an explicit answer — Cancel or the action — plus an imperative `await confirm({...})`.
|
|
357
|
+
|
|
358
|
+
Category: overlays · Status: beta · Slug: `alert-dialog`
|
|
359
|
+
|
|
360
|
+
```tsx
|
|
361
|
+
import { AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogCancel, AlertDialogAction, confirm, ConfirmHost } from '@peerproblem/sw3-ui'
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
## When to use
|
|
365
|
+
- Confirming destructive or irreversible actions: delete a project, revoke a key, stop a running agent.
|
|
366
|
+
- From an event handler: `if (await confirm({ title: "Delete run?", variant: "danger" })) …` with <ConfirmHost/> (or <OverlayHost/>) mounted once.
|
|
367
|
+
|
|
368
|
+
## Avoid
|
|
369
|
+
- Forms or rich content → use Dialog.
|
|
370
|
+
- Confirming routine, undoable actions → just do it and offer Undo in a toast.
|
|
371
|
+
- Vague buttons like "OK" → name the action ("Delete project").
|
|
372
|
+
|
|
373
|
+
## Props
|
|
374
|
+
|
|
375
|
+
| Prop | Type | Default | Description |
|
|
376
|
+
| --- | --- | --- | --- |
|
|
377
|
+
| `open` | `boolean` | | Controlled open state of the alert dialog. |
|
|
378
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
379
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
380
|
+
| `dismissible` | `boolean` | `true` | Whether Escape closes it (as Cancel). Pressing outside never closes it. |
|
|
381
|
+
| `AlertDialogTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default Button. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
|
|
382
|
+
| `AlertDialogContent.size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Max width. |
|
|
383
|
+
| `AlertDialogCancel` | `ButtonProps` | `children "Cancel"` | The safe answer. Gets initial focus. Put it first. |
|
|
384
|
+
| `AlertDialogAction.variant` | `'primary' \| 'danger' \| …ButtonVariant` | `'primary'` | Use danger for destructive actions. |
|
|
385
|
+
| `AlertDialogAction.onClick` | `(e) => unknown \| Promise<unknown>` | | Runs, then the dialog closes. Return a Promise to show loading until it resolves; a rejection keeps it open. Call e.preventDefault() to keep it open. |
|
|
386
|
+
| `confirm(options)` | `({ title, description?, confirmLabel?, cancelLabel?, variant?: "primary" \| "danger" }) => Promise<boolean>` | | Ask from anywhere; resolves true for confirm, false for Cancel/Escape. Calls queue. Needs <ConfirmHost/> or <OverlayHost/>. |
|
|
387
|
+
|
|
388
|
+
## Examples
|
|
389
|
+
|
|
390
|
+
### Delete project
|
|
391
|
+
|
|
392
|
+
```tsx
|
|
393
|
+
<AlertDialog>
|
|
394
|
+
<AlertDialogTrigger variant="danger">Delete project</AlertDialogTrigger>
|
|
395
|
+
<AlertDialogContent>
|
|
396
|
+
<AlertDialogHeader>
|
|
397
|
+
<AlertDialogTitle>Delete “support-bot”?</AlertDialogTitle>
|
|
398
|
+
<AlertDialogDescription>Its runs, traces and API keys are removed for everyone. This can’t be undone.</AlertDialogDescription>
|
|
399
|
+
</AlertDialogHeader>
|
|
400
|
+
<AlertDialogFooter>
|
|
401
|
+
<AlertDialogCancel />
|
|
402
|
+
<AlertDialogAction variant="danger" onClick={() => api.deleteProject(id)}>Delete project</AlertDialogAction>
|
|
403
|
+
</AlertDialogFooter>
|
|
404
|
+
</AlertDialogContent>
|
|
405
|
+
</AlertDialog>
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### confirm() from a handler
|
|
409
|
+
|
|
410
|
+
```tsx
|
|
411
|
+
// once, near the root:
|
|
412
|
+
<OverlayHost />
|
|
413
|
+
|
|
414
|
+
async function revoke(key: string) {
|
|
415
|
+
const yes = await confirm({ title: 'Revoke this key?', description: 'Running jobs using it will fail.', confirmLabel: 'Revoke', variant: 'danger' })
|
|
416
|
+
if (yes) await api.revoke(key)
|
|
417
|
+
}
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
## Rules
|
|
421
|
+
- Title is the question; description says what happens.
|
|
422
|
+
- Cancel first, the action last; label the action with its verb.
|
|
423
|
+
- Only one AlertDialogAction.
|
|
424
|
+
|
|
425
|
+
## Accessibility
|
|
426
|
+
- role="alertdialog" + aria-modal, labelled and described. Focus starts on Cancel and is trapped; Escape cancels; outside presses are ignored.
|
|
427
|
+
|
|
428
|
+
## DOM contract (for agents operating the page)
|
|
429
|
+
|
|
430
|
+
- Selector: `[data-sw="alert-dialog-trigger"], [data-sw="alert-dialog-content"][role="alertdialog"]`
|
|
431
|
+
- `data-state`: open | closed
|
|
432
|
+
- `data-pending`: on the action while its Promise runs
|
|
433
|
+
- How to operate: Answer by clicking [data-sw="alert-dialog-cancel"] or [data-sw="alert-dialog-action"]. Agent bridge (kind "alert-dialog"): state {open}; actions open(), close() (close = cancel), toggle().
|
|
434
|
+
|
|
435
|
+
Related: `dialog`, `toast`
|
|
436
|
+
|
|
437
|
+
---
|
|
438
|
+
|
|
439
|
+
# Drawer
|
|
440
|
+
|
|
441
|
+
> A sheet that slides in from an edge (bottom by default); drag it toward its edge to dismiss, with optional snap points.
|
|
442
|
+
|
|
443
|
+
Category: overlays · Status: beta · Slug: `drawer`
|
|
444
|
+
|
|
445
|
+
```tsx
|
|
446
|
+
import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter, DrawerClose } from '@peerproblem/sw3-ui'
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
## When to use
|
|
450
|
+
- Phone-first tasks and action sheets.
|
|
451
|
+
- Side panels: filters, run details, settings (side="right").
|
|
452
|
+
- Map-style sheets that rest at several heights (snapPoints).
|
|
453
|
+
|
|
454
|
+
## Avoid
|
|
455
|
+
- Short confirmations → use AlertDialog.
|
|
456
|
+
- Tiny edits next to a control on desktop → use Popover.
|
|
457
|
+
- Putting the only way to close behind a swipe — keep a DrawerClose.
|
|
458
|
+
|
|
459
|
+
## Props
|
|
460
|
+
|
|
461
|
+
| Prop | Type | Default | Description |
|
|
462
|
+
| --- | --- | --- | --- |
|
|
463
|
+
| `open` | `boolean` | | Controlled open state of the drawer. |
|
|
464
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
465
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
466
|
+
| `side` | `'bottom' \| 'top' \| 'left' \| 'right'` | `'bottom'` | Edge it slides from. |
|
|
467
|
+
| `modal` | `boolean` | `true` | Trap focus, lock scroll and dim the page. |
|
|
468
|
+
| `dismissible` | `boolean` | `true` | Whether Escape, backdrop press and swipe can close it (it rubber-bands otherwise). |
|
|
469
|
+
| `closeOnOutsidePress` | `boolean` | `true` | Whether pressing the backdrop closes it. |
|
|
470
|
+
| `snapPoints` | `number[]` | | Resting sizes: fractions of the viewport (≤ 1) or px (> 1), e.g. [0.4, 0.9]. The sheet is sized to the largest. |
|
|
471
|
+
| `snapPoint / defaultSnapPoint / onSnapPointChange` | `number / number / (p: number) => void` | | Controlled / initial (default: smallest) snap point. |
|
|
472
|
+
| `DrawerTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default Button. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
|
|
473
|
+
| `DrawerContent.handle` | `boolean` | `true for top/bottom` | Grab handle. With 2+ snap points it is a button: press cycles sizes, arrow keys / Home / End pick one. |
|
|
474
|
+
| `DrawerHeader / DrawerBody / DrawerFooter` | `div` | | Layout: title block, scrollable middle (drag starts there only when scrolled to the top), equal-width action row. |
|
|
475
|
+
| `DrawerTitle / DrawerDescription / DrawerClose` | `parts` | | Same as Dialog’s. |
|
|
476
|
+
|
|
477
|
+
## Examples
|
|
478
|
+
|
|
479
|
+
### Bottom sheet
|
|
480
|
+
|
|
481
|
+
```tsx
|
|
482
|
+
<Drawer>
|
|
483
|
+
<DrawerTrigger>Run settings</DrawerTrigger>
|
|
484
|
+
<DrawerContent>
|
|
485
|
+
<DrawerHeader>
|
|
486
|
+
<DrawerTitle>Run settings</DrawerTitle>
|
|
487
|
+
<DrawerDescription>Applies to the next run only.</DrawerDescription>
|
|
488
|
+
</DrawerHeader>
|
|
489
|
+
<DrawerBody>
|
|
490
|
+
<Switch label="Stream tokens" checked={stream} onCheckedChange={setStream} />
|
|
491
|
+
</DrawerBody>
|
|
492
|
+
<DrawerFooter>
|
|
493
|
+
<DrawerClose>Cancel</DrawerClose>
|
|
494
|
+
<DrawerClose variant="primary" onClick={save}>Save</DrawerClose>
|
|
495
|
+
</DrawerFooter>
|
|
496
|
+
</DrawerContent>
|
|
497
|
+
</Drawer>
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
### Right panel
|
|
501
|
+
|
|
502
|
+
```tsx
|
|
503
|
+
<Drawer side="right">
|
|
504
|
+
<DrawerTrigger>Trace</DrawerTrigger>
|
|
505
|
+
<DrawerContent>…</DrawerContent>
|
|
506
|
+
</Drawer>
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
### Snap points
|
|
510
|
+
|
|
511
|
+
```tsx
|
|
512
|
+
<Drawer snapPoints={[0.35, 0.9]}>
|
|
513
|
+
<DrawerTrigger>Nearby agents</DrawerTrigger>
|
|
514
|
+
<DrawerContent>
|
|
515
|
+
<DrawerHeader><DrawerTitle>Nearby agents</DrawerTitle></DrawerHeader>
|
|
516
|
+
<DrawerBody>{/* list */}</DrawerBody>
|
|
517
|
+
</DrawerContent>
|
|
518
|
+
</Drawer>
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
## Rules
|
|
522
|
+
- Trigger and Close parts render an SW3 <Button> (trigger variant "outline", close variant "secondary") and accept every Button prop (variant, size, leading…). To use your own element pass `render={<a href="…"/>}`.
|
|
523
|
+
- Always include a DrawerTitle and a visible way to close (DrawerClose).
|
|
524
|
+
- Prefer bottom on phones, right for desktop side panels.
|
|
525
|
+
|
|
526
|
+
## Accessibility
|
|
527
|
+
- role="dialog" + aria-modal, labelled and described; focus trapped and returned. Escape and the backdrop close it; dragging is never the only way.
|
|
528
|
+
- The snap handle is a button (aria-label "Resize drawer") operable with arrows, Home, End.
|
|
529
|
+
|
|
530
|
+
## DOM contract (for agents operating the page)
|
|
531
|
+
|
|
532
|
+
- Selector: `[data-sw="drawer-trigger"], [data-sw="drawer-content"][role="dialog"]`
|
|
533
|
+
- `data-state`: open | closed
|
|
534
|
+
- `data-side`: bottom | top | left | right
|
|
535
|
+
- `data-snap`: current snap point
|
|
536
|
+
- `data-dragging`: present while dragged
|
|
537
|
+
- How to operate: Click the trigger; close with [data-sw="drawer-close"] or Escape; resize with [data-sw="drawer-handle"]. Agent bridge (kind "drawer"): state {open, side, snapPoint}; actions open(), close(), toggle().
|
|
538
|
+
|
|
539
|
+
Related: `dialog`, `popover`
|
|
540
|
+
|
|
541
|
+
---
|
|
542
|
+
|
|
543
|
+
# Menu
|
|
544
|
+
|
|
545
|
+
> A popup list of actions opened from a button, or at the pointer on right-click (ContextMenu), with groups, checkboxes, radios, submenus and shortcut hints.
|
|
546
|
+
|
|
547
|
+
Category: overlays · Status: beta · Slug: `menu`
|
|
548
|
+
|
|
549
|
+
```tsx
|
|
550
|
+
import { Menu, MenuTrigger, MenuContent, MenuItem, MenuGroup, MenuLabel, MenuSeparator, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuSub, MenuSubTrigger, MenuSubContent, ContextMenu, ContextMenuTrigger } from '@peerproblem/sw3-ui'
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
## When to use
|
|
554
|
+
- A short list of actions on an object ("…" overflow, row actions, account menu).
|
|
555
|
+
- View options and quick settings: MenuCheckboxItem for on/off toggles, MenuRadioGroup for one-of-many (sort, density). Use these instead of Switches in a Popover.
|
|
556
|
+
- Right-click actions on an area: `<ContextMenu><ContextMenuTrigger>…</ContextMenuTrigger><MenuContent>…</MenuContent></ContextMenu>`.
|
|
557
|
+
|
|
558
|
+
## Avoid
|
|
559
|
+
- Choosing a form value with a Menu — use Select (it shows the value and submits it).
|
|
560
|
+
- Searching through many commands — use Command.
|
|
561
|
+
- Navigation links for a site — use NavigationMenu / links, not menuitems.
|
|
562
|
+
- Putting inputs or long content inside a menu — use Popover.
|
|
563
|
+
|
|
564
|
+
## Props
|
|
565
|
+
|
|
566
|
+
| Prop | Type | Default | Description |
|
|
567
|
+
| --- | --- | --- | --- |
|
|
568
|
+
| `open / defaultOpen / onOpenChange` | `boolean / (open: boolean) => void` | | Menu: controlled or uncontrolled open state. |
|
|
569
|
+
| `onAction` | `(value: string) => void` | | Menu: runs for every plain MenuItem (also in submenus) with its `value`. |
|
|
570
|
+
| `loop` | `boolean` | `true` | Menu: arrow keys wrap. |
|
|
571
|
+
| `asChild` | `boolean` | | MenuTrigger / ContextMenuTrigger: clone your single child element (e.g. `<Button>`) with the trigger props instead of rendering the default button / div. |
|
|
572
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | MenuTrigger: size of the default framed trigger button. |
|
|
573
|
+
| `placement / offset` | `Placement / number` | `'bottom-start' / 6` | MenuContent / MenuSubContent: side and gap (submenus default 'right-start' / 2). |
|
|
574
|
+
| `value` | `string` | | MenuItem: passed to `onAction`. MenuRadioItem: required, the radio value. |
|
|
575
|
+
| `onSelect` | `(event) => void` | | MenuItem: runs when chosen; `event.preventDefault()` keeps the menu open and skips onAction. |
|
|
576
|
+
| `icon / shortcut` | `ReactNode / string` | | Items: leading icon; shortcut hint like "mod+d" (⌘D / Ctrl+D) — display + aria-keyshortcuts only. |
|
|
577
|
+
| `destructive` | `boolean` | | MenuItem: red, for Delete. |
|
|
578
|
+
| `disabled` | `boolean` | | Items and triggers: cannot be chosen; keyboard skips it. |
|
|
579
|
+
| `label` | `string` | | Items: text typeahead matches when children are not plain text. MenuGroup: shorthand heading. |
|
|
580
|
+
| `closeOnSelect` | `boolean` | `true for MenuItem, false for checkbox / radio items` | Close after choosing. |
|
|
581
|
+
| `checked / defaultChecked / onCheckedChange` | `boolean / (checked) => void` | | MenuCheckboxItem state. |
|
|
582
|
+
| `value / defaultValue / onValueChange` | `string / (value) => void` | | MenuRadioGroup state. |
|
|
583
|
+
|
|
584
|
+
## Examples
|
|
585
|
+
|
|
586
|
+
### Actions
|
|
587
|
+
|
|
588
|
+
```tsx
|
|
589
|
+
<Menu onAction={(v) => console.log(v)}>
|
|
590
|
+
<MenuTrigger>Actions</MenuTrigger>
|
|
591
|
+
<MenuContent>
|
|
592
|
+
<MenuItem value="rename" shortcut="mod+r">Rename</MenuItem>
|
|
593
|
+
<MenuItem value="duplicate" shortcut="mod+d">Duplicate</MenuItem>
|
|
594
|
+
<MenuSeparator />
|
|
595
|
+
<MenuItem value="delete" destructive>Delete</MenuItem>
|
|
596
|
+
</MenuContent>
|
|
597
|
+
</Menu>
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
### Options, radios and a submenu with your own button
|
|
601
|
+
|
|
602
|
+
```tsx
|
|
603
|
+
<Menu>
|
|
604
|
+
<MenuTrigger asChild><Button variant="outline" size="sm">View</Button></MenuTrigger>
|
|
605
|
+
<MenuContent>
|
|
606
|
+
<MenuCheckboxItem checked={showLogs} onCheckedChange={setShowLogs}>Show logs</MenuCheckboxItem>
|
|
607
|
+
<MenuGroup label="Sort by">
|
|
608
|
+
<MenuRadioGroup value={sort} onValueChange={setSort}>
|
|
609
|
+
<MenuRadioItem value="recent">Most recent</MenuRadioItem>
|
|
610
|
+
<MenuRadioItem value="name">Name</MenuRadioItem>
|
|
611
|
+
</MenuRadioGroup>
|
|
612
|
+
</MenuGroup>
|
|
613
|
+
<MenuSub>
|
|
614
|
+
<MenuSubTrigger>Export</MenuSubTrigger>
|
|
615
|
+
<MenuSubContent>
|
|
616
|
+
<MenuItem value="csv">CSV</MenuItem>
|
|
617
|
+
<MenuItem value="json">JSON</MenuItem>
|
|
618
|
+
</MenuSubContent>
|
|
619
|
+
</MenuSub>
|
|
620
|
+
</MenuContent>
|
|
621
|
+
</Menu>
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
### Context menu
|
|
625
|
+
|
|
626
|
+
```tsx
|
|
627
|
+
<ContextMenu onAction={runAction}>
|
|
628
|
+
<ContextMenuTrigger>
|
|
629
|
+
<Card>Right-click this run</Card>
|
|
630
|
+
</ContextMenuTrigger>
|
|
631
|
+
<MenuContent>
|
|
632
|
+
<MenuItem value="rerun">Re-run</MenuItem>
|
|
633
|
+
<MenuItem value="copy-id">Copy run ID</MenuItem>
|
|
634
|
+
</MenuContent>
|
|
635
|
+
</ContextMenu>
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
## Rules
|
|
639
|
+
- Item labels are verbs in sentence case ("Duplicate", "Copy link").
|
|
640
|
+
- Group related items with MenuGroup/MenuSeparator; keep a menu under ~10 items, move the rest into a submenu.
|
|
641
|
+
- Destructive items go last, after a separator (`destructive` sets data-tone="danger": red label and icon).
|
|
642
|
+
- Checkbox and radio items show a trailing accent check; plain items never do.
|
|
643
|
+
- Trigger parts render a framed squircle button by default; pass `asChild` to use your own Button.
|
|
644
|
+
|
|
645
|
+
## Accessibility
|
|
646
|
+
- Trigger: aria-haspopup="menu", aria-expanded, aria-controls. ArrowDown/Enter/Space open and focus the first item; ArrowUp the last.
|
|
647
|
+
- Content role="menu"; items role="menuitem" / "menuitemcheckbox" / "menuitemradio" with roving focus.
|
|
648
|
+
- Arrows move (wrap), Home/End jump, typing jumps by label, Enter/Space choose, Escape closes one level and returns focus, Tab closes.
|
|
649
|
+
- ArrowRight opens a submenu, ArrowLeft closes it. Context menu also opens with Shift+F10 / the Menu key and a long press on touch.
|
|
650
|
+
|
|
651
|
+
## DOM contract (for agents operating the page)
|
|
652
|
+
|
|
653
|
+
- Selector: `[data-sw="menu-trigger"], [data-sw="menu-context-trigger"]`
|
|
654
|
+
- `aria-expanded`: on the trigger: whether open
|
|
655
|
+
- `data-state`: trigger: 'open' | 'closed'
|
|
656
|
+
- `[data-sw="menu-content"] [data-sw-menu-item]`: the items while open; `data-value`, `data-label`, `aria-checked` (checkbox/radio), `data-disabled`
|
|
657
|
+
- How to operate: Click the trigger, then click an item in [data-sw="menu-content"] (portaled to <body>). Agent bridge: open(), close(), toggle(), select(valueOrLabel) — opens the menu and runs the item; items = the open menu’s items.
|
|
658
|
+
|
|
659
|
+
Related: `menubar`, `command`, `select`, `popover`
|
|
660
|
+
|
|
661
|
+
---
|
|
662
|
+
|
|
663
|
+
# Menubar
|
|
664
|
+
|
|
665
|
+
> A horizontal bar of menus (File, Edit, View) with one tab stop, arrow keys between menus and hover-switching while one is open.
|
|
666
|
+
|
|
667
|
+
Category: navigation · Status: beta · Slug: `menubar`
|
|
668
|
+
|
|
669
|
+
```tsx
|
|
670
|
+
import { Menubar, Menu, MenuTrigger, MenuContent, MenuItem } from '@peerproblem/sw3-ui'
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
## When to use
|
|
674
|
+
- Desktop-style apps and editors with several command menus.
|
|
675
|
+
- A toolbar of 2–6 menus that share the same keyboard model.
|
|
676
|
+
|
|
677
|
+
## Avoid
|
|
678
|
+
- Site navigation — use NavigationMenu or links.
|
|
679
|
+
- A single menu — use Menu on its own.
|
|
680
|
+
- Phones-first UIs with many menus — collapse into one Menu.
|
|
681
|
+
|
|
682
|
+
## Props
|
|
683
|
+
|
|
684
|
+
| Prop | Type | Default | Description |
|
|
685
|
+
| --- | --- | --- | --- |
|
|
686
|
+
| `children` * | `ReactNode` | | `<Menu>` elements, each with a `<MenuTrigger>` (rendered as a bar item) and `<MenuContent>`. |
|
|
687
|
+
| `loop` | `boolean` | `true` | Arrow keys wrap from the last menu to the first. |
|
|
688
|
+
| `disabled` | `boolean` | `false` | Disable every menu. |
|
|
689
|
+
| `bordered` | `boolean` | `true` | Draw the squircle frame around the bar. |
|
|
690
|
+
|
|
691
|
+
## Examples
|
|
692
|
+
|
|
693
|
+
### Editor menubar
|
|
694
|
+
|
|
695
|
+
```tsx
|
|
696
|
+
<Menubar aria-label="Editor">
|
|
697
|
+
<Menu onAction={run}>
|
|
698
|
+
<MenuTrigger>File</MenuTrigger>
|
|
699
|
+
<MenuContent>
|
|
700
|
+
<MenuItem value="new" shortcut="mod+n">New prompt</MenuItem>
|
|
701
|
+
<MenuItem value="open" shortcut="mod+o">Open…</MenuItem>
|
|
702
|
+
</MenuContent>
|
|
703
|
+
</Menu>
|
|
704
|
+
<Menu onAction={run}>
|
|
705
|
+
<MenuTrigger>Edit</MenuTrigger>
|
|
706
|
+
<MenuContent>
|
|
707
|
+
<MenuItem value="undo" shortcut="mod+z">Undo</MenuItem>
|
|
708
|
+
</MenuContent>
|
|
709
|
+
</Menu>
|
|
710
|
+
</Menubar>
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
## Rules
|
|
714
|
+
- Short one-word menu names in title order (File, Edit, View, Run, Help).
|
|
715
|
+
- Every Menu inside a Menubar needs a MenuTrigger and MenuContent; all Menu features (submenus, checkboxes) work.
|
|
716
|
+
|
|
717
|
+
## Accessibility
|
|
718
|
+
- role="menubar" with triggers role="menuitem"; one tab stop (roving tabindex).
|
|
719
|
+
- ArrowLeft/Right move between menus (and switch the open menu), Home/End jump, ArrowDown/Enter/Space open.
|
|
720
|
+
- Inside an open menu ArrowLeft/Right move to the neighbouring menu.
|
|
721
|
+
|
|
722
|
+
## DOM contract (for agents operating the page)
|
|
723
|
+
|
|
724
|
+
- Selector: `[data-sw="menubar"]`
|
|
725
|
+
- `data-state`: 'open' while any menu is open
|
|
726
|
+
- `[data-sw="menubar-trigger"]`: one per menu; aria-expanded, data-state
|
|
727
|
+
- How to operate: Click a [data-sw="menubar-trigger"] then an item in the open [data-sw="menu-content"]. Agent bridge: open(menuLabel), close(); items = menu names. Each menu trigger also has its own Menu binding (select(item)).
|
|
728
|
+
|
|
729
|
+
Related: `menu`, `toolbar`
|
|
730
|
+
|
|
731
|
+
---
|
|
732
|
+
|
|
733
|
+
# Command
|
|
734
|
+
|
|
735
|
+
> A command palette: a search field over grouped commands with shortcuts and nested pages; `CommandDialog` opens it with ⌘K.
|
|
736
|
+
|
|
737
|
+
Category: navigation · Status: beta · Slug: `command`
|
|
738
|
+
|
|
739
|
+
```tsx
|
|
740
|
+
import { Command, CommandInput, CommandList, CommandGroup, CommandItem, CommandSeparator, CommandEmpty, CommandPage, CommandShortcut, CommandDialog } from '@peerproblem/sw3-ui'
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
## When to use
|
|
744
|
+
- A ⌘K palette for jumping and running actions across an app.
|
|
745
|
+
- An inline searchable action list (e.g. "Add block").
|
|
746
|
+
- Drill-down choices with pages (Switch project → list of projects).
|
|
747
|
+
|
|
748
|
+
## Avoid
|
|
749
|
+
- Choosing a form value — use Combobox.
|
|
750
|
+
- A handful of actions on one object — use Menu.
|
|
751
|
+
|
|
752
|
+
## Props
|
|
753
|
+
|
|
754
|
+
| Prop | Type | Default | Description |
|
|
755
|
+
| --- | --- | --- | --- |
|
|
756
|
+
| `items` | `Array<{ value, label, keywords?, icon?, shortcut?, disabled?, description?, items? (page), onSelect? } \| { type: 'group', label, items } \| { type: 'separator' }>` | | Commands as data; renders input + list for you. An item with `items` opens a page. |
|
|
757
|
+
| `onAction` | `(value: string) => void` | | Runs when a command runs (Enter, click or its shortcut). |
|
|
758
|
+
| `query / defaultQuery / onQueryChange` | `string` | | Search text. |
|
|
759
|
+
| `value / defaultValue / onValueChange` | `string \| null` | | The highlighted command (the first match is highlighted by default). |
|
|
760
|
+
| `pages / defaultPages / onPagesChange` | `string[]` | | Stack of open pages. |
|
|
761
|
+
| `filter` | `'contains' \| 'fuzzy' \| 'startsWith' \| false \| fn` | `'contains'` | How the search narrows commands (label + keywords). |
|
|
762
|
+
| `loading` | `boolean` | | Spinner in the search field and "Loading…" while empty. |
|
|
763
|
+
| `loop / bordered / placeholder` | `boolean / boolean / string` | | Arrow wrap (true); framed surface (true, false in a dialog); placeholder for `items` mode. Inline density is compact (34px rows, 6px list inset); CommandDialog is roomy (40px rows, 8px inset). Row corners are concentric with the frame. |
|
|
764
|
+
| `CommandItem: value?, label?, keywords?, icon?, shortcut?, page?, disabled?, onSelect?` | `props` | | `shortcut` ("mod+p") runs it while the palette is mounted, even when filtered out. `page` opens that CommandPage. `onSelect(e)` + `e.preventDefault()` skips onAction/closing. |
|
|
765
|
+
| `CommandPage: value?` | `string` | | Commands shown only while this page is open; leave `value` out for the first page. |
|
|
766
|
+
| `CommandGroup: heading` | `ReactNode` | | Group label; hides itself when no command in it matches. |
|
|
767
|
+
| `CommandEmpty: children` | `ReactNode` | `"No results"` | Shown when nothing matches. |
|
|
768
|
+
| `CommandDialog: open / defaultOpen / onOpenChange, shortcut, closeOnSelect, aria-label + all Command props` | `boolean, string \| false = 'mod+k', boolean = true` | | Modal palette toggled by the shortcut; closes after a command runs. |
|
|
769
|
+
|
|
770
|
+
## Examples
|
|
771
|
+
|
|
772
|
+
### Inline palette
|
|
773
|
+
|
|
774
|
+
```tsx
|
|
775
|
+
<Command onAction={run}>
|
|
776
|
+
<CommandInput placeholder="Type a command…" />
|
|
777
|
+
<CommandList>
|
|
778
|
+
<CommandGroup heading="Agents">
|
|
779
|
+
<CommandItem value="new-agent" icon={<Icon name="plus" />} shortcut="mod+n">New agent</CommandItem>
|
|
780
|
+
<CommandItem value="runs" page="runs">Open run…</CommandItem>
|
|
781
|
+
</CommandGroup>
|
|
782
|
+
<CommandPage value="runs">
|
|
783
|
+
<CommandItem value="run-812">Run #812</CommandItem>
|
|
784
|
+
</CommandPage>
|
|
785
|
+
<CommandEmpty>No commands found.</CommandEmpty>
|
|
786
|
+
</CommandList>
|
|
787
|
+
</Command>
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
### ⌘K dialog from data
|
|
791
|
+
|
|
792
|
+
```tsx
|
|
793
|
+
<CommandDialog onAction={run} items={[
|
|
794
|
+
{ type: 'group', label: 'Navigate', items: [
|
|
795
|
+
{ value: 'dashboard', label: 'Dashboard', shortcut: 'mod+1' },
|
|
796
|
+
{ value: 'settings', label: 'Settings', keywords: ['preferences'] },
|
|
797
|
+
] },
|
|
798
|
+
{ value: 'theme', label: 'Change theme…', items: [
|
|
799
|
+
{ value: 'light', label: 'Light' },
|
|
800
|
+
{ value: 'dark', label: 'Dark' },
|
|
801
|
+
] },
|
|
802
|
+
]} />
|
|
803
|
+
```
|
|
804
|
+
|
|
805
|
+
## Rules
|
|
806
|
+
- Search matches are shown weight-free: matched text in the foreground, the rest muted. On a page the search icon becomes a ghost back button.
|
|
807
|
+
- Commands are verbs or destinations in sentence case; add `keywords` for synonyms.
|
|
808
|
+
- One CommandDialog per app; its default shortcut is ⌘K / Ctrl+K.
|
|
809
|
+
- Group by intent (Navigate, Create, Settings); put the most used first.
|
|
810
|
+
|
|
811
|
+
## Accessibility
|
|
812
|
+
- Input role="combobox" (aria-expanded=true, aria-controls the list, aria-activedescendant); list role="listbox"; commands role="option".
|
|
813
|
+
- Typing filters and highlights the first match; arrows move; Enter runs; Escape clears the search, then goes back a page, then closes the dialog; Backspace on an empty search goes back.
|
|
814
|
+
- CommandDialog is role="dialog" aria-modal with a focus trap and scroll lock; focus returns to where it was.
|
|
815
|
+
|
|
816
|
+
## DOM contract (for agents operating the page)
|
|
817
|
+
|
|
818
|
+
- Selector: `[data-sw="command"]`
|
|
819
|
+
- `data-page`: current page value (absent on the first page)
|
|
820
|
+
- `[data-sw="command-item"]`: visible commands; data-value, data-label, data-active (highlighted), data-disabled
|
|
821
|
+
- `[data-sw="command-dialog"]`: hidden marker with data-state 'open' | 'closed'
|
|
822
|
+
- How to operate: Type into [data-sw="command-input"] and press Enter, or click a [data-sw="command-item"]. Agent bridge (command): search(text), clear(), back(), select(valueOrLabel); items = visible commands. (command-dialog): open(), close(), toggle().
|
|
823
|
+
|
|
824
|
+
Related: `menu`, `combobox`, `dialog`
|
|
825
|
+
|
|
826
|
+
---
|
|
827
|
+
|
|
828
|
+
# Tabs
|
|
829
|
+
|
|
830
|
+
> A list of tabs with a sliding indicator, each showing one panel. Automatic or manual activation, horizontal or vertical.
|
|
831
|
+
|
|
832
|
+
Category: navigation · Status: beta · Slug: `tabs`
|
|
833
|
+
|
|
834
|
+
```tsx
|
|
835
|
+
import { Tabs, TabsList, Tab, TabsPanel } from '@peerproblem/sw3-ui'
|
|
836
|
+
```
|
|
837
|
+
|
|
838
|
+
## When to use
|
|
839
|
+
- Switching between peer views of the same object (Overview / Logs / Settings).
|
|
840
|
+
- Keeping a long settings page in sections without leaving the page.
|
|
841
|
+
|
|
842
|
+
## Avoid
|
|
843
|
+
- Picking a value for a form or filter — use SegmentedControl (a radio group).
|
|
844
|
+
- Sequential steps — use a stepper or wizard.
|
|
845
|
+
- Site-wide navigation between pages — use NavigationMenu or links.
|
|
846
|
+
- Many tabs that overflow on phones without thought — keep labels short; the list scrolls horizontally.
|
|
847
|
+
|
|
848
|
+
## Props
|
|
849
|
+
|
|
850
|
+
| Prop | Type | Default | Description |
|
|
851
|
+
| --- | --- | --- | --- |
|
|
852
|
+
| `variant: 'metric'` | `variant` | | Equal-width cells, each holding a `<Stat size="sm">`, with a full-width indicator. The panel plots the selected metric. This is the KPI row of a dashboard (the Plausible / Vercel Analytics pattern). |
|
|
853
|
+
| `items` | `{ value: string; label: ReactNode; content: ReactNode; icon?: ReactNode; disabled?: boolean }[]` | | Shorthand: render the list and panels from data. Pass aria-label for the list. |
|
|
854
|
+
| `value` | `string \| null` | | Selected tab. Controlled. |
|
|
855
|
+
| `defaultValue` | `string \| null` | `first enabled tab` | Tab selected at first. |
|
|
856
|
+
| `onValueChange` | `(value: string) => void` | | Called when a tab is selected. |
|
|
857
|
+
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout and which arrow keys move. |
|
|
858
|
+
| `activation` | `'automatic' \| 'manual'` | `'automatic'` | automatic selects on arrow focus; manual waits for Enter/Space (use when panels are slow to render). |
|
|
859
|
+
| `loop` | `boolean` | `true` | Arrow keys wrap. |
|
|
860
|
+
| `variant` | `'line' \| 'pill'` | `'line'` | line = underline indicator on a hairline; pill = muted track with a sliding squircle pill. |
|
|
861
|
+
| `size` | `'sm' \| 'md'` | `'md'` | Tab height 32 / 40px. |
|
|
862
|
+
| `keepMounted` | `boolean` | `false` | Keep hidden panels mounted. |
|
|
863
|
+
| `aria-label` | `string` | | With items: names the tab list. |
|
|
864
|
+
| `TabsList.aria-label` | `string` | | Names the list when there is no visible heading. |
|
|
865
|
+
| `Tab.value` * | `string` | | Pairs the tab with the TabsPanel of the same value. |
|
|
866
|
+
| `Tab.disabled` | `boolean` | | Focusable but not selectable (aria-disabled). |
|
|
867
|
+
| `Tab.icon` | `ReactNode` | | Icon before the label. |
|
|
868
|
+
| `TabsPanel.value` * | `string` | | The tab this panel belongs to. |
|
|
869
|
+
| `TabsPanel.keepMounted` | `boolean` | | Override keepMounted for one panel. |
|
|
870
|
+
|
|
871
|
+
## Examples
|
|
872
|
+
|
|
873
|
+
### From data
|
|
874
|
+
|
|
875
|
+
```tsx
|
|
876
|
+
<Tabs
|
|
877
|
+
aria-label="Deployment"
|
|
878
|
+
items={[
|
|
879
|
+
{ value: 'overview', label: 'Overview', content: <Text>Ready · 2m ago</Text> },
|
|
880
|
+
{ value: 'logs', label: 'Logs', content: <Text>Build finished in 41s.</Text> },
|
|
881
|
+
{ value: 'settings', label: 'Settings', content: <Text>Region: fra1</Text> },
|
|
882
|
+
]}
|
|
883
|
+
/>
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
### Parts, controlled, pill variant
|
|
887
|
+
|
|
888
|
+
```tsx
|
|
889
|
+
const [tab, setTab] = useState('runs')
|
|
890
|
+
|
|
891
|
+
<Tabs value={tab} onValueChange={setTab} variant="pill">
|
|
892
|
+
<TabsList aria-label="Agent">
|
|
893
|
+
<Tab value="runs">Runs</Tab>
|
|
894
|
+
<Tab value="tools">Tools</Tab>
|
|
895
|
+
<Tab value="memory" disabled>Memory</Tab>
|
|
896
|
+
</TabsList>
|
|
897
|
+
<TabsPanel value="runs">…</TabsPanel>
|
|
898
|
+
<TabsPanel value="tools">…</TabsPanel>
|
|
899
|
+
<TabsPanel value="memory">…</TabsPanel>
|
|
900
|
+
</Tabs>
|
|
901
|
+
```
|
|
902
|
+
|
|
903
|
+
### Vertical, manual activation
|
|
904
|
+
|
|
905
|
+
```tsx
|
|
906
|
+
<Tabs orientation="vertical" activation="manual" defaultValue="general">
|
|
907
|
+
<TabsList aria-label="Settings">
|
|
908
|
+
<Tab value="general">General</Tab>
|
|
909
|
+
<Tab value="members">Members</Tab>
|
|
910
|
+
</TabsList>
|
|
911
|
+
<TabsPanel value="general">…</TabsPanel>
|
|
912
|
+
<TabsPanel value="members">…</TabsPanel>
|
|
913
|
+
</Tabs>
|
|
914
|
+
```
|
|
915
|
+
|
|
916
|
+
## Rules
|
|
917
|
+
- Labels are one or two words.
|
|
918
|
+
- Every Tab has a TabsPanel with the same value.
|
|
919
|
+
- Use 2–7 tabs; beyond that, use a select or a side navigation.
|
|
920
|
+
|
|
921
|
+
## Accessibility
|
|
922
|
+
- role="tablist" / "tab" / "tabpanel" with aria-selected, aria-controls and aria-labelledby.
|
|
923
|
+
- One tab stop (roving tabindex). Arrow keys move along the orientation, Home/End jump; Enter/Space select in manual mode.
|
|
924
|
+
- Disabled tabs stay focusable with aria-disabled, as the pattern asks.
|
|
925
|
+
|
|
926
|
+
## DOM contract (for agents operating the page)
|
|
927
|
+
|
|
928
|
+
- Selector: `[data-sw="tabs"]`
|
|
929
|
+
- `aria-selected`: true on the selected [data-sw="tabs-tab"]
|
|
930
|
+
- `data-state`: active | inactive on tabs and panels
|
|
931
|
+
- `data-value`: each tab's and panel's value
|
|
932
|
+
- `data-orientation`: horizontal | vertical
|
|
933
|
+
- How to operate: Click the [data-sw="tabs-tab"] whose text matches. Agent bridge: setValue(value), select(value); items = tabs; state = { value, orientation }.
|
|
934
|
+
|
|
935
|
+
Related: `segmented-control`, `navigation-menu`, `accordion`
|
|
936
|
+
|
|
937
|
+
---
|
|
938
|
+
|
|
939
|
+
# NavigationMenu
|
|
940
|
+
|
|
941
|
+
> Site navigation: a row of triggers that open panels of links on hover or press, plus plain top-level links.
|
|
942
|
+
|
|
943
|
+
Category: navigation · Status: beta · Slug: `navigation-menu`
|
|
944
|
+
|
|
945
|
+
```tsx
|
|
946
|
+
import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink } from '@peerproblem/sw3-ui'
|
|
947
|
+
```
|
|
948
|
+
|
|
949
|
+
## When to use
|
|
950
|
+
- The header of a marketing site or docs with grouped destinations (Products, Resources).
|
|
951
|
+
- A few top-level sections, each with 2–8 links.
|
|
952
|
+
|
|
953
|
+
## Avoid
|
|
954
|
+
- Actions (Save, Delete) — use Menu; this is for links.
|
|
955
|
+
- Switching views inside a page — use Tabs.
|
|
956
|
+
- Deep, multi-level trees — use Tree or a side navigation.
|
|
957
|
+
|
|
958
|
+
## Props
|
|
959
|
+
|
|
960
|
+
| Prop | Type | Default | Description |
|
|
961
|
+
| --- | --- | --- | --- |
|
|
962
|
+
| `aria-label` * | `string` | | Names the <nav> landmark, e.g. "Main". |
|
|
963
|
+
| `items` | `{ label; value?; href?; current?; columns?: 1 \| 2; links?: { label; href; description?; icon?; current? }[] }[]` | | Shorthand: items with `links` get a trigger + panel; items with `href` are plain links. |
|
|
964
|
+
| `value` | `string \| null` | | The open item; null = closed. Controlled. |
|
|
965
|
+
| `defaultValue` | `string \| null` | `null` | Open item at first. |
|
|
966
|
+
| `onValueChange` | `(value: string \| null) => void` | | Called when a panel opens, switches or closes. |
|
|
967
|
+
| `openOnHover` | `boolean` | `true` | Open when the mouse rests on a trigger. Pressing always works; false = click-only. |
|
|
968
|
+
| `delay` | `number` | `120` | Hover delay before opening (ms). Moving between triggers while open switches at once. |
|
|
969
|
+
| `closeDelay` | `number` | `200` | Delay before closing after the pointer leaves (ms). |
|
|
970
|
+
| `closeOnSelect` | `boolean` | `true` | Close when a link is pressed. |
|
|
971
|
+
| `NavigationMenuItem.value` | `string` | | Identifies the item. Generated when omitted. |
|
|
972
|
+
| `NavigationMenuTrigger` | `ButtonHTMLAttributes` | | The button that opens the item's panel. |
|
|
973
|
+
| `NavigationMenuContent.columns` | `1 \| 2` | `1` | Link grid columns (2 collapses to 1 on phones). |
|
|
974
|
+
| `NavigationMenuContent.keepMounted` | `boolean` | | Keep the links in the DOM (hidden) while closed, for crawlers. |
|
|
975
|
+
| `NavigationMenuLink.href` * | `string` | | Destination. |
|
|
976
|
+
| `NavigationMenuLink.current` | `boolean` | | Marks the current page (aria-current="page"). |
|
|
977
|
+
| `NavigationMenuLink.description` | `ReactNode` | | One short line under the label (in panels). |
|
|
978
|
+
| `NavigationMenuLink.icon` | `ReactNode` | | Bare 16px icon before the label (in panels), muted until hover. |
|
|
979
|
+
| `NavigationMenuLink.closeOnSelect` | `boolean` | | Override closeOnSelect for one link. |
|
|
980
|
+
|
|
981
|
+
## Examples
|
|
982
|
+
|
|
983
|
+
### From data
|
|
984
|
+
|
|
985
|
+
```tsx
|
|
986
|
+
<NavigationMenu
|
|
987
|
+
aria-label="Main"
|
|
988
|
+
items={[
|
|
989
|
+
{ label: 'Product', links: [
|
|
990
|
+
{ label: 'Agents', href: '/agents', description: 'Run tools on a schedule.', icon: <Icon name="command" /> },
|
|
991
|
+
{ label: 'Evals', href: '/evals', description: 'Score every change.', icon: <Icon name="check" /> },
|
|
992
|
+
] },
|
|
993
|
+
{ label: 'Docs', links: [{ label: 'Quickstart', href: '/docs' }, { label: 'API', href: '/docs/api' }] },
|
|
994
|
+
{ label: 'Pricing', href: '/pricing' },
|
|
995
|
+
]}
|
|
996
|
+
/>
|
|
997
|
+
```
|
|
998
|
+
|
|
999
|
+
### Parts
|
|
1000
|
+
|
|
1001
|
+
```tsx
|
|
1002
|
+
<NavigationMenu aria-label="Main">
|
|
1003
|
+
<NavigationMenuList>
|
|
1004
|
+
<NavigationMenuItem value="product">
|
|
1005
|
+
<NavigationMenuTrigger>Product</NavigationMenuTrigger>
|
|
1006
|
+
<NavigationMenuContent columns={2}>
|
|
1007
|
+
<NavigationMenuLink href="/agents" description="Run tools on a schedule.">Agents</NavigationMenuLink>
|
|
1008
|
+
<NavigationMenuLink href="/evals" description="Score every change.">Evals</NavigationMenuLink>
|
|
1009
|
+
</NavigationMenuContent>
|
|
1010
|
+
</NavigationMenuItem>
|
|
1011
|
+
<NavigationMenuItem>
|
|
1012
|
+
<NavigationMenuLink href="/pricing" current>Pricing</NavigationMenuLink>
|
|
1013
|
+
</NavigationMenuItem>
|
|
1014
|
+
</NavigationMenuList>
|
|
1015
|
+
</NavigationMenu>
|
|
1016
|
+
```
|
|
1017
|
+
|
|
1018
|
+
## Rules
|
|
1019
|
+
- Trigger labels are nouns (Product, Resources); link descriptions are one short line.
|
|
1020
|
+
- Keep 3–6 top-level items.
|
|
1021
|
+
- One hover shape everywhere: xs squircle on the bar, panel-concentric squircle in panels. The current page is a neutral fill + 500, never accent text.
|
|
1022
|
+
|
|
1023
|
+
## Accessibility
|
|
1024
|
+
- APG disclosure navigation: <nav aria-label> with buttons (aria-expanded, aria-controls) revealing lists of ordinary links.
|
|
1025
|
+
- Panels render in place (not portaled), so Tab moves from a trigger into its links in order.
|
|
1026
|
+
- Left/Right move between top-level items; ArrowDown on a trigger opens it and focuses the first link; Up/Down move between links; Escape closes and returns focus to the trigger.
|
|
1027
|
+
|
|
1028
|
+
## DOM contract (for agents operating the page)
|
|
1029
|
+
|
|
1030
|
+
- Selector: `[data-sw="navigation-menu"]`
|
|
1031
|
+
- `aria-expanded`: on each [data-sw="navigation-menu-trigger"]
|
|
1032
|
+
- `data-state`: open | closed on root, items and triggers
|
|
1033
|
+
- `aria-current`: "page" on the current [data-sw="navigation-menu-link"]
|
|
1034
|
+
- How to operate: Click a [data-sw="navigation-menu-trigger"], then click a [data-sw="navigation-menu-link"]. Agent bridge: open(value), close(), setValue(value | null); items = triggers.
|
|
1035
|
+
|
|
1036
|
+
Related: `tabs`
|
|
1037
|
+
|
|
1038
|
+
---
|
|
1039
|
+
|
|
1040
|
+
# Pagination
|
|
1041
|
+
|
|
1042
|
+
> Numbered pages with ellipses and Previous / Next, as buttons (onPageChange) or links (getHref).
|
|
1043
|
+
|
|
1044
|
+
Category: navigation · Status: beta · Slug: `pagination`
|
|
1045
|
+
|
|
1046
|
+
```tsx
|
|
1047
|
+
import { Pagination, paginationRange } from '@peerproblem/sw3-ui'
|
|
1048
|
+
```
|
|
1049
|
+
|
|
1050
|
+
## When to use
|
|
1051
|
+
- Paging through tables, search results or logs with a known number of pages.
|
|
1052
|
+
- Server-rendered lists where each page has its own URL (pass getHref).
|
|
1053
|
+
|
|
1054
|
+
## Avoid
|
|
1055
|
+
- Infinite feeds — use a "Load more" button.
|
|
1056
|
+
- Fewer than 2 pages — render nothing.
|
|
1057
|
+
- Stepping through a carousel — use Carousel.
|
|
1058
|
+
|
|
1059
|
+
## Props
|
|
1060
|
+
|
|
1061
|
+
| Prop | Type | Default | Description |
|
|
1062
|
+
| --- | --- | --- | --- |
|
|
1063
|
+
| `variant` | `'default' \| 'compact'` | `'default'` | compact is '‹ 2 / 5 ›' with 24px ghost Buttons, for a Card or tile header. Pair it with a controlled Carousel (controls and indicators off) to page a tile's content. |
|
|
1064
|
+
| `noun` | `string` | `'page'` | Names the compact buttons and status, e.g. "Next region". |
|
|
1065
|
+
| `page` | `number` | | Current page, from 1. Controlled. |
|
|
1066
|
+
| `defaultPage` | `number` | `1` | Starting page, when uncontrolled. |
|
|
1067
|
+
| `onPageChange` | `(page: number) => void` | | Called on page, Previous, Next, First or Last press. |
|
|
1068
|
+
| `pageCount` | `number` | | Number of pages. Or pass total + pageSize. |
|
|
1069
|
+
| `total` | `number` | | Number of items (with pageSize). |
|
|
1070
|
+
| `pageSize` | `number` | `10` | Items per page (with total). |
|
|
1071
|
+
| `siblings` | `number` | `1` | Pages shown on each side of the current one. |
|
|
1072
|
+
| `boundaries` | `number` | `1` | Pages always shown at each end. |
|
|
1073
|
+
| `getHref` | `(page: number) => string` | | Render pages as links to these URLs (work before JS, open in new tabs). |
|
|
1074
|
+
| `showFirstLast` | `boolean` | `false` | Add First and Last buttons. |
|
|
1075
|
+
| `simple` | `boolean` | `false` | Previous · "3 / 12" · Next, without numbers. |
|
|
1076
|
+
| `size` | `'sm' \| 'md'` | `'md'` | 30 / 36px buttons. |
|
|
1077
|
+
| `labels` | `{ previous?; next?; first?; last? }` | | Translate the step labels. |
|
|
1078
|
+
| `aria-label` | `string` | `'Pagination'` | Names the navigation landmark. |
|
|
1079
|
+
|
|
1080
|
+
## Examples
|
|
1081
|
+
|
|
1082
|
+
### Buttons
|
|
1083
|
+
|
|
1084
|
+
```tsx
|
|
1085
|
+
const [page, setPage] = useState(1)
|
|
1086
|
+
|
|
1087
|
+
<Pagination page={page} onPageChange={setPage} total={482} pageSize={20} />
|
|
1088
|
+
```
|
|
1089
|
+
|
|
1090
|
+
### Links
|
|
1091
|
+
|
|
1092
|
+
```tsx
|
|
1093
|
+
<Pagination defaultPage={4} pageCount={30} getHref={(p) => `/runs?page=${p}`} siblings={2} showFirstLast />
|
|
1094
|
+
```
|
|
1095
|
+
|
|
1096
|
+
### Custom markup from the range helper
|
|
1097
|
+
|
|
1098
|
+
```tsx
|
|
1099
|
+
paginationRange(6, 20, 1, 1) // [1, 'ellipsis-start', 5, 6, 7, 'ellipsis-end', 20]
|
|
1100
|
+
```
|
|
1101
|
+
|
|
1102
|
+
## Rules
|
|
1103
|
+
- Place it under the list it pages, centred or right-aligned.
|
|
1104
|
+
- Keep siblings at 1 on phones; the row wraps rather than scrolling.
|
|
1105
|
+
|
|
1106
|
+
## Accessibility
|
|
1107
|
+
- <nav aria-label="Pagination"> with a list; the current page has aria-current="page".
|
|
1108
|
+
- Previous/Next at the ends get aria-disabled and stay focusable (buttons) or lose href (links).
|
|
1109
|
+
- Ellipses are aria-hidden.
|
|
1110
|
+
|
|
1111
|
+
## DOM contract (for agents operating the page)
|
|
1112
|
+
|
|
1113
|
+
- Selector: `[data-sw="pagination"]`
|
|
1114
|
+
- `aria-current`: "page" on the current [data-sw="pagination-link"]
|
|
1115
|
+
- `data-page`: page number on each [data-sw="pagination-link"]
|
|
1116
|
+
- `aria-disabled`: on [data-sw="pagination-previous"] / [data-sw="pagination-next"] at the ends
|
|
1117
|
+
- How to operate: Click [data-sw="pagination-link"][data-page="N"], or pagination-next / pagination-previous. Agent bridge: setPage(n), next(), previous(), first(), last(); state = { page, pageCount }.
|
|
1118
|
+
|
|
1119
|
+
Related: `carousel`
|
|
1120
|
+
|
|
1121
|
+
---
|
|
1122
|
+
|
|
1123
|
+
# Breadcrumbs
|
|
1124
|
+
|
|
1125
|
+
> Where you are in the hierarchy ("Acme / API / Incidents") for the shell header. Middle items shrink first.
|
|
1126
|
+
|
|
1127
|
+
Category: navigation · Status: beta · Slug: `breadcrumbs`
|
|
1128
|
+
|
|
1129
|
+
```tsx
|
|
1130
|
+
import { Breadcrumbs } from '@peerproblem/sw3-ui'
|
|
1131
|
+
```
|
|
1132
|
+
|
|
1133
|
+
## When to use
|
|
1134
|
+
- The leading slot of AppShellHeader, in apps with workspace → project → page levels.
|
|
1135
|
+
|
|
1136
|
+
## Avoid
|
|
1137
|
+
- Repeating the sidebar. Show the levels the sidebar doesn't.
|
|
1138
|
+
- Navigation between sibling pages. Use the sidebar or Tabs.
|
|
1139
|
+
|
|
1140
|
+
## Props
|
|
1141
|
+
|
|
1142
|
+
| Prop | Type | Default | Description |
|
|
1143
|
+
| --- | --- | --- | --- |
|
|
1144
|
+
| `items` * | `{ label; href?; onClick?; icon? }[]` | | From the root to the current page. The last item is the current page. |
|
|
1145
|
+
|
|
1146
|
+
## Examples
|
|
1147
|
+
|
|
1148
|
+
### Header path
|
|
1149
|
+
|
|
1150
|
+
```tsx
|
|
1151
|
+
<Breadcrumbs items={[{ label: 'Acme', href: '#/' }, { label: 'API', href: '#/api' }, { label: 'Incidents' }]} />
|
|
1152
|
+
```
|
|
1153
|
+
|
|
1154
|
+
## Rules
|
|
1155
|
+
- Keep it to 2–4 levels.
|
|
1156
|
+
|
|
1157
|
+
## Accessibility
|
|
1158
|
+
- <nav aria-label="Breadcrumb"> with an ordered list. The last item has aria-current="page".
|
|
1159
|
+
|
|
1160
|
+
## DOM contract (for agents operating the page)
|
|
1161
|
+
|
|
1162
|
+
- Selector: `[data-sw="breadcrumbs"]`
|
|
1163
|
+
- How to operate: Click a link in the list.
|
|
1164
|
+
|
|
1165
|
+
Related: `app-shell`
|
|
1166
|
+
|
|
1167
|
+
---
|