@peerproblem/sw3-ui 0.0.0-stage → 0.3.0

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