@peerproblem/sw3-ui 0.0.0-stage → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +109 -2
- package/agent/components/accordion.md +95 -0
- package/agent/components/action-square.md +106 -0
- package/agent/components/agent-bridge.md +87 -0
- package/agent/components/agent-console.md +123 -0
- package/agent/components/alert-dialog.md +82 -0
- package/agent/components/app-shell.md +105 -0
- package/agent/components/area-chart.md +56 -0
- package/agent/components/async-options.md +47 -0
- package/agent/components/autocomplete.md +69 -0
- package/agent/components/avatar.md +88 -0
- package/agent/components/badge.md +51 -0
- package/agent/components/bar-chart.md +56 -0
- package/agent/components/bar-list.md +49 -0
- package/agent/components/breadcrumbs.md +43 -0
- package/agent/components/button.md +109 -0
- package/agent/components/calendar.md +114 -0
- package/agent/components/canvas.md +105 -0
- package/agent/components/card.md +78 -0
- package/agent/components/carousel.md +113 -0
- package/agent/components/chart-card.md +41 -0
- package/agent/components/chart-surface.md +56 -0
- package/agent/components/checkbox.md +88 -0
- package/agent/components/citation-chip.md +61 -0
- package/agent/components/collapsible.md +69 -0
- package/agent/components/color-picker.md +82 -0
- package/agent/components/combobox.md +104 -0
- package/agent/components/command.md +92 -0
- package/agent/components/dashboard-grid.md +73 -0
- package/agent/components/date-input.md +87 -0
- package/agent/components/date-picker.md +122 -0
- package/agent/components/dialog.md +97 -0
- package/agent/components/donut-chart.md +50 -0
- package/agent/components/drawer.md +101 -0
- package/agent/components/empty-state.md +52 -0
- package/agent/components/field.md +80 -0
- package/agent/components/file-input.md +84 -0
- package/agent/components/hover-card.md +64 -0
- package/agent/components/image-cropper.md +77 -0
- package/agent/components/input.md +49 -0
- package/agent/components/label.md +53 -0
- package/agent/components/line-chart.md +60 -0
- package/agent/components/listbox.md +84 -0
- package/agent/components/map-view.md +104 -0
- package/agent/components/menu.md +117 -0
- package/agent/components/menubar.md +67 -0
- package/agent/components/meter.md +59 -0
- package/agent/components/navigation-menu.md +98 -0
- package/agent/components/number-input.md +81 -0
- package/agent/components/otp-input.md +67 -0
- package/agent/components/pagination.md +80 -0
- package/agent/components/password-input.md +67 -0
- package/agent/components/pill-button.md +116 -0
- package/agent/components/popover.md +85 -0
- package/agent/components/poster-card.md +61 -0
- package/agent/components/preferences.md +92 -0
- package/agent/components/progress.md +63 -0
- package/agent/components/provider.md +47 -0
- package/agent/components/radio.md +91 -0
- package/agent/components/rating.md +66 -0
- package/agent/components/reorder.md +61 -0
- package/agent/components/resizable.md +87 -0
- package/agent/components/scatter-chart.md +49 -0
- package/agent/components/scroll-area.md +81 -0
- package/agent/components/segmented-control.md +56 -0
- package/agent/components/select.md +130 -0
- package/agent/components/separator.md +60 -0
- package/agent/components/shortcuts.md +50 -0
- package/agent/components/sidebar-nav.md +68 -0
- package/agent/components/skeleton.md +58 -0
- package/agent/components/slider.md +79 -0
- package/agent/components/sparkline.md +39 -0
- package/agent/components/squircle.md +58 -0
- package/agent/components/stat.md +58 -0
- package/agent/components/switch.md +48 -0
- package/agent/components/table.md +58 -0
- package/agent/components/tabs.md +108 -0
- package/agent/components/textarea.md +68 -0
- package/agent/components/time-input.md +84 -0
- package/agent/components/timeline.md +91 -0
- package/agent/components/toast.md +85 -0
- package/agent/components/toggle.md +76 -0
- package/agent/components/token-input.md +66 -0
- package/agent/components/toolbar.md +76 -0
- package/agent/components/tooltip.md +83 -0
- package/agent/components/tracker.md +47 -0
- package/agent/components/tree.md +87 -0
- package/agent/components/treemap.md +72 -0
- package/agent/components/trend-chart.md +80 -0
- package/agent/components/trigger-menu.md +67 -0
- package/agent/components/typography.md +51 -0
- package/agent/components/waterfall.md +78 -0
- package/agent/components/week-schedule.md +113 -0
- package/agent/llms/actions-and-layout.txt +1749 -0
- package/agent/llms/agents.txt +505 -0
- package/agent/llms/charts.txt +778 -0
- package/agent/llms/dashboards.txt +457 -0
- package/agent/llms/extend.txt +132 -0
- package/agent/llms/extras.txt +527 -0
- package/agent/llms/forms.txt +2152 -0
- package/agent/llms/foundations.txt +674 -0
- package/agent/llms/hooks.txt +178 -0
- package/agent/llms/maps.txt +229 -0
- package/agent/llms/overlays-and-navigation.txt +1167 -0
- package/agent/llms-full.txt +8717 -0
- package/agent/llms.txt +145 -0
- package/agent/registry.json +11289 -0
- package/agent/tokens.md +66 -0
- package/dist/agent/index.d.ts +235 -0
- package/dist/agent/index.js +21 -0
- package/dist/card-Ipm-Cj5f.d.ts +490 -0
- package/dist/charts/index.d.ts +289 -0
- package/dist/charts/index.js +815 -0
- package/dist/check/cli.d.ts +1 -0
- package/dist/check/cli.js +48 -0
- package/dist/check/rendered.d.ts +11 -0
- package/dist/check/rendered.js +77 -0
- package/dist/check/source.d.ts +13 -0
- package/dist/check/source.js +182 -0
- package/dist/chunk-3DXBM65D.js +65 -0
- package/dist/chunk-3H5X4ZP6.js +55 -0
- package/dist/chunk-6XC4BC5C.js +92 -0
- package/dist/chunk-7H6TEAWD.js +507 -0
- package/dist/chunk-I63ZTJOI.js +1089 -0
- package/dist/chunk-JCIRUM4W.js +33 -0
- package/dist/chunk-LTBEHZ3P.js +25 -0
- package/dist/chunk-QDPPLO4U.js +60 -0
- package/dist/chunk-U2XFBPU4.js +56 -0
- package/dist/chunk-UY2WH5AY.js +681 -0
- package/dist/extras.d.ts +203 -0
- package/dist/extras.js +904 -0
- package/dist/icons-BJiGEAnU.d.ts +68 -0
- package/dist/index.d.ts +3737 -0
- package/dist/index.js +14477 -0
- package/dist/map/index.d.ts +115 -0
- package/dist/map/index.js +394 -0
- package/dist/meta/index.d.ts +3314 -0
- package/dist/meta/index.js +5106 -0
- package/dist/rules-1RIZ_JZr.d.ts +38 -0
- package/dist/styles.css +4037 -0
- package/dist/themes/calm.css +42 -0
- package/dist/themes/frost.css +40 -0
- package/package.json +142 -4
|
@@ -0,0 +1,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.
|