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