@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,77 @@
1
+ # ImageCropper
2
+
3
+ > Move and resize a crop over an image (or pan and zoom the image under a fixed frame) with pointer and keyboard; the crop is {x, y, width, height} in image pixels, and cropImage() turns it into a Blob.
4
+
5
+ Category: inputs · Status: beta · Slug: `image-cropper`
6
+
7
+ ```tsx
8
+ import { ImageCropper, cropImage, type CropRect } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Avatar and cover-image editors.
13
+ - Cropping a screenshot before attaching it.
14
+ - Choosing a region of an image to send to a vision model.
15
+
16
+ ## Avoid
17
+ - Cropping with CSS `object-position` and calling it saved — the file is unchanged. Use `cropImage(src, crop)` and upload the Blob.
18
+ - Cross-origin images without CORS headers: the canvas is tainted and cropImage fails. Use object URLs or same-origin images.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `src` * | `string` | | Image URL (an object URL for a picked file works well). |
25
+ | `alt` | `string` | | Describes the image. |
26
+ | `crop / defaultCrop` | `{ x: number; y: number; width: number; height: number }` | | The crop in image pixels. Starts at 4/5 of the largest crop at the ratio, centered. |
27
+ | `onCropChange` | `(crop: CropRect) => void` | | Every drag step, key or wheel tick, and once the image loads. |
28
+ | `onCropCommit` | `(crop: CropRect) => void` | | Once an interaction ends. Save here. |
29
+ | `mode` | `'box' \| 'frame'` | `'box'` | box: move/resize a selection. frame: the selection stays put, drag/wheel pans and zooms the image (avatar editor). |
30
+ | `aspectRatio` | `number` | | Lock width/height, e.g. 1 or 16 / 9. Defaults to 1 in frame mode. |
31
+ | `shape` | `'rect' \| 'circle'` | `'rect'` | circle rounds the selection; pass shape to cropImage too. |
32
+ | `minWidth / minHeight` | `number` | `16` | Smallest crop in image px. |
33
+ | `maxZoom` | `number` | `4` | Largest zoom (1 = largest crop the image allows). |
34
+ | `grid` | `boolean` | `true` | Rule-of-thirds lines. |
35
+ | `zoomControl` | `boolean` | `true` | Zoom slider under the image. |
36
+ | `height` | `number` | `320` | Viewport height in px (width fills the container). |
37
+ | `disabled` | `boolean` | | Stops every change. |
38
+ | `children` | `ReactNode` | | Extra toolbar controls next to the zoom slider (e.g. a Crop button). |
39
+ | `cropImage(src, rect, { type?, quality?, shape?, width? })` | `Promise<Blob>` | | Canvas helper: crops (and optionally rounds/resizes) to a Blob. Browser only. |
40
+
41
+ ## Examples
42
+
43
+ ### Square crop and save
44
+
45
+ ```tsx
46
+ const [crop, setCrop] = useState<CropRect>()
47
+
48
+ <ImageCropper src={url} alt="Profile photo" aspectRatio={1} crop={crop} onCropChange={setCrop}>
49
+ <Button size="sm" onClick={async () => upload(await cropImage(url, crop!, { width: 256 }))}>Save</Button>
50
+ </ImageCropper>
51
+ ```
52
+
53
+ ### Avatar editor (frame mode)
54
+
55
+ ```tsx
56
+ <ImageCropper src={url} alt="" mode="frame" shape="circle" onCropCommit={setCrop} />
57
+ // later: cropImage(url, crop, { shape: 'circle', width: 128 })
58
+ ```
59
+
60
+ ## Rules
61
+ - Keep the crop in state from onCropChange (or onCropCommit) and pass it to cropImage; never measure the DOM.
62
+ - Use frame mode + circle for avatars, box mode for free-form crops.
63
+
64
+ ## Accessibility
65
+ - The cropper is a group. The selection and each handle are sliders announcing "W by H pixels, at X, Y".
66
+ - Arrows move the selection (on a handle: its edges); Shift moves 10×; + / − zoom; Escape during a drag restores the crop.
67
+
68
+ ## DOM contract (for agents operating the page)
69
+
70
+ - Selector: `[data-sw="image-cropper"]`
71
+ - `data-status`: 'loading' | 'ready' | 'error'
72
+ - `data-dragging`: pointer drag in progress
73
+ - `data-mode`: 'box' | 'frame'
74
+ - `data-shape`: 'rect' | 'circle'
75
+ - How to operate: Agent bridge: setCrop({x,y,width,height}) (also setValue), setZoom(n), reset(); state has crop, zoom and image size. DOM: focus [data-sw="image-cropper-selection"] and press arrow keys.
76
+
77
+ Related: `file-input`, `avatar`
@@ -0,0 +1,49 @@
1
+ # Input
2
+
3
+ > A text field with label, hint, error and optional prefix/suffix, in a squircle frame.
4
+
5
+ Category: inputs · Status: stable · Slug: `input`
6
+
7
+ ```tsx
8
+ import { Input } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Single-line text, email, number, search.
13
+
14
+ ## Avoid
15
+ - Placeholder as the only label — always pass `label` (or aria-label).
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ | --- | --- | --- | --- |
21
+ | `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Heights 28 / 32 / 40 / 52px. Use xs for dense toolbars and card headers. |
22
+ | `variant` | `'outline' \| 'filled'` | `'outline'` | filled: a borderless muted well whose frame appears on focus. Use it for search in dense toolbars. |
23
+ | `shortcut` | `string` | | A key that focuses the field, e.g. '/' or 'mod+k'. Shown as a hint while the field is empty. |
24
+ | `label` | `ReactNode` | | Visible label. |
25
+ | `hint` | `ReactNode` | | Help text under the field. |
26
+ | `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
27
+ | `invalid` | `boolean` | | Mark invalid without error text (e.g. inside a Field that shows the error). |
28
+ | `clearable` | `boolean` | `false` | Show a × button that clears the value (data-sw="input-clear"). |
29
+ | `onValueChange` | `(value: string) => void` | | Called with the new text on every change, including clear. |
30
+ | `prefix / suffix` | `ReactNode` | | Icon or unit inside the field. |
31
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'sm'` | Squircle corner radius (token or px). |
32
+ | `...rest` | `InputHTMLAttributes` | | value, onChange, type, placeholder… |
33
+
34
+ ## Examples
35
+
36
+ ### Email
37
+
38
+ ```tsx
39
+ <Input label="Email" type="email" placeholder="you@company.com" />
40
+ ```
41
+
42
+ ## Rules
43
+ - Search in a list toolbar: `<Input type="search" size="xs" variant="filled" prefix={<Icon name="search"/>} clearable aria-label="Search …"/>`. Escape clears it.
44
+
45
+ ## DOM contract (for agents operating the page)
46
+
47
+ - Selector: `[data-sw="input"] input`
48
+ - `aria-invalid`: true on error
49
+ - How to operate: Type into the <input>; its <label> names it. Works inside <Field>. Agent bridge: setValue(text), clear().
@@ -0,0 +1,53 @@
1
+ # Label
2
+
3
+ > Names any control; pressing it focuses or activates the control, even groups a native label cannot reach.
4
+
5
+ Category: inputs · Status: beta · Slug: `label`
6
+
7
+ ```tsx
8
+ import { Label } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A visible name for a control outside a Field: `<Label htmlFor="plan">` next to `<RadioGroup id="plan">`.
13
+ - Inside `<Field>` (no htmlFor needed) — same as FieldLabel.
14
+
15
+ ## Avoid
16
+ - Label without htmlFor outside a Field — it names nothing. Use Field, or a control with its own `label` prop.
17
+ - Using a <span> as a label — screen readers and agents won’t connect it.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `htmlFor` | `string` | | id of the control. Optional inside a Field. |
24
+ | `required` | `boolean` | | Show a `*` marker. |
25
+ | `...rest` | `LabelHTMLAttributes` | | id, className, children… |
26
+
27
+ ## Examples
28
+
29
+ ### Label a radio group
30
+
31
+ ```tsx
32
+ <Label htmlFor="plan">Plan</Label>
33
+ <RadioGroup id="plan" defaultValue="pro" items={[{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }]} />
34
+ ```
35
+
36
+ ### Inside a Field
37
+
38
+ ```tsx
39
+ <Field>
40
+ <Label>Model</Label>
41
+ <Input defaultValue="sw3-large" />
42
+ </Field>
43
+ ```
44
+
45
+ ## Accessibility
46
+ - Renders a native <label>. Non-labelable targets get aria-labelledby pointing at it (unless they already have a name).
47
+
48
+ ## DOM contract (for agents operating the page)
49
+
50
+ - Selector: `[data-sw="label"]`
51
+ - How to operate: Click it to focus/check its control.
52
+
53
+ Related: `field`
@@ -0,0 +1,60 @@
1
+ # LineChart
2
+
3
+ > Trends over time for 1–5 series. Built on Unovis VisLine.
4
+
5
+ Category: charts · Status: beta · Slug: `line-chart`
6
+
7
+ ```tsx
8
+ import { LineChart, ChartCard } from '@peerproblem/sw3-ui/charts'
9
+ ```
10
+
11
+ ## When to use
12
+ - A value changing over time.
13
+ - Comparing a few trends.
14
+
15
+ ## Avoid
16
+ - Categories with no order — use BarChart.
17
+ - More than 5 lines.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `data` * | `D[]` | | Array of rows. |
24
+ | `x` * | `keyof D \| (d, i) => number \| Date \| string` | | X field. Numbers/Dates use a scale; strings become ordered categories. |
25
+ | `series` * | `Array<{ key: keyof D; label?: string; color?: string }>` | | One entry per plotted field. Colors default to --sw-chart-1..8 in order. |
26
+ | `height` | `number` | `240` | Pixels. Width fills the parent. |
27
+ | `xFormat / yFormat` | `(v) => string` | | Tick and tooltip formatting. y defaults to compact (12.4k). |
28
+ | `showXAxis / showYAxis / showGrid` | `boolean` | `true` | Axes and horizontal grid. |
29
+ | `tooltip` | `boolean` | `true` | Crosshair + tooltip on hover. |
30
+ | `yDomain` | `[min?, max?]` | | Fix the y range, e.g. [0, undefined]. |
31
+ | `aria-label` | `string` | | Text summary of the chart. Always set it — agents and screen readers cannot read SVG. |
32
+ | `curve` | `'smooth' \| 'linear' \| 'step'` | `'smooth'` | |
33
+ | `lineWidth` | `number` | `2` | |
34
+
35
+ ## Examples
36
+
37
+ ### Traffic
38
+
39
+ ```tsx
40
+ const data = [{ day: 'Mon', visits: 120, signups: 12 }, { day: 'Tue', visits: 180, signups: 20 } /* … */]
41
+
42
+ <ChartCard title="Traffic" description="Last 7 days" value="12.4k" legend={[{ key: 'visits', label: 'Visits' }, { key: 'signups', label: 'Sign-ups' }]}>
43
+ <LineChart aria-label="Visits rose all week" data={data} x="day" series={[{ key: 'visits', label: 'Visits' }, { key: 'signups', label: 'Sign-ups' }]} />
44
+ </ChartCard>
45
+ ```
46
+
47
+ ## Rules
48
+ - Wrap the chart in <ChartCard> and give the card a title.
49
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
50
+ - Use the default palette order; color 1 (blue) is the primary series.
51
+ - Max 5 series per chart. Do not use dual y-axes.
52
+
53
+ ## DOM contract (for agents operating the page)
54
+
55
+ - Selector: `[data-sw="chart"]`
56
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
57
+ - `aria-label`: the summary
58
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
59
+
60
+ Related: `area-chart`, `chart-card`
@@ -0,0 +1,84 @@
1
+ # Listbox
2
+
3
+ > An always-visible framed list to pick one or several options, with one tab stop and full keyboard support.
4
+
5
+ Category: selection · Status: beta · Slug: `listbox`
6
+
7
+ ```tsx
8
+ import { Listbox, ListboxItem, ListboxGroup, ListboxSeparator } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Picking from a list that should stay visible (sidebar of files, a picker inside a dialog).
13
+ - Multi-select of a short list where seeing every option matters.
14
+
15
+ ## Avoid
16
+ - Saving space — use Select (popup).
17
+ - Searching many items — use Combobox or Command.
18
+ - Rich rows with buttons inside — use a list of Cards or a table.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `items[].meta` | `ReactNode` | | Quiet trailing text (time, count) that gives its place to the actions on hover. |
25
+ | `items[].actions / items[].menu` | `{ label; icon?; onSelect; destructive?; disabled? }[]` | | Row actions as data. The SDK renders 24px ghost Buttons with tooltips, centred on the row, plus a ⋯ menu. A reorderable list adds Move to top/up/down to that menu. Actions are always shown on touch. |
26
+ | `framed` | `boolean` | | Default: true on its own (capped at 320px), false inside a Card or Accordion. Unframed, rows sit 6px from the container edge and their content starts on its 12px line. |
27
+ | `--sw-listbox-max-height` | `CSS length \| none` | `320px framed, none unframed` | Set on an ancestor to change when the list scrolls. `none` never scrolls; a length scrolls inside with the slim scrollbar and keeps the focused row in view. |
28
+ | `descriptionLayout` | `'below' \| 'inline'` | `'below'` | inline puts the description after the label, for dense data rows. |
29
+ | `onItemAction` | `(value) => void` | | Enter or double-click: open or drill in. |
30
+ | `onReorder / reorderable / handle` | `(values, { id, from, to }) => void / boolean / 'hover' \| 'always' \| 'none'` | | Rows drag from their body with a mouse (after 5px) and from the grip by touch, with a drop line and preview. Alt+↑/↓ and the ⋯ menu's Move items also reorder. The 'hover' grip swaps with the row icon. Pass `useListQuery().reorderable` so reordering stops while searching or sorted. |
31
+ | `items` | `Array<{ value: string; label: string; keywords?: string[]; disabled?: boolean; icon?: ReactNode; description?: ReactNode } \| { type: 'group'; label: string; items: [...] } \| { type: 'separator' }>` | | Options as data — the one-line way. Or pass `<ListboxItem>` children instead. |
32
+ | `value / defaultValue / onValueChange` | `string \| null (string[] with multiple)` | | Selected value(s). |
33
+ | `multiple` | `boolean` | `false` | Pick several; Ctrl/⌘+A selects all. |
34
+ | `activation` | `'automatic' \| 'manual'` | `'automatic' (single), 'manual' (multiple)` | Whether arrow keys select as they move, or only Enter/Space/click selects. |
35
+ | `deselectable` | `boolean` | `false` | Single: pressing the selected item clears it. |
36
+ | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Which arrow keys move. |
37
+ | `loop` | `boolean` | `true` | Arrow keys wrap. |
38
+ | `emptyMessage` | `ReactNode` | `"No options"` | Shown with no options. |
39
+ | `name` | `string` | | Native form field name; the value submits through hidden inputs (one per value when multiple). |
40
+ | `disabled / readOnly / required / invalid` | `boolean` | | States. Inherit from a surrounding `<Field>`. |
41
+ | `aria-label` | `string` | | Accessible name when there is no visible label or Field. |
42
+
43
+ ## Examples
44
+
45
+ ### Single
46
+
47
+ ```tsx
48
+ <Listbox aria-label="Environment" defaultValue="staging" items={[
49
+ { value: 'prod', label: 'Production' },
50
+ { value: 'staging', label: 'Staging' },
51
+ { value: 'dev', label: 'Development' },
52
+ ]} />
53
+ ```
54
+
55
+ ### Multiple with children
56
+
57
+ ```tsx
58
+ <Listbox multiple aria-label="Tools" value={tools} onValueChange={setTools}>
59
+ <ListboxItem value="search">Web search</ListboxItem>
60
+ <ListboxItem value="code">Code execution</ListboxItem>
61
+ <ListboxItem value="files" disabled>File system</ListboxItem>
62
+ </Listbox>
63
+ ```
64
+
65
+ ## Rules
66
+ - Row height follows the density preference (`data-density`: compact 28, comfortable 32, spacious 40). Do not set heights per list.
67
+ - Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
68
+ - It grows with its options up to 320px, then scrolls inside its frame.
69
+ - Chosen options use the neutral selected fill and 500-weight labels. Multi-select adds a trailing check so several choices remain easy to scan. Pointer and keyboard highlight one active row at a time.
70
+
71
+ ## Accessibility
72
+ - role="listbox" (one tab stop) with aria-activedescendant; options role="option" + aria-selected; aria-multiselectable with multiple.
73
+ - Arrows move, Home/End jump, typing jumps by label, Enter/Space select.
74
+
75
+ ## DOM contract (for agents operating the page)
76
+
77
+ - Selector: `[data-sw="listbox"]`
78
+ - `aria-selected`: on each [role=option]
79
+ - `data-value`: on each option
80
+ - `aria-activedescendant`: highlighted option id
81
+ - `data-disabled`: present when disabled
82
+ - How to operate: Click an option ([data-sw="listbox-item"]). Agent bridge: setValue(value | value[]), select(value) (toggles with multiple), clear(); items = options.
83
+
84
+ Related: `select`, `combobox`, `radio`
@@ -0,0 +1,104 @@
1
+ # MapView
2
+
3
+ > A MapLibre GL map in a squircle Card with routes, pins, categorized locations, and highlighted areas.
4
+
5
+ Category: map · Status: beta · Slug: `map-view`
6
+
7
+ ```tsx
8
+ import { MapView } from '@peerproblem/sw3-ui/map'
9
+ import 'maplibre-gl/dist/maplibre-gl.css'
10
+ ```
11
+
12
+ ## When to use
13
+ - Showing a route, track or path (GeoJSON LineString).
14
+ - Showing locations such as shelters, closures, and emergency resources with or without routes.
15
+ - Highlighting a known advisory, closure or coverage boundary.
16
+
17
+ ## Avoid
18
+ - Forgetting the maplibre-gl CSS import — controls and canvas will be misplaced.
19
+ - Relying on the default MapLibre worker URL in a bundled app. Configure the worker before the first map. See the Maps guide.
20
+ - Thousands of markers — add a GeoJSON circle layer through onLoad instead.
21
+ - Picking line colors by hand — leave `color` unset to use the accent token.
22
+
23
+ ## Props
24
+
25
+ | Prop | Type | Default | Description |
26
+ | --- | --- | --- | --- |
27
+ | `routes` | `Array<{ coordinates: [lng, lat][]; color?: string; width?: number; dashed?: boolean; id?: string }>` | | Lines to draw. Coordinates are [longitude, latitude] — GeoJSON order. |
28
+ | `geojson` | `GeoJSON.Feature \| GeoJSON.FeatureCollection` | | Alternative input: any LineString features. |
29
+ | `markers` | `Array<{ lngLat: [lng, lat]; label?: string; description?: string; kind?: 'default' \| 'start' \| 'end' \| 'pin' \| 'impact' \| 'incident' \| 'shelter' \| 'closure' \| 'resource' \| 'origin' }>` | | Points with or without routes. Categorized markers use a glyph and category label, and appear with their name and optional description in the locations list. |
30
+ | `areas` | `readonly MapArea[]` | | Named GeoJSON Polygon or MultiPolygon regions with a stable id, label, optional description, accent, warning or danger tone, and a defined (solid) or approximate (dashed) boundary. |
31
+ | `areaListLabel` | `string` | `Map areas` | Label for the visible list of regions below the map. |
32
+ | `markerListLabel` | `string` | `Map locations` | Label for the visible list below the map when categorized markers are present. |
33
+ | `MapMarker.popup` | `{ title?: string; description: string }` | | Plain-text details opened by clicking the marker or its Show details button. |
34
+ | `workerUrl` | `string` | | Bundled MapLibre worker URL. See the Maps guide for Next.js. |
35
+ | `fitToData` | `boolean` | `true` | Zoom to fit routes, markers and areas. |
36
+ | `center / zoom` | `[lng, lat] / number` | `first point / 13` | Initial camera when not fitting. |
37
+ | `animateRoutes` | `boolean` | `false` | Draw the lines on with a 1.6s motion animation. |
38
+ | `height` | `number` | `360` | Pixels. |
39
+ | `basemap` | `'auto' \| 'light' \| 'dark' \| 'bright' \| string` | `'auto'` | auto follows the theme (OpenFreeMap positron/dark, no API key). Or any MapLibre style URL. |
40
+ | `interactive` | `boolean` | `true` | Pan/zoom + zoom buttons. |
41
+ | `overlay` | `ReactNode` | | Content pinned 12px from the top and left edges. Use <Squircle concentric borderWidth={0}> for an overlay surface that follows the map’s radius minus the inset and inherits its smoothing. |
42
+ | `controls` | `ReactNode` | | Additional actions below the zoom group (top-right). Use an icon-only Button with size="md" and an accessible name. |
43
+ | `onLoad` | `(map: maplibregl.Map) => void` | | Escape hatch for custom layers. |
44
+ | `radius` | `RadiusValue` | `'lg'` | Squircle corners of the frame. |
45
+
46
+ ## Examples
47
+
48
+ ### Route with start/end
49
+
50
+ ```tsx
51
+ const route: [number, number][] = [
52
+ [-122.48369693756104, 37.83381888486939],
53
+ [-122.48348236083984, 37.83317489144141],
54
+ // …
55
+ [-122.49378204345702, 37.83368330777276],
56
+ ]
57
+
58
+ <MapView
59
+ height={420}
60
+ animateRoutes
61
+ routes={[{ coordinates: route }]}
62
+ markers={[
63
+ { lngLat: route[0], kind: 'start', label: 'Start' },
64
+ { lngLat: route[route.length - 1], kind: 'end', label: 'Finish' },
65
+ ]}
66
+ />
67
+ ```
68
+
69
+ ### Emergency locations
70
+
71
+ ```tsx
72
+ <MapView
73
+ markerListLabel="Emergency locations"
74
+ areas={[{
75
+ id: 'advisory', label: 'Flood advisory area', tone: 'warning', boundary: 'approximate',
76
+ geometry: { type: 'Polygon', coordinates: [[[24.78, 60.19], [24.81, 60.19], [24.81, 60.21], [24.78, 60.19]]] },
77
+ }]}
78
+ markers={[
79
+ { lngLat: [24.79, 60.20], kind: 'pin', label: 'Meeting point' },
80
+ { lngLat: [24.83, 60.18], kind: 'closure', label: 'Ring I', description: 'Eastbound lane closed.' },
81
+ { lngLat: [24.79, 60.20], kind: 'shelter', label: 'Community center', description: 'Open overnight.' },
82
+ ]}
83
+ />
84
+ ```
85
+
86
+ ## Rules
87
+ - Pass coordinates in GeoJSON order: [longitude, latitude].
88
+ - Use one accent route and style additional routes with chart tokens or the dashed option.
89
+ - Supply a short location name and put useful details in description for pins, categorized markers and areas.
90
+ - Use approximate for estimated extent and defined for a known boundary. The map renders a subtle tint below place labels.
91
+ - Close each polygon ring by repeating its first coordinate. Keep map credits visible for the selected basemap.
92
+ - The zoom group uses its own sm squircle, including when the map frame is square. Use controls for nearby map actions.
93
+
94
+ ## Accessibility
95
+ - Give the surrounding section a heading that describes the map.
96
+ - Categorized points use glyphs and text labels so categories can be distinguished without color.
97
+ - The locations list below the map provides each categorized point’s type, name and description as readable text. Static markers do not add tab stops. Areas have names and textual boundary status in a separate list. In interactive maps, each area has a keyboard-accessible zoom button.
98
+
99
+ ## DOM contract (for agents operating the page)
100
+
101
+ - Selector: `[data-sw="map"]`
102
+ - `[data-sw="map-marker"]`: marker elements with data-kind and text labels
103
+ - `[data-sw="map-controls"]`: additional map actions supplied by the app
104
+ - How to operate: Read area names and boundary status in the areas list and use its zoom buttons to inspect boundaries. Read location details in the locations list. Use onLoad to expose the map instance if an agent must control the camera.
@@ -0,0 +1,117 @@
1
+ # Menu
2
+
3
+ > 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.
4
+
5
+ Category: overlays · Status: beta · Slug: `menu`
6
+
7
+ ```tsx
8
+ import { Menu, MenuTrigger, MenuContent, MenuItem, MenuGroup, MenuLabel, MenuSeparator, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuSub, MenuSubTrigger, MenuSubContent, ContextMenu, ContextMenuTrigger } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A short list of actions on an object ("…" overflow, row actions, account menu).
13
+ - 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.
14
+ - Right-click actions on an area: `<ContextMenu><ContextMenuTrigger>…</ContextMenuTrigger><MenuContent>…</MenuContent></ContextMenu>`.
15
+
16
+ ## Avoid
17
+ - Choosing a form value with a Menu — use Select (it shows the value and submits it).
18
+ - Searching through many commands — use Command.
19
+ - Navigation links for a site — use NavigationMenu / links, not menuitems.
20
+ - Putting inputs or long content inside a menu — use Popover.
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Default | Description |
25
+ | --- | --- | --- | --- |
26
+ | `open / defaultOpen / onOpenChange` | `boolean / (open: boolean) => void` | | Menu: controlled or uncontrolled open state. |
27
+ | `onAction` | `(value: string) => void` | | Menu: runs for every plain MenuItem (also in submenus) with its `value`. |
28
+ | `loop` | `boolean` | `true` | Menu: arrow keys wrap. |
29
+ | `asChild` | `boolean` | | MenuTrigger / ContextMenuTrigger: clone your single child element (e.g. `<Button>`) with the trigger props instead of rendering the default button / div. |
30
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | MenuTrigger: size of the default framed trigger button. |
31
+ | `placement / offset` | `Placement / number` | `'bottom-start' / 6` | MenuContent / MenuSubContent: side and gap (submenus default 'right-start' / 2). |
32
+ | `value` | `string` | | MenuItem: passed to `onAction`. MenuRadioItem: required, the radio value. |
33
+ | `onSelect` | `(event) => void` | | MenuItem: runs when chosen; `event.preventDefault()` keeps the menu open and skips onAction. |
34
+ | `icon / shortcut` | `ReactNode / string` | | Items: leading icon; shortcut hint like "mod+d" (⌘D / Ctrl+D) — display + aria-keyshortcuts only. |
35
+ | `destructive` | `boolean` | | MenuItem: red, for Delete. |
36
+ | `disabled` | `boolean` | | Items and triggers: cannot be chosen; keyboard skips it. |
37
+ | `label` | `string` | | Items: text typeahead matches when children are not plain text. MenuGroup: shorthand heading. |
38
+ | `closeOnSelect` | `boolean` | `true for MenuItem, false for checkbox / radio items` | Close after choosing. |
39
+ | `checked / defaultChecked / onCheckedChange` | `boolean / (checked) => void` | | MenuCheckboxItem state. |
40
+ | `value / defaultValue / onValueChange` | `string / (value) => void` | | MenuRadioGroup state. |
41
+
42
+ ## Examples
43
+
44
+ ### Actions
45
+
46
+ ```tsx
47
+ <Menu onAction={(v) => console.log(v)}>
48
+ <MenuTrigger>Actions</MenuTrigger>
49
+ <MenuContent>
50
+ <MenuItem value="rename" shortcut="mod+r">Rename</MenuItem>
51
+ <MenuItem value="duplicate" shortcut="mod+d">Duplicate</MenuItem>
52
+ <MenuSeparator />
53
+ <MenuItem value="delete" destructive>Delete</MenuItem>
54
+ </MenuContent>
55
+ </Menu>
56
+ ```
57
+
58
+ ### Options, radios and a submenu with your own button
59
+
60
+ ```tsx
61
+ <Menu>
62
+ <MenuTrigger asChild><Button variant="outline" size="sm">View</Button></MenuTrigger>
63
+ <MenuContent>
64
+ <MenuCheckboxItem checked={showLogs} onCheckedChange={setShowLogs}>Show logs</MenuCheckboxItem>
65
+ <MenuGroup label="Sort by">
66
+ <MenuRadioGroup value={sort} onValueChange={setSort}>
67
+ <MenuRadioItem value="recent">Most recent</MenuRadioItem>
68
+ <MenuRadioItem value="name">Name</MenuRadioItem>
69
+ </MenuRadioGroup>
70
+ </MenuGroup>
71
+ <MenuSub>
72
+ <MenuSubTrigger>Export</MenuSubTrigger>
73
+ <MenuSubContent>
74
+ <MenuItem value="csv">CSV</MenuItem>
75
+ <MenuItem value="json">JSON</MenuItem>
76
+ </MenuSubContent>
77
+ </MenuSub>
78
+ </MenuContent>
79
+ </Menu>
80
+ ```
81
+
82
+ ### Context menu
83
+
84
+ ```tsx
85
+ <ContextMenu onAction={runAction}>
86
+ <ContextMenuTrigger>
87
+ <Card>Right-click this run</Card>
88
+ </ContextMenuTrigger>
89
+ <MenuContent>
90
+ <MenuItem value="rerun">Re-run</MenuItem>
91
+ <MenuItem value="copy-id">Copy run ID</MenuItem>
92
+ </MenuContent>
93
+ </ContextMenu>
94
+ ```
95
+
96
+ ## Rules
97
+ - Item labels are verbs in sentence case ("Duplicate", "Copy link").
98
+ - Group related items with MenuGroup/MenuSeparator; keep a menu under ~10 items, move the rest into a submenu.
99
+ - Destructive items go last, after a separator (`destructive` sets data-tone="danger": red label and icon).
100
+ - Checkbox and radio items show a trailing accent check; plain items never do.
101
+ - Trigger parts render a framed squircle button by default; pass `asChild` to use your own Button.
102
+
103
+ ## Accessibility
104
+ - Trigger: aria-haspopup="menu", aria-expanded, aria-controls. ArrowDown/Enter/Space open and focus the first item; ArrowUp the last.
105
+ - Content role="menu"; items role="menuitem" / "menuitemcheckbox" / "menuitemradio" with roving focus.
106
+ - Arrows move (wrap), Home/End jump, typing jumps by label, Enter/Space choose, Escape closes one level and returns focus, Tab closes.
107
+ - ArrowRight opens a submenu, ArrowLeft closes it. Context menu also opens with Shift+F10 / the Menu key and a long press on touch.
108
+
109
+ ## DOM contract (for agents operating the page)
110
+
111
+ - Selector: `[data-sw="menu-trigger"], [data-sw="menu-context-trigger"]`
112
+ - `aria-expanded`: on the trigger: whether open
113
+ - `data-state`: trigger: 'open' | 'closed'
114
+ - `[data-sw="menu-content"] [data-sw-menu-item]`: the items while open; `data-value`, `data-label`, `aria-checked` (checkbox/radio), `data-disabled`
115
+ - 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.
116
+
117
+ Related: `menubar`, `command`, `select`, `popover`
@@ -0,0 +1,67 @@
1
+ # Menubar
2
+
3
+ > A horizontal bar of menus (File, Edit, View) with one tab stop, arrow keys between menus and hover-switching while one is open.
4
+
5
+ Category: navigation · Status: beta · Slug: `menubar`
6
+
7
+ ```tsx
8
+ import { Menubar, Menu, MenuTrigger, MenuContent, MenuItem } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Desktop-style apps and editors with several command menus.
13
+ - A toolbar of 2–6 menus that share the same keyboard model.
14
+
15
+ ## Avoid
16
+ - Site navigation — use NavigationMenu or links.
17
+ - A single menu — use Menu on its own.
18
+ - Phones-first UIs with many menus — collapse into one Menu.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `children` * | `ReactNode` | | `<Menu>` elements, each with a `<MenuTrigger>` (rendered as a bar item) and `<MenuContent>`. |
25
+ | `loop` | `boolean` | `true` | Arrow keys wrap from the last menu to the first. |
26
+ | `disabled` | `boolean` | `false` | Disable every menu. |
27
+ | `bordered` | `boolean` | `true` | Draw the squircle frame around the bar. |
28
+
29
+ ## Examples
30
+
31
+ ### Editor menubar
32
+
33
+ ```tsx
34
+ <Menubar aria-label="Editor">
35
+ <Menu onAction={run}>
36
+ <MenuTrigger>File</MenuTrigger>
37
+ <MenuContent>
38
+ <MenuItem value="new" shortcut="mod+n">New prompt</MenuItem>
39
+ <MenuItem value="open" shortcut="mod+o">Open…</MenuItem>
40
+ </MenuContent>
41
+ </Menu>
42
+ <Menu onAction={run}>
43
+ <MenuTrigger>Edit</MenuTrigger>
44
+ <MenuContent>
45
+ <MenuItem value="undo" shortcut="mod+z">Undo</MenuItem>
46
+ </MenuContent>
47
+ </Menu>
48
+ </Menubar>
49
+ ```
50
+
51
+ ## Rules
52
+ - Short one-word menu names in title order (File, Edit, View, Run, Help).
53
+ - Every Menu inside a Menubar needs a MenuTrigger and MenuContent; all Menu features (submenus, checkboxes) work.
54
+
55
+ ## Accessibility
56
+ - role="menubar" with triggers role="menuitem"; one tab stop (roving tabindex).
57
+ - ArrowLeft/Right move between menus (and switch the open menu), Home/End jump, ArrowDown/Enter/Space open.
58
+ - Inside an open menu ArrowLeft/Right move to the neighbouring menu.
59
+
60
+ ## DOM contract (for agents operating the page)
61
+
62
+ - Selector: `[data-sw="menubar"]`
63
+ - `data-state`: 'open' while any menu is open
64
+ - `[data-sw="menubar-trigger"]`: one per menu; aria-expanded, data-state
65
+ - 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)).
66
+
67
+ Related: `menu`, `toolbar`