@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,61 @@
1
+ # PosterCard
2
+
3
+ > A gallery tile: tight display words (outlined + solid) top-left, a mono caption under them, and a live component below. Height follows content.
4
+
5
+ Category: extras · Status: stable · Slug: `poster-card`
6
+
7
+ ```tsx
8
+ import { PosterCard } from '@peerproblem/sw3-ui/extras'
9
+ ```
10
+
11
+ ## When to use
12
+ - Showcasing a component, feature or behavior in a grid.
13
+ - Landing-page galleries (3 columns ≥1280px, 2 ≥640px, 1 on phones).
14
+
15
+ ## Avoid
16
+ - Long titles — 1–2 short words. Hyphenate long words manually: ["Accor-", "dion"].
17
+ - Captions longer than 3 lines or ~28 characters per line.
18
+ - Dense forms inside — show one control.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `title` * | `string \| string[]` | | Display words. String splits on spaces; pass an array to control lines. |
25
+ | `outline` | `'first' \| 'last' \| 'none' \| 'all' \| 'muted-first'` | `'first'` | Which word renders as stroked outline type (muted-first = grey instead of stroked). |
26
+ | `caption` | `string[]` | | 1–3 short instruction lines, e.g. ["Pick a color", "Drag or type a value"]. |
27
+ | `action` | `ReactNode` | | A control in the top-right corner, such as a Docs link. Use it instead of making the whole card clickable when the card holds a live demo. |
28
+ | `bordered` | `boolean` | `true for the surface variant` | Set false for tiles without a frame. |
29
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'lg'` | Squircle corner radius (token or px). |
30
+ | `children` | `ReactNode` | | The live demo, centred. |
31
+
32
+ ## Examples
33
+
34
+ ### Gallery tile
35
+
36
+ ```tsx
37
+ <PosterCard title="Switch" caption={['Turn things on and off', 'Tap a switch']}>
38
+ <Switch checked={on} onCheckedChange={setOn} />
39
+ </PosterCard>
40
+ ```
41
+
42
+ ### Gallery grid
43
+
44
+ ```tsx
45
+ <div style={{ display: 'grid', gap: 12, gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))' }}>
46
+ <PosterCard title="Segmented Control" outline="muted-first" caption={['Pick one option', 'Tap to switch']}>…</PosterCard>
47
+ <PosterCard title="Number Input" outline="muted-first" caption={['Pick a number']}>…</PosterCard>
48
+ </div>
49
+ ```
50
+
51
+ ## Rules
52
+ - Title and caption always sit top-left; the demo goes below. No background patterns.
53
+ - Type scales with the card width (container queries) — never set font-size on the words.
54
+ - Captions are instructions in plain words: "Tap a star", not "Interactive rating component".
55
+
56
+ ## DOM contract (for agents operating the page)
57
+
58
+ - Selector: `[data-sw="poster-card"]`
59
+ - How to operate: aria-label holds the title. The demo inside is a normal component.
60
+
61
+ Related: `card`
@@ -0,0 +1,92 @@
1
+ # Preferences
2
+
3
+ > Applies user preferences (theme, reduced motion, contrast, density, font size) as data-* attributes on <html>, saves them to localStorage and a cookie, and ships a ready-made settings panel.
4
+
5
+ Category: foundation · Status: beta · Slug: `preferences`
6
+
7
+ ```tsx
8
+ import { PreferencesProvider, PreferencesPanel, usePreferences, PreferencesScript, readPreferencesCookie, getPreferenceAttributes } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - An appearance/accessibility settings page or menu.
13
+ - Any app that should remember theme, motion, contrast, density or text size between visits (SSR-safe with the cookie).
14
+
15
+ ## Avoid
16
+ - Setting `SwProvider theme` while PreferencesProvider manages the theme — they would both write html[data-theme]. Leave SwProvider at its default, or pass `manageTheme={false}`.
17
+ - Reading localStorage yourself for these settings. Use `usePreferences()`.
18
+ - Building your own toggles for these. Use `<PreferencesPanel>` (or `usePreferences().setPreference`).
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `PreferencesProvider.defaultValue` | `Partial<PreferenceValues>` | | Starting values; pass the cookie value read on the server to avoid a flash. |
25
+ | `PreferencesProvider.value / onValueChange` | `PreferenceValues / (v) => void` | | Controlled preferences. |
26
+ | `PreferencesProvider.storage` | `'local' \| 'cookie' \| 'both' \| 'none'` | `'both'` | Where choices are saved (all access is try/catch guarded). |
27
+ | `PreferencesProvider.storageKey` | `string` | `'sw-preferences'` | localStorage key and cookie name. |
28
+ | `PreferencesProvider.manageTheme` | `boolean` | `true` | Write html[data-theme] (system removes it, exactly like SwProvider). |
29
+ | `PreferenceValues` | `{ theme: 'light'\|'dark'\|'system'; motion: 'system'\|'reduce'\|'full'; contrast: 'system'\|'more'\|'normal'; density: 'compact'\|'comfortable'\|'spacious'; fontSize: 'sm'\|'md'\|'lg' }` | | Defaults: system, system, system, comfortable, md. |
30
+ | `usePreferences()` | `{ preferences, resolved, setPreference(key, value), setPreferences(partial), reset() }` | | `resolved` says what system means right now (theme, motion, contrast). |
31
+ | `PreferencesPanel.show` | `PreferenceKey[]` | `all five` | Rows to show, in order. |
32
+ | `PreferencesPanel.resettable` | `boolean` | `true` | Show "Reset to defaults". |
33
+ | `PreferencesScript` | `{ storageKey?, nonce? }` | | Inline <head> script that applies saved values before first paint. |
34
+ | `readPreferencesCookie(cookieHeader, key?) / getPreferenceAttributes(prefs)` | `functions` | | Server helpers: read the cookie, then spread the attributes onto <html>. |
35
+
36
+ ## Examples
37
+
38
+ ### App root + settings page
39
+
40
+ ```tsx
41
+ <SwProvider>
42
+ <PreferencesProvider>
43
+ <App />
44
+ </PreferencesProvider>
45
+ </SwProvider>
46
+
47
+ function AppearanceSettings() {
48
+ return <PreferencesPanel />
49
+ }
50
+ ```
51
+
52
+ ### Read a preference
53
+
54
+ ```tsx
55
+ function Sidebar() {
56
+ const { preferences, setPreference } = usePreferences()
57
+ return <Switch label="Compact" checked={preferences.density === 'compact'}
58
+ onCheckedChange={(on) => setPreference('density', on ? 'compact' : 'comfortable')} />
59
+ }
60
+ ```
61
+
62
+ ### Server rendering
63
+
64
+ ```tsx
65
+ const prefs = readPreferencesCookie(request.headers.get('cookie'))
66
+ <html {...getPreferenceAttributes(prefs)}>
67
+ <head><PreferencesScript /></head>
68
+ <body><PreferencesProvider defaultValue={prefs}>…</PreferencesProvider></body>
69
+ </html>
70
+ ```
71
+
72
+ ## Rules
73
+ - Mount one PreferencesProvider near the root (inside SwProvider).
74
+ - Style with the attributes: `[data-density="compact"] .row { … }`, or use `var(--sw-density)` (0.85 / 1 / 1.2). Reduced motion and more contrast are applied to SW3 components for you.
75
+ - motion also drives motion/react (MotionConfig reducedMotion).
76
+
77
+ ## Accessibility
78
+ - PreferencesPanel is a labelled group of SegmentedControls (radiogroups) and Switches.
79
+ - Respect the OS by default: system values follow prefers-color-scheme, prefers-reduced-motion and prefers-contrast live.
80
+
81
+ ## DOM contract (for agents operating the page)
82
+
83
+ - Selector: `[data-sw="preferences-panel"]`
84
+ - `html[data-theme]`: 'light' | 'dark' (absent = system)
85
+ - `html[data-motion]`: 'reduce' | 'full' (resolved)
86
+ - `html[data-contrast]`: 'more' | 'normal' (resolved)
87
+ - `html[data-density]`: 'compact' | 'comfortable' | 'spacious'
88
+ - `html[data-font-size]`: 'sm' | 'md' | 'lg'
89
+ - `data-key / data-value (rows)`: each [data-sw="preferences-item"] row
90
+ - How to operate: Agent bridge (on the panel): setPreference(key, value), setValue(partial), reset(). DOM: click the radios in each [data-sw="preferences-item"] row or toggle its switch.
91
+
92
+ Related: `provider`, `segmented-control`, `switch`
@@ -0,0 +1,63 @@
1
+ # Progress
2
+
3
+ > Task progress: a bar that fills as work completes (determinate) or slides while the amount is unknown (`value={null}`).
4
+
5
+ Category: display · Status: beta · Slug: `progress`
6
+
7
+ ```tsx
8
+ import { Progress } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Uploads, imports, agent runs with known steps.
13
+ - Work under way with unknown duration: `value={null}`.
14
+
15
+ ## Avoid
16
+ - A static quantity in a range — use Meter.
17
+ - Very short waits (<1s) — show nothing or a spinner on the button.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `value` * | `number \| null` | | How far along; null = indeterminate. |
24
+ | `min / max` | `number` | `0 / 100` | Range. |
25
+ | `label` | `ReactNode` | | What is happening ("Indexing docs"). |
26
+ | `showValue` | `boolean` | `true` | Formatted value at the right (hidden while indeterminate). |
27
+ | `formatOptions` | `Intl.NumberFormatOptions` | `{ style: 'percent' }` | Value format. |
28
+ | `locale` | `string` | | Formatting locale. |
29
+ | `getValueLabel` | `(value \| null, formatted) => string` | | Screen-reader text, e.g. "3 of 12 files". |
30
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Bar 4 / 6 / 10px. |
31
+
32
+ ## Examples
33
+
34
+ ### Determinate
35
+
36
+ ```tsx
37
+ <Progress label="Indexing docs" value={64} />
38
+ ```
39
+
40
+ ### Steps
41
+
42
+ ```tsx
43
+ <Progress label="Uploading" value={3} max={12} formatOptions={{ style: 'decimal' }}
44
+ getValueLabel={(v) => `${v} of 12 files`} />
45
+ ```
46
+
47
+ ### Indeterminate
48
+
49
+ ```tsx
50
+ <Progress label="Waiting for the agent" value={null} />
51
+ ```
52
+
53
+ ## Accessibility
54
+ - role="progressbar"; aria-valuenow is omitted while indeterminate; aria-busy until complete.
55
+
56
+ ## DOM contract (for agents operating the page)
57
+
58
+ - Selector: `[data-sw="progress"]`
59
+ - `data-state`: loading | indeterminate | complete
60
+ - `aria-valuenow`: current value
61
+ - How to operate: Read-only. Agent bridge state: value, min, max, state.
62
+
63
+ Related: `meter`
@@ -0,0 +1,47 @@
1
+ # SwProvider
2
+
3
+ > Sets the theme and motion defaults for all SW3 components. Wrap the app once.
4
+
5
+ Category: foundation · Status: stable · Slug: `provider`
6
+
7
+ ```tsx
8
+ import { SwProvider } from '@peerproblem/sw3-ui'
9
+ import '@peerproblem/sw3-ui/styles.css'
10
+ ```
11
+
12
+ ## When to use
13
+ - Once, at the root of every app that uses @peerproblem/sw3-ui.
14
+
15
+ ## Avoid
16
+ - Nesting several providers. Use one at the root.
17
+
18
+ ## Props
19
+
20
+ | Prop | Type | Default | Description |
21
+ | --- | --- | --- | --- |
22
+ | `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Sets data-theme on <html>. |
23
+ | `reducedMotion` | `'user' \| 'always' \| 'never'` | `'user'` | Follows the OS reduce-motion setting by default. |
24
+
25
+ ## Examples
26
+
27
+ ### App root
28
+
29
+ ```tsx
30
+ import { SwProvider } from '@peerproblem/sw3-ui'
31
+ import '@peerproblem/sw3-ui/styles.css'
32
+
33
+ export function App() {
34
+ return (
35
+ <SwProvider theme="system">
36
+ <main className="sw-root">{/* ... */}</main>
37
+ </SwProvider>
38
+ )
39
+ }
40
+ ```
41
+
42
+ ## Rules
43
+ - Add className="sw-root" on the page wrapper (or <body class="sw-body">) to get canvas background and Geist type.
44
+
45
+ ## DOM contract (for agents operating the page)
46
+
47
+ - Selector: `html[data-theme]`
@@ -0,0 +1,91 @@
1
+ # RadioGroup / Radio
2
+
3
+ > One choice out of a few, all visible: radio dots, or card rows with icons (`variant="card"`). Arrow keys move and check; submits natively with `name`.
4
+
5
+ Category: selection · Status: beta · Slug: `radio`
6
+
7
+ ```tsx
8
+ import { RadioGroup, Radio } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Choosing exactly one of 2–6 options where seeing all of them helps.
13
+ - Form choices with a short description per option.
14
+ - A list of modes or sections in a side panel or settings page: `variant="card"` with icons.
15
+
16
+ ## Avoid
17
+ - Many options — use Select.
18
+ - Picking an item to open (a project, a run) — use Listbox.
19
+ - A view switcher — use SegmentedControl or Tabs.
20
+ - Independent options — use Checkbox.
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Default | Description |
25
+ | --- | --- | --- | --- |
26
+ | `value` | `string \| null` | | Checked value (controlled). null checks none. |
27
+ | `defaultValue` | `string \| null` | `null` | Initial value. |
28
+ | `onValueChange` | `(value: string) => void` | | Called on click or arrow key. |
29
+ | `items` | `{ value, label, description?, icon?, disabled? }[]` | | Shorthand: one Radio per item. |
30
+ | `variant` | `'default' \| 'card'` | `'default'` | card: rows with an optional icon and no dot; a squircle fill marks hover and the checked row. |
31
+ | `columns` | `1 \| 2 \| 3 \| 4` | `1` | Card columns once the container is at least 35rem wide. |
32
+ | `radius` | `RadiusValue` | `'md'` | Corner radius of card rows. |
33
+ | `name` | `string` | | Form field name; submits the checked value. |
34
+ | `loop` | `boolean` | `true` | Arrow keys wrap around. |
35
+ | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout and arrow keys. |
36
+ | `disabled / readOnly / required / invalid` | `boolean` | | States. |
37
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Circle 16 / 18 / 22px. |
38
+ | `aria-label` | `string` | | Names the group when there is no Field/Label. |
39
+ | `Radio.value` * | `string` | | Value of this option. |
40
+ | `Radio.label / description` | `ReactNode` | | Clickable text and a muted line. |
41
+ | `Radio.icon` | `IconName \| ReactNode` | | Leading 18px icon in card rows, e.g. 'user', 'clock'. |
42
+ | `Radio.disabled` | `boolean` | | Skip this option. |
43
+
44
+ ## Examples
45
+
46
+ ### Compound
47
+
48
+ ```tsx
49
+ <RadioGroup aria-label="Run mode" name="mode" defaultValue="auto">
50
+ <Radio value="auto" label="Autonomous" description="The agent runs every step." />
51
+ <Radio value="review" label="Review each step" />
52
+ <Radio value="dry" label="Dry run" disabled />
53
+ </RadioGroup>
54
+ ```
55
+
56
+ ### Options in a foldable side panel
57
+
58
+ ```tsx
59
+ <Accordion size="sm" multiple defaultValue={['view']}>
60
+ <AccordionItem value="view">
61
+ <AccordionTrigger>View</AccordionTrigger>
62
+ <AccordionPanel>
63
+ <RadioGroup variant="card" aria-label="Section" value={section} onValueChange={setSection}>
64
+ <Radio value="deliveries" icon="upload" label="Deliveries" />
65
+ <Radio value="agents" icon="user" label="Agents & keys" />
66
+ <Radio value="log" icon="clock" label="Access log" description="Last 30 days" />
67
+ </RadioGroup>
68
+ </AccordionPanel>
69
+ </AccordionItem>
70
+ </Accordion>
71
+ ```
72
+
73
+ ### Items in a Field
74
+
75
+ ```tsx
76
+ <Field label="Region" required>
77
+ <RadioGroup items={[{ value: 'eu', label: 'Europe' }, { value: 'us', label: 'United States' }]} />
78
+ </Field>
79
+ ```
80
+
81
+ ## Accessibility
82
+ - role="radiogroup" with role="radio" buttons; one tab stop on the checked (or first) radio; Arrow keys move and check, skipping disabled.
83
+
84
+ ## DOM contract (for agents operating the page)
85
+
86
+ - Selector: `[data-sw="radio-group"]`
87
+ - `aria-checked`: on each [data-sw="radio"]
88
+ - `data-value`: value of each radio
89
+ - How to operate: Click the [data-sw="radio"] whose label matches. Agent bridge: setValue(value) / select(value); items = options.
90
+
91
+ Related: `segmented-control`, `listbox`, `checkbox`
@@ -0,0 +1,66 @@
1
+ # Rating
2
+
3
+ > Star rating: a radio group of scores with hover preview, half steps, keyboard, and a read-only mode that shows any fraction.
4
+
5
+ Category: inputs · Status: beta · Slug: `rating`
6
+
7
+ ```tsx
8
+ import { Rating } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Rating an answer, run or product (1–5).
13
+ - Showing an average score: `readOnly value={4.3}`.
14
+
15
+ ## Avoid
16
+ - Binary feedback — use two Toggles (thumbs up/down).
17
+ - More than 10 stars — use Slider.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `value` | `number \| null` | | Controlled score; null = unrated. |
24
+ | `defaultValue` | `number \| null` | `null` | Initial score. |
25
+ | `onValueChange` | `(value: number \| null) => void` | | Called on click or arrow key. |
26
+ | `max` | `number` | `5` | Number of stars. |
27
+ | `step` | `1 \| 0.5` | `1` | 0.5 allows half stars. |
28
+ | `deselectable` | `boolean` | `false` | Pressing the checked star clears it. |
29
+ | `readOnly` | `boolean` | `false` | Image of the score (role="img"); fractions show. |
30
+ | `disabled / required / loop` | `boolean` | | States; loop wraps arrow keys. |
31
+ | `name` | `string` | | Submits the score. |
32
+ | `getValueLabel` | `(value, max) => string` | | Name of each score. Default "3 stars". |
33
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Stars 18 / 24 / 32px. |
34
+ | `aria-label` | `string` | | Name of the group. |
35
+
36
+ ## Examples
37
+
38
+ ### Rate an answer
39
+
40
+ ```tsx
41
+ <Rating aria-label="Rate this answer" value={score} onValueChange={setScore} deselectable />
42
+ ```
43
+
44
+ ### Half stars
45
+
46
+ ```tsx
47
+ <Rating aria-label="Quality" step={0.5} defaultValue={3.5} />
48
+ ```
49
+
50
+ ### Average
51
+
52
+ ```tsx
53
+ <Rating aria-label="Average rating" readOnly value={4.3} size="sm" />
54
+ ```
55
+
56
+ ## Accessibility
57
+ - role="radiogroup" with one role="radio" per score (two per star with halves); one tab stop; Arrow keys move and check; Space checks (or clears when deselectable).
58
+
59
+ ## DOM contract (for agents operating the page)
60
+
61
+ - Selector: `[data-sw="rating"]`
62
+ - `aria-checked`: on the chosen [data-score] radio
63
+ - `data-state`: full | partial | empty on each [data-sw="rating-item"]
64
+ - How to operate: Click the button with data-score="N". Agent bridge: setValue(n | null), clear().
65
+
66
+ Related: `slider`, `toggle`
@@ -0,0 +1,61 @@
1
+ # useReorder
2
+
3
+ > The headless drag-and-drop and keyboard reordering behind Listbox and DashboardGrid. Use it for your own sortable rows, chips or columns.
4
+
5
+ Category: hooks · Status: beta · Slug: `reorder`
6
+
7
+ ```tsx
8
+ import { useReorder, moveItem, applyOrder } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A custom reorderable layout that Listbox or DashboardGrid does not cover.
13
+
14
+ ## Avoid
15
+ - Moving items between containers or into groups. This handles reordering within one list.
16
+ - Reimplementing it with HTML5 drag events, which have no keyboard support or announcements.
17
+
18
+ ## Props
19
+
20
+ | Prop | Type | Default | Description |
21
+ | --- | --- | --- | --- |
22
+ | `ids` * | `string[]` | | Item ids in their current order. |
23
+ | `onReorder` * | `(ids, { id, from, to }) => void` | | New order after a drop or a keyboard move. |
24
+ | `orientation` | `'vertical' \| 'horizontal' \| 'grid'` | `'vertical'` | Stacked rows, one row, or wrapping tiles. |
25
+ | `getLabel` | `(id) => string` | | Name used in announcements and the drag preview. |
26
+ | `returns` | `object` | | getContainerProps(), getItemProps(id, { dragFromItem }), getHandleProps(id), moveBy(id, delta), moveTo(id, index), dropIndicator, overlay, dragId, liftedId. |
27
+
28
+ ## Examples
29
+
30
+ ### Sortable chips
31
+
32
+ ```tsx
33
+ const r = useReorder({ ids: tags.map((t) => t.id), orientation: 'horizontal', onReorder: (ids) => setTags(applyOrder(tags, ids, (t) => t.id)), getLabel: (id) => id })
34
+
35
+ <div {...r.getContainerProps()} style={{ position: 'relative', display: 'flex', gap: 6 }}>
36
+ {tags.map((t) => (
37
+ <span key={t.id} {...r.getItemProps(t.id)}>
38
+ <button {...r.getHandleProps(t.id)}><Icon name="grip" /></button>{t.label}
39
+ </span>
40
+ ))}
41
+ {r.dropIndicator}
42
+ {r.overlay}
43
+ </div>
44
+ ```
45
+
46
+ ## Rules
47
+ - Items stay in place while dragging. The source dims to 0.4, a preview follows the pointer, and a 2px line marks the drop point.
48
+ - A drag starts after 5px of movement. Touch drags start only from the handle, so pages still scroll.
49
+ - After a drop, flash the item (built in) and update optimistically.
50
+
51
+ ## Accessibility
52
+ - Handles: Space or Enter lifts, the arrows move, Space or Enter drops, Escape cancels. Every step is announced in a polite live region with the item name and position.
53
+
54
+ ## DOM contract (for agents operating the page)
55
+
56
+ - Selector: `[data-reorder-root]`
57
+ - `data-dragging`: on the item being dragged
58
+ - `data-lifted`: on a keyboard-lifted item
59
+ - `data-flash`: for 700ms after a drop
60
+
61
+ Related: `listbox`, `dashboard-grid`
@@ -0,0 +1,87 @@
1
+ # Resizable
2
+
3
+ > Panel groups split by draggable, keyboard-operable handles, with min/max, collapsible panels and saved layouts.
4
+
5
+ Category: layout · Status: beta · Slug: `resizable`
6
+
7
+ ```tsx
8
+ import { Resizable, ResizablePanel, ResizableHandle } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - IDE-style layouts: file tree | editor | preview, editor above terminal.
13
+ - Letting people trade space between a list and its detail view.
14
+
15
+ ## Avoid
16
+ - Phone-first layouts — stack the panes instead (or use orientation="vertical").
17
+ - Decorative splits that nobody needs to resize — use a CSS grid.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Side by side or stacked. |
24
+ | `layout` | `number[]` | | Panel sizes in percent, in order. Controlled. |
25
+ | `defaultLayout` | `number[]` | | Initial sizes (otherwise each panel's defaultSize). |
26
+ | `onLayoutChange` | `(layout: number[]) => void` | | Every drag frame and key press. |
27
+ | `onLayoutCommit` | `(layout: number[]) => void` | | Once an interaction ends. Save here. |
28
+ | `autoSaveId` | `string` | | Persist the layout to localStorage under this key and restore it on mount. |
29
+ | `step` | `number` | `5` | Arrow-key step in percent. |
30
+ | `largeStep` | `number` | `20` | Shift+Arrow step in percent. |
31
+ | `disabled` | `boolean` | `false` | Freeze every handle. |
32
+ | `framed` | `boolean` | `true` | Own 1px squircle frame; panels are clipped to it. Set false on nested groups or inside a framed surface. |
33
+ | `radius` | `RadiusToken \| number` | `'md'` | Frame radius. |
34
+ | `ResizablePanel.id` | `string` | | Stable id (aria-controls, agent actions). |
35
+ | `ResizablePanel.defaultSize` | `number` | | Starting size in percent; panels without one share the rest. |
36
+ | `ResizablePanel.minSize` | `number` | `0` | Minimum percent while open. |
37
+ | `ResizablePanel.maxSize` | `number` | `100` | Maximum percent. |
38
+ | `ResizablePanel.collapsible` | `boolean` | `false` | Can collapse to collapsedSize (drag past halfway below min, Enter or double-click the handle). |
39
+ | `ResizablePanel.collapsedSize` | `number` | `0` | Size when collapsed. At 0 its content is inert. |
40
+ | `ResizableHandle.aria-label` | `string` | | Names the handle, e.g. "Resize sidebar". |
41
+ | `ResizableHandle.disabled` | `boolean` | | Freeze this handle. |
42
+ | `ResizableHandle.withGrip` | `boolean` | `true` | Show the small grip. |
43
+
44
+ ## Examples
45
+
46
+ ### Sidebar | editor | preview, saved
47
+
48
+ ```tsx
49
+ <Resizable autoSaveId="editor-layout">
50
+ <ResizablePanel id="files" defaultSize={22} minSize={14} collapsible>…</ResizablePanel>
51
+ <ResizableHandle aria-label="Resize file list" />
52
+ <ResizablePanel id="editor" minSize={30}>…</ResizablePanel>
53
+ <ResizableHandle aria-label="Resize preview" />
54
+ <ResizablePanel id="preview" defaultSize={30} minSize={20}>…</ResizablePanel>
55
+ </Resizable>
56
+ ```
57
+
58
+ ### Editor above terminal
59
+
60
+ ```tsx
61
+ <Resizable orientation="vertical" style={{ height: 220 }}>
62
+ <ResizablePanel defaultSize={70}>…</ResizablePanel>
63
+ <ResizableHandle aria-label="Resize terminal" />
64
+ <ResizablePanel minSize={15} collapsible>…</ResizablePanel>
65
+ </Resizable>
66
+ ```
67
+
68
+ ## Rules
69
+ - Panels and handles must be direct children of <Resizable> (no fragments or wrappers).
70
+ - The group is framed by default — do not wrap it in a Card. Nested groups take framed={false}.
71
+ - Keep panel content transparent (no opaque pane backgrounds); the group supplies the surface.
72
+ - Horizontal groups are as tall as their content. Vertical groups need a height — size it to the content (≈180–240px), not a tall empty pane.
73
+ - Name every handle with aria-label.
74
+
75
+ ## Accessibility
76
+ - Handles are APG window splitters: focusable role="separator" with aria-valuenow (size of the panel before), aria-valuemin/max and aria-controls.
77
+ - Arrow keys along the axis move by step (Shift = largeStep), Home/End go to the limits, Enter collapses/restores a collapsible neighbour.
78
+
79
+ ## DOM contract (for agents operating the page)
80
+
81
+ - Selector: `[data-sw="resizable"]`
82
+ - `aria-valuenow`: on each [data-sw="resizable-handle"]: percent size of the panel before it
83
+ - `data-size`: rounded percent on each [data-sw="resizable-panel"]
84
+ - `data-collapsed`: on collapsed panels
85
+ - How to operate: Focus a [data-sw="resizable-handle"] and press arrow keys, or drag it. Agent bridge: setSizes(number[]), collapse(panelId), expand(panelId); state = { layout, orientation, panels }.
86
+
87
+ Related: `scroll-area`
@@ -0,0 +1,49 @@
1
+ # ScatterChart
2
+
3
+ > Correlation between two numeric fields, optional size field. Built on Unovis VisScatter.
4
+
5
+ Category: charts · Status: beta · Slug: `scatter-chart`
6
+
7
+ ```tsx
8
+ import { ScatterChart, ChartCard } from '@peerproblem/sw3-ui/charts'
9
+ ```
10
+
11
+ ## When to use
12
+ - Relationship between two measures.
13
+
14
+ ## Avoid
15
+ - Fewer than ~10 points — use a table.
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ | --- | --- | --- | --- |
21
+ | `data` * | `D[]` | | |
22
+ | `x` * | `keyof D` | | Numeric x field. |
23
+ | `y` * | `keyof D` | | Numeric y field. |
24
+ | `size` | `keyof D` | | Numeric field for point size. |
25
+ | `color` | `string` | | Point color. Default --sw-chart-1. |
26
+ | `height` | `number` | `240` | |
27
+
28
+ ## Examples
29
+
30
+ ### Latency vs cost
31
+
32
+ ```tsx
33
+ <ChartCard title="Latency vs cost">
34
+ <ScatterChart aria-label="Faster models cost more" data={models} x="latency" y="cost" size="calls" />
35
+ </ChartCard>
36
+ ```
37
+
38
+ ## Rules
39
+ - Wrap the chart in <ChartCard> and give the card a title.
40
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
41
+ - Use the default palette order; color 1 (blue) is the primary series.
42
+ - Max 5 series per chart. Do not use dual y-axes.
43
+
44
+ ## DOM contract (for agents operating the page)
45
+
46
+ - Selector: `[data-sw="chart"]`
47
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
48
+ - `aria-label`: the summary
49
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.