@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,109 @@
|
|
|
1
|
+
# Button
|
|
2
|
+
|
|
3
|
+
> A squircle button with press motion. Ink, app-brandable accent and quiet variants.
|
|
4
|
+
|
|
5
|
+
Category: actions · Status: stable · Slug: `button`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Button, ArrowIcon, Icon, Tooltip } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Any action the user triggers.
|
|
13
|
+
- Pairs of hero CTAs: `size="xl"` primary + accent side by side.
|
|
14
|
+
- Navigation styled as a button: pass `href`.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- More than one `accent` button in the same view — accent is the single most important action.
|
|
18
|
+
- Icon-only buttons without `aria-label`.
|
|
19
|
+
- Custom border-radius CSS — use `radius`, so the squircle stays consistent.
|
|
20
|
+
|
|
21
|
+
## Props
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `size` | `'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Heights 20 / 28 / 32 / 40 / 52 / 80px. Use 2xs for row actions and xs for header and toolbar controls. Ghost icon buttons at these sizes use a muted icon that turns ink on hover. xl is the poster-scale hero CTA. |
|
|
26
|
+
| `variant` | `'primary' \| 'accent' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | primary = ink fill, accent = app accent fill (ink by default), secondary = muted fill, outline = framed, ghost = text only. |
|
|
27
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `per size: xs / sm / md / lg` | Squircle corner radius (token or px). |
|
|
28
|
+
| `smoothing` | `'none' \| 'soft' \| 'max' \| number` | `'soft' (0.6)` | Corner smoothing from 0 to 1. SW3 uses 0.6 by default. |
|
|
29
|
+
| `leading` | `ReactNode` | | Icon before the label. |
|
|
30
|
+
| `trailing` | `ReactNode` | | Icon after the label. Use <ArrowIcon/> for forward actions. |
|
|
31
|
+
| `iconOnly` | `boolean` | `false` | Opt into a square layout for one icon passed through `leading` or `trailing`. Supply an accessible name. Visible children and `fullWidth` use the regular layout. |
|
|
32
|
+
| `loading` | `boolean` | `false` | Shows a spinner and disables the button. |
|
|
33
|
+
| `fullWidth` | `boolean` | `false` | Stretch to the container width. |
|
|
34
|
+
| `href` | `string` | | Render as an <a> link with button styling. |
|
|
35
|
+
| `data-sw-confirm` | `presence attribute` | | Require app confirmation before agent activation. |
|
|
36
|
+
| `...rest` | `HTMLMotionProps<"button">` | | Any button or motion prop (onClick, disabled, type, whileHover…). |
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
40
|
+
### Variants
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
<Button>Save</Button>
|
|
44
|
+
<Button variant="secondary">Cancel</Button>
|
|
45
|
+
<Button variant="outline">Preview</Button>
|
|
46
|
+
<Button variant="ghost">Skip</Button>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Hero CTA pair
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
<div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
|
|
53
|
+
<Button size="xl" href="/docs" trailing={<ArrowIcon />}>Read the Docs</Button>
|
|
54
|
+
<Button size="xl" variant="outline" onClick={copyPrompt}>Copy prompt</Button>
|
|
55
|
+
</div>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Brand accent
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
<div className="brand-accent">
|
|
62
|
+
{/* Set the app’s accent tokens on this wrapper. See the Color guide. */}
|
|
63
|
+
<Button variant="accent">Publish</Button>
|
|
64
|
+
</div>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Loading
|
|
68
|
+
|
|
69
|
+
```tsx
|
|
70
|
+
<Button loading>Deploying</Button>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Text with an icon
|
|
74
|
+
|
|
75
|
+
```tsx
|
|
76
|
+
<Button variant="secondary" leading={<Icon name="copy" />} onClick={copyLink}>Copy link</Button>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Compact copy action
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
<Tooltip content="Copy code">
|
|
83
|
+
<Button size="sm" variant="ghost" iconOnly aria-label="Copy code" leading={<Icon name="copy" />} onClick={copyCode} />
|
|
84
|
+
</Tooltip>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Rules
|
|
88
|
+
- Dense icon actions are `<Button size="2xs" variant="ghost" iconOnly aria-label>` (in rows) or `size="xs"` (in headers and toolbars), wrapped in a Tooltip. In a Listbox, pass row actions as data and let it render them. Do not hand-roll small icon buttons.
|
|
89
|
+
- Labels are verbs in sentence case ("Save changes", not "SAVE").
|
|
90
|
+
- One accent button per view; everything else primary/secondary/ghost.
|
|
91
|
+
- Use `secondary` for a quiet fill without a frame. Set `--sw-button-secondary-bg` on an ancestor when the default fill is too close to the surrounding surface.
|
|
92
|
+
- Choose the label for the context. Use text for primary, unfamiliar or ambiguous actions. Add an icon when it helps users recognize the action. Use an icon alone for familiar utility actions with clear context, such as copying a code block.
|
|
93
|
+
- Pair icon-only actions with an accessible name and a tooltip. For copy actions, keep the name stable, show a check icon after success, and announce the result through a status region.
|
|
94
|
+
|
|
95
|
+
## Accessibility
|
|
96
|
+
- Renders a native <button type="button"> (or <a> with href).
|
|
97
|
+
- Focus shows a 2px accent squircle ring outside the shape.
|
|
98
|
+
|
|
99
|
+
## DOM contract (for agents operating the page)
|
|
100
|
+
|
|
101
|
+
- Selector: `[data-sw="button"]`
|
|
102
|
+
- `data-variant`: variant name
|
|
103
|
+
- `data-size`: size
|
|
104
|
+
- `data-icon-only`: present for square icon buttons
|
|
105
|
+
- `data-loading`: present while loading
|
|
106
|
+
- `disabled`: native disabled attribute
|
|
107
|
+
- How to operate: Click the button by its accessible name, including aria-label on icon-only actions.
|
|
108
|
+
|
|
109
|
+
Related: `card`
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Calendar
|
|
2
|
+
|
|
3
|
+
> An inline month grid for picking one date, several dates or a range, with full grid keyboard support. Values are ISO date strings.
|
|
4
|
+
|
|
5
|
+
Category: dates · Status: beta · Slug: `calendar`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Calendar, CalendarHeader, CalendarPrevious, CalendarHeading, CalendarNext, CalendarGrid } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Dates that should stay visible on the page: a booking flow, a schedule, an availability view.
|
|
13
|
+
- Picking several separate days (`mode="multiple"`) or a span (`mode="range"`, often with `months={2}`).
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- A form field for a single date → use DatePicker (typing + popup) or DateInput (typing only).
|
|
17
|
+
- Passing Date objects → values are ISO strings like "2026-11-14"; use the exported helpers (addDays, formatDate…) for arithmetic.
|
|
18
|
+
- Disabling days you only want to mark as booked → use `unavailable`/`isDateUnavailable` so they stay focusable and readable.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `mode` | `'single' \| 'multiple' \| 'range'` | `'single'` | How many dates it selects. |
|
|
25
|
+
| `value` | `string \| null · string[] · [start, end] \| null` | | Selected value for the mode: an ISO date, a sorted list, or an inclusive [start, end] range. Pass to control. |
|
|
26
|
+
| `defaultValue` | `same as value` | | Initial value when uncontrolled. |
|
|
27
|
+
| `onValueChange` | `(value) => void` | | Runs when a day is picked. A range reports once both ends are chosen. |
|
|
28
|
+
| `month` | `string ("YYYY-MM")` | | First month shown. Pass to control it. |
|
|
29
|
+
| `defaultMonth` | `string ("YYYY-MM")` | | Initial month. Defaults to the selection, else today. |
|
|
30
|
+
| `onMonthChange` | `(month: string) => void` | | Runs when Previous/Next or keyboard paging changes the month. |
|
|
31
|
+
| `min` | `string (ISO date)` | | Earliest date that can be picked, e.g. "2026-11-01". |
|
|
32
|
+
| `max` | `string (ISO date)` | | Latest date that can be picked. |
|
|
33
|
+
| `isDateUnavailable` | `(date: string) => boolean` | | Return true for dates that cannot be picked (booked days). They stay focusable so keyboard users hear them. |
|
|
34
|
+
| `unavailable` | `DateMatcher \| DateMatcher[]` | | The same as data: ISO dates, `{ from, to }`, `{ before }`, `{ after }`, `{ weekday: [0, 6] }` (weekends) or a function. |
|
|
35
|
+
| `locale` | `string` | `page lang, then browser` | BCP 47 locale for names, order and week start. |
|
|
36
|
+
| `weekStartsOn` | `number (0–6)` | `locale's (Intl weekInfo)` | First day of the week, 0 = Sunday. |
|
|
37
|
+
| `months` | `number` | `1` | Months side by side, each its own grid. They wrap on narrow screens. |
|
|
38
|
+
| `weekdayFormat` | `'narrow' \| 'short' \| 'long'` | `'short'` | Weekday header style. |
|
|
39
|
+
| `fixedWeeks` | `boolean` | `false` | Always render six weeks so the height never changes. |
|
|
40
|
+
| `showOutsideDays` | `boolean` | `true with 1 month, false with more` | Show neighbouring months' days at the edges. |
|
|
41
|
+
| `disabled` | `boolean` | `false` | Nothing can be picked or focused. |
|
|
42
|
+
| `readOnly` | `boolean` | `false` | Days can be focused but not picked. |
|
|
43
|
+
| `deselectable` | `boolean` | `false` | Single mode: pressing the selected day clears it. |
|
|
44
|
+
| `minDays` | `number` | | Range: fewest days in a range, ends included. |
|
|
45
|
+
| `maxDays` | `number` | | Range: most days in a range, ends included. |
|
|
46
|
+
| `allowUnavailable` | `boolean` | `false` | Range: allow a range to cross unavailable days. |
|
|
47
|
+
| `today` | `string (ISO date)` | | Override today (marker + starting month). Useful for tests and demos. |
|
|
48
|
+
| `timeZone` | `string` | `browser's` | IANA zone that decides what day today is. |
|
|
49
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Day cell size 32 / 38 / 44px. |
|
|
50
|
+
| `framed` | `boolean` | `true` | Draw its own squircle frame. Pass false only when it already sits on a surface (a popup, a Card it shares with other content). |
|
|
51
|
+
| `autoFocus` | `boolean` | `false` | Focus the tab-stop day on mount. |
|
|
52
|
+
| `renderDay` | `(day: CalendarDayState) => ReactNode` | | Custom content inside each day button (e.g. a price or a dot). Keep the day number visible. |
|
|
53
|
+
| `children` | `ReactNode` | | Custom layout from parts: <CalendarHeader/> (or <CalendarPrevious/>, <CalendarHeading/>, <CalendarNext/>) and <CalendarGrid offset={n}/>. Empty = default layout. |
|
|
54
|
+
| `CalendarGrid.offset` | `number` | `0` | Which of the shown months this grid renders, from 0. |
|
|
55
|
+
| `CalendarPrevious / CalendarNext aria-label` | `string` | | Override "Previous month" / "Next month". |
|
|
56
|
+
|
|
57
|
+
## Examples
|
|
58
|
+
|
|
59
|
+
### Single date
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
const [date, setDate] = useState<string | null>('2026-11-14')
|
|
63
|
+
<Calendar value={date} onValueChange={setDate} />
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Range over two months, weekends unavailable
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
<Calendar
|
|
70
|
+
mode="range"
|
|
71
|
+
months={2}
|
|
72
|
+
defaultValue={['2026-11-16', '2026-11-20']}
|
|
73
|
+
min="2026-11-01"
|
|
74
|
+
unavailable={{ weekday: [0, 6] }}
|
|
75
|
+
onValueChange={(range) => console.log(range)} // ['2026-11-16', '2026-11-20'] | null
|
|
76
|
+
/>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Several days, Monday first
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
<Card padding="md">
|
|
83
|
+
<Text>Pick review days</Text>
|
|
84
|
+
<Calendar mode="multiple" weekStartsOn={1} defaultValue={['2026-11-03', '2026-11-10']} framed={false} />
|
|
85
|
+
</Card>
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Rules
|
|
89
|
+
- All values are ISO strings ("YYYY-MM-DD", months "YYYY-MM"). Never pass Date objects.
|
|
90
|
+
- Selection is the one accent fill; do not add other accent elements next to it.
|
|
91
|
+
- Framed by default — do not wrap it in a Card just to frame it (that double-frames it). Use `framed={false}` inside a popup or a shared surface.
|
|
92
|
+
- Today is marked by a dot only (normal weight). Days have an even 2px gutter and concentric squircle corners (host radius − inset).
|
|
93
|
+
- For booked or blocked days use `unavailable` (still focusable); `min`/`max` for hard bounds.
|
|
94
|
+
|
|
95
|
+
## Accessibility
|
|
96
|
+
- Each month is a role="grid" table named by its month; weekday headers carry full names; each day is a gridcell (aria-selected) holding a button named by its full date, with aria-current="date" on today.
|
|
97
|
+
- One Tab stop: the selected day, else today, else the first available day.
|
|
98
|
+
- Keys: arrows move by day/week, Home/End to week start/end, PageUp/PageDown by month, Shift+PageUp/PageDown by year, Enter/Space selects, Escape cancels an unfinished range.
|
|
99
|
+
- The heading is aria-live so month changes are announced.
|
|
100
|
+
|
|
101
|
+
## DOM contract (for agents operating the page)
|
|
102
|
+
|
|
103
|
+
- Selector: `[data-sw="calendar"]`
|
|
104
|
+
- `data-mode`: single | multiple | range
|
|
105
|
+
- `[data-sw="calendar-day"][data-value]`: each day's ISO date
|
|
106
|
+
- `data-selected / aria-selected (on the gridcell)`: selected days (every day of a range)
|
|
107
|
+
- `data-range-start / data-range-middle / data-range-end`: range parts
|
|
108
|
+
- `data-today`: today
|
|
109
|
+
- `data-unavailable / data-disabled / data-outside`: unpickable / out of bounds / neighbouring month
|
|
110
|
+
- `[data-sw="calendar-grid"][data-month]`: the month a grid shows ("YYYY-MM")
|
|
111
|
+
- `data-range-pending`: on the root while a range start is chosen but not its end
|
|
112
|
+
- How to operate: Click `[data-sw="calendar-day"][data-value="2026-11-14"]` to pick it (range: click start, then end). Use `[data-sw="calendar-next"]` / `calendar-previous` to change month. Agent bridge: setValue(iso | "start/end" | "a,b,c"), select(iso), clear(), setMonth("YYYY-MM"), previous(), next(); state = { mode, value, month, min, max, disabled, readOnly, rangeStart }.
|
|
113
|
+
|
|
114
|
+
Related: `date-picker`, `date-input`
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Canvas
|
|
2
|
+
|
|
3
|
+
> A small design artboard of rectangles, ellipses and display text: click to select, drag to move, corner handles to resize, with a built-in layers / X·Y·W·H / fill / opacity inspector.
|
|
4
|
+
|
|
5
|
+
Category: extras · Status: beta · Slug: `canvas`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Canvas } from '@peerproblem/sw3-ui/extras'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Letting people arrange a few blocks on a poster, card or slide layout and nudge them precisely.
|
|
13
|
+
- Demonstrating or prototyping direct manipulation (select, move, resize, inspect) that an agent can also drive.
|
|
14
|
+
- Editing a small, fixed set of shapes whose position, size, fill and opacity are the whole model.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- A full vector editor (paths, groups, rotation, undo history) — Canvas is a fixed-set layout board; build on a dedicated editor.
|
|
18
|
+
- Charts or data plots — use the chart components in @peerproblem/sw3-ui/charts.
|
|
19
|
+
- Image cropping or framing — use ImageCropper.
|
|
20
|
+
- Arranging list items in order — use a sortable list, not free positioning.
|
|
21
|
+
- More than ~12 shapes: every shape is a tab stop and a layers row.
|
|
22
|
+
|
|
23
|
+
## Props
|
|
24
|
+
|
|
25
|
+
| Prop | Type | Default | Description |
|
|
26
|
+
| --- | --- | --- | --- |
|
|
27
|
+
| `shapes` | `CanvasShape[]` | | Shapes, bottom to top: { id, type: 'rect' | 'ellipse' | 'text', name, x, y, w, h, fill: 'ink' | 'gray' | 'white' | 'hatch', opacity: 10–100, text? }. Controlled. |
|
|
28
|
+
| `defaultShapes` | `CanvasShape[]` | `[]` | Initial shapes when uncontrolled. |
|
|
29
|
+
| `onShapesChange` | `(shapes: CanvasShape[]) => void` | | Every change: each drag frame, arrow key and inspector edit. |
|
|
30
|
+
| `onShapesCommit` | `(shapes: CanvasShape[]) => void` | | Once an interaction ends (pointer up, key, field blur/Enter, swatch, slider release). Save here. |
|
|
31
|
+
| `selectedId` | `string \| null` | | Id of the selected shape, null for none. Controlled. |
|
|
32
|
+
| `defaultSelectedId` | `string \| null` | `null` | Initially selected shape. |
|
|
33
|
+
| `onSelectedIdChange` | `(id: string \| null) => void` | | Selection changed (click, focus, layers row, Escape, empty-board click). |
|
|
34
|
+
| `width` | `number` | `560` | Artboard width in units. The board fills the container width and keeps width:height. |
|
|
35
|
+
| `height` | `number` | `320` | Artboard height in units. |
|
|
36
|
+
| `inspector` | `boolean` | `true` | Show LAYERS, X/Y/W/H, FILL and OPACITY under the board. |
|
|
37
|
+
| `framed` | `boolean` | `true` | Draw an outer surface around the artboard and inspector. Set false inside a card or preview that already supplies the surface. The artboard keeps its own boundary. |
|
|
38
|
+
| `snap` | `number` | `1` | Drag and resize snap, in units. |
|
|
39
|
+
| `radius` | `RadiusToken \| number` | `'lg'` | Outer squircle frame radius. |
|
|
40
|
+
| `aria-label` | `string` | | Names the canvas, e.g. "Poster canvas". |
|
|
41
|
+
|
|
42
|
+
## Examples
|
|
43
|
+
|
|
44
|
+
### Poster layout, ellipse selected
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
<Canvas
|
|
48
|
+
aria-label="Poster canvas"
|
|
49
|
+
width={460}
|
|
50
|
+
height={312}
|
|
51
|
+
defaultSelectedId="ellipse"
|
|
52
|
+
defaultShapes={[
|
|
53
|
+
{ id: 'rect', type: 'rect', name: 'Rectangle', x: 24, y: 24, w: 240, h: 168, fill: 'hatch', opacity: 100 },
|
|
54
|
+
{ id: 'ellipse', type: 'ellipse', name: 'Ellipse', x: 300, y: 56, w: 136, h: 136, fill: 'white', opacity: 100 },
|
|
55
|
+
{ id: 'text', type: 'text', name: 'Text', x: 120, y: 222, w: 220, h: 56, fill: 'white', opacity: 100, text: 'Behaviors.' },
|
|
56
|
+
]}
|
|
57
|
+
/>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Embedded artboard, saved on commit
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
const [shapes, setShapes] = useState(initialShapes)
|
|
64
|
+
const [selected, setSelected] = useState<string | null>(null)
|
|
65
|
+
|
|
66
|
+
<Canvas
|
|
67
|
+
aria-label="Card layout"
|
|
68
|
+
shapes={shapes}
|
|
69
|
+
onShapesChange={setShapes}
|
|
70
|
+
onShapesCommit={(s) => save(s)}
|
|
71
|
+
selectedId={selected}
|
|
72
|
+
onSelectedIdChange={setSelected}
|
|
73
|
+
inspector={false}
|
|
74
|
+
framed={false}
|
|
75
|
+
/>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Rules
|
|
79
|
+
- Give every shape a short, unique, human name ("Logo", "Headline") — it is the layer label, the shape's accessible name and the key agents use.
|
|
80
|
+
- Positions are artboard units, not pixels: the board scales to its container. Pick width/height for the aspect ratio you want and size shapes in those units.
|
|
81
|
+
- Shapes always stay inside the artboard (min 8 × 8); do not pass coordinates you expect to overflow.
|
|
82
|
+
- Fills are a fixed monochrome set (ink, gray, white, hatch) that flips with the theme — do not try to colour shapes with the accent.
|
|
83
|
+
- Use framed={false} inside an existing card or gallery preview. Keep the artboard boundary visible so users can see the editable area.
|
|
84
|
+
- Use onShapesCommit (not onShapesChange) to save or sync — onShapesChange fires on every drag frame.
|
|
85
|
+
|
|
86
|
+
## Accessibility
|
|
87
|
+
- Each shape is a focusable role="button" with aria-roledescription="shape", aria-label "<Name>. Arrow keys move it." and aria-pressed = selected.
|
|
88
|
+
- Focusing a shape selects it. Arrow keys move it 1 unit, Shift+Arrow 10. Escape deselects. Delete/Backspace do nothing (shapes cannot be removed here).
|
|
89
|
+
- Resize from the keyboard with the W / H number fields (Arrow Up/Down, Shift = ×10). The corner handles are pointer-only.
|
|
90
|
+
- LAYERS is a vertical ToggleGroup (one tab stop, Up/Down to move, Space/Enter to select). FILL swatches are an icon ToggleGroup with aria-labels Ink / Gray / White / Hatch.
|
|
91
|
+
- With nothing selected the X/Y/W/H, FILL and OPACITY controls are disabled and empty, so a screen reader never edits a hidden shape.
|
|
92
|
+
- Selection is shown by a dashed box plus corner handles and a solid layers row — never colour alone.
|
|
93
|
+
|
|
94
|
+
## DOM contract (for agents operating the page)
|
|
95
|
+
|
|
96
|
+
- Selector: `[data-sw="canvas"]`
|
|
97
|
+
- `data-selected`: on the root: id of the selected shape (absent when none)
|
|
98
|
+
- `data-framed`: on the root when the outer surface is shown
|
|
99
|
+
- `data-dragging`: on the root while a move or resize drag is in progress
|
|
100
|
+
- `aria-pressed`: on each .sw-canvas__shape[role="button"]: true when selected
|
|
101
|
+
- `data-id / data-shape / data-fill`: on each shape: its id, rect|ellipse|text and fill
|
|
102
|
+
- `style left/top/width/height`: each shape's box in percent of the artboard (units = percent × width or height / 100)
|
|
103
|
+
- How to operate: Click a [aria-roledescription="shape"] to select it and press Arrow keys to move it; type into the inputs labelled "X position", "Y position", "Width", "Height"; press a FILL toggle (aria-label Ink/Gray/White/Hatch); use the Opacity slider. Agent bridge: kind "canvas", state = { shapes, selected (name), selectedId, width, height }; actions select(nameOrId | null), update(nameOrId, { x, y, w, h, fill, opacity, text, name }), move(nameOrId, dx, dy). Values are clamped into the artboard.
|
|
104
|
+
|
|
105
|
+
Related: `toggle`, `number-input`, `slider`, `resizable`, `image-cropper`
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Card
|
|
2
|
+
|
|
3
|
+
> A squircle surface with a 1px frame. Plain by design: no background patterns, no hover movement.
|
|
4
|
+
|
|
5
|
+
Category: layout · Status: stable · Slug: `card`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Grouping related content.
|
|
13
|
+
- Dashboard tiles and settings sections.
|
|
14
|
+
- A clickable tile: set `interactive` and `onClick`.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Cards inside cards more than one level deep.
|
|
18
|
+
- Shadows — the system uses 1px frames, not elevation.
|
|
19
|
+
- Setting border-radius in CSS (breaks the squircle).
|
|
20
|
+
- Background decoration (grids, dots, hatching) or hover lift/scale on cards — keep surfaces quiet.
|
|
21
|
+
- Fixed or min heights — let a card be as tall as its content.
|
|
22
|
+
|
|
23
|
+
## Props
|
|
24
|
+
|
|
25
|
+
| Prop | Type | Default | Description |
|
|
26
|
+
| --- | --- | --- | --- |
|
|
27
|
+
| `title` | `ReactNode` | | Turns on the panel layout: a 40px header bar (6px inset + 28px trigger), then toolbar, body and footer. Use it for every dashboard tile, side panel and list box. |
|
|
28
|
+
| `count / icon / actions` | `ReactNode` | | Header bar pieces. Actions are xs/2xs ghost Buttons, a Menu trigger, or `Pagination variant="compact"`. |
|
|
29
|
+
| `toolbar` | `ReactNode` | | A row under the header, usually `<Toolbar variant="plain" size="sm">` with a ToolbarInput and a sort Menu. |
|
|
30
|
+
| `footer` | `ReactNode` | | A pinned row under the body, with a line above it. |
|
|
31
|
+
| `collapsible / open / defaultOpen / onOpenChange` | `boolean` | | The header folds the card down to its header bar. The count stays visible. |
|
|
32
|
+
| `framed` | `boolean` | | Default: true, or false inside a container that already draws the frame (a joined DashboardGrid, an Accordion, another panel Card). |
|
|
33
|
+
| `padding (panel layout)` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'sm'` | Body padding of 0, 12, 16 or 24px. The header inset follows it, so the title and body text share one line. Use 'none' for lists that reach the edges. |
|
|
34
|
+
| `variant` | `'surface' \| 'muted' \| 'inverse' \| 'ghost'` | `'surface'` | surface = white + frame, muted = grey well, inverse = ink, ghost = no fill. |
|
|
35
|
+
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 16 / 24 / 40px. |
|
|
36
|
+
| `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'lg' (20px)` | Squircle corner radius (token or px). |
|
|
37
|
+
| `smoothing` | `'none' \| 'soft' \| 'max' \| number` | `'soft' (0.6)` | Corner smoothing from 0 to 1. SW3 uses 0.6 by default. |
|
|
38
|
+
| `bordered` | `boolean` | `true (false for ghost)` | Draw the 1px frame. |
|
|
39
|
+
| `href / target / rel` | `anchor attributes` | | Give the card a native link without intercepting nested controls. |
|
|
40
|
+
| `interactive` | `boolean` | `false` | Whole card clickable: pointer cursor, frame darkens on hover, focus ring. The card never moves. Clicks on controls or on any SW3 component inside it (including its empty space) stay with that component; drags never click. |
|
|
41
|
+
| `clipContent` | `boolean` | `false` | Clip children to the squircle (edge-to-edge images, maps). |
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
### Basic
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
<Card>
|
|
49
|
+
<CardHeader>
|
|
50
|
+
<CardTitle>Weekly digest</CardTitle>
|
|
51
|
+
<CardDescription>A summary of your week, every Monday.</CardDescription>
|
|
52
|
+
</CardHeader>
|
|
53
|
+
<CardFooter>
|
|
54
|
+
<Button size="sm">Subscribe</Button>
|
|
55
|
+
</CardFooter>
|
|
56
|
+
</Card>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Hero poster
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
<Card padding="lg" radius="xl">
|
|
63
|
+
<Display size="md">Behaviors, <Outline>not</Outline> widgets.</Display>
|
|
64
|
+
</Card>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Rules
|
|
68
|
+
- Dashboard tiles and side panels are Cards with `title`. Do not stack framed Cards inside a panel Card: they unframe themselves, so group with an Accordion instead.
|
|
69
|
+
- Use `canvas` (page) behind cards and `background` inside them; never put a card on a white page without the canvas.
|
|
70
|
+
- Keep 12–16px gaps between cards in a grid.
|
|
71
|
+
|
|
72
|
+
## DOM contract (for agents operating the page)
|
|
73
|
+
|
|
74
|
+
- Selector: `[data-sw="card"]`
|
|
75
|
+
- `data-variant`: variant
|
|
76
|
+
- `data-interactive`: present when clickable
|
|
77
|
+
|
|
78
|
+
Related: `poster-card`, `chart-card`
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Carousel
|
|
2
|
+
|
|
3
|
+
> Slides on native scroll-snap with Previous / Next, page dots, keyboard paging and optional autoplay with a pause control.
|
|
4
|
+
|
|
5
|
+
Category: display · Status: beta · Slug: `carousel`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Carousel, CarouselItem, CarouselViewport, CarouselControls, CarouselPrevious, CarouselNext, CarouselIndicators, CarouselPlayToggle } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Showcasing a handful of templates, screenshots or testimonials in limited space.
|
|
13
|
+
- Several cards per page on desktop (slidesPerPage).
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Hiding important content in later slides — most people never see them.
|
|
17
|
+
- Autoplay for anything people need to read carefully.
|
|
18
|
+
- Long lists — use a grid or a horizontal ScrollArea.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `aria-label` * | `string` | | Names the carousel, e.g. "Featured templates". |
|
|
25
|
+
| `page` | `number` | | Current page, from 1. Controlled. |
|
|
26
|
+
| `defaultPage` | `number` | `1` | Starting page. |
|
|
27
|
+
| `onPageChange` | `(page: number) => void` | | Called when the page changes (buttons, dots, keys, swipe, autoplay). |
|
|
28
|
+
| `slidesPerPage` | `number` | `1` | Slides visible per page; Next moves this many. |
|
|
29
|
+
| `loop` | `boolean` | `false` | Next on the last page wraps to the first. |
|
|
30
|
+
| `playing` | `boolean` | | Autoplay. Controlled. |
|
|
31
|
+
| `defaultPlaying` | `boolean` | `false` | Start rotating (skipped when the user prefers reduced motion). Shows a play/pause button. |
|
|
32
|
+
| `onPlayingChange` | `(playing: boolean) => void` | | Rotation started or stopped (keyboard focus and manual paging stop it). |
|
|
33
|
+
| `interval` | `number` | `5000` | ms per page while rotating. |
|
|
34
|
+
| `controls` | `boolean` | `true` | Default layout: Previous / Next buttons. |
|
|
35
|
+
| `indicators` | `boolean` | `true` | Default layout: page dots (a tablist). |
|
|
36
|
+
| `gap` | `number` | `12` | Gap between slides in px. |
|
|
37
|
+
| `labels` | `{ previous?; next?; play?; pause?; page?(n); slide?(n, total) }` | | Translate control and slide labels. |
|
|
38
|
+
| `CarouselItem` | `HTMLAttributes<HTMLDivElement>` | | One slide. Direct child of Carousel (default layout) or of CarouselViewport. |
|
|
39
|
+
| `Parts` | `CarouselViewport, CarouselControls, CarouselPlayToggle, CarouselIndicators, CarouselPrevious, CarouselNext` | | For your own layout, pass parts instead of slides: any child that is not a CarouselItem switches Carousel to custom layout. The parts read state from the Carousel, so they work in any order and wrapper. |
|
|
40
|
+
|
|
41
|
+
## Anatomy
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
Carousel root: state, keyboard, autoplay, agent binding
|
|
45
|
+
├─ CarouselViewport scroll-snap area (focusable)
|
|
46
|
+
│ └─ CarouselItem × n one slide
|
|
47
|
+
└─ CarouselControls the row under the slides
|
|
48
|
+
├─ CarouselPlayToggle when it can autoplay
|
|
49
|
+
├─ CarouselIndicators page dots (tablist)
|
|
50
|
+
├─ CarouselPrevious
|
|
51
|
+
└─ CarouselNext
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Built from: `useSquircle (round buttons)`, `Icon`.
|
|
55
|
+
|
|
56
|
+
## Examples
|
|
57
|
+
|
|
58
|
+
### Custom layout from parts
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
<Carousel aria-label="Release highlights" loop>
|
|
62
|
+
<CarouselControls>
|
|
63
|
+
<Heading as="h3" size="sm">Highlights</Heading>
|
|
64
|
+
<span style={{ marginLeft: 'auto', display: 'flex', gap: 6 }}>
|
|
65
|
+
<CarouselPrevious />
|
|
66
|
+
<CarouselNext />
|
|
67
|
+
</span>
|
|
68
|
+
</CarouselControls>
|
|
69
|
+
<CarouselViewport>
|
|
70
|
+
{releases.map((r) => <CarouselItem key={r.id}><Card>{r.title}</Card></CarouselItem>)}
|
|
71
|
+
</CarouselViewport>
|
|
72
|
+
<CarouselIndicators />
|
|
73
|
+
</Carousel>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Templates, two per page
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
<Carousel aria-label="Templates" slidesPerPage={2}>
|
|
80
|
+
{templates.map((t) => (
|
|
81
|
+
<CarouselItem key={t.id}><Card>{t.name}</Card></CarouselItem>
|
|
82
|
+
))}
|
|
83
|
+
</Carousel>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Autoplay with pause
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
<Carousel aria-label="Release highlights" defaultPlaying interval={6000} loop>
|
|
90
|
+
<CarouselItem>…</CarouselItem>
|
|
91
|
+
<CarouselItem>…</CarouselItem>
|
|
92
|
+
<CarouselItem>…</CarouselItem>
|
|
93
|
+
</Carousel>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Rules
|
|
97
|
+
- 3–8 slides. Each slide makes sense on its own.
|
|
98
|
+
- Autoplay only with loop, and only for non-essential content.
|
|
99
|
+
|
|
100
|
+
## Accessibility
|
|
101
|
+
- APG carousel: region with aria-roledescription="carousel"; slides are groups labelled "n of N"; off-page slides are inert.
|
|
102
|
+
- Arrow keys page in the focused viewport, Home/End go to the ends; dots are a tablist with arrow-key roving.
|
|
103
|
+
- Rotation stops when keyboard focus enters, pauses on hover, and the live region is polite only while not rotating.
|
|
104
|
+
|
|
105
|
+
## DOM contract (for agents operating the page)
|
|
106
|
+
|
|
107
|
+
- Selector: `[data-sw="carousel"]`
|
|
108
|
+
- `data-active`: on [data-sw="carousel-item"] slides of the current page
|
|
109
|
+
- `aria-selected`: on the current [data-sw="carousel-indicator"]
|
|
110
|
+
- `data-playing`: on the root while rotating
|
|
111
|
+
- How to operate: Click [data-sw="carousel-next"] / [data-sw="carousel-previous"] or [data-sw="carousel-indicator"][data-page="N"]. Agent bridge: setValue(page), setPage(page), next(), prev(), play(), pause(); state = { page, pageCount, playing }.
|
|
112
|
+
|
|
113
|
+
Related: `scroll-area`, `pagination`
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# ChartCard
|
|
2
|
+
|
|
3
|
+
> A Card laid out for a chart: title, description, headline value, actions, chart, legend.
|
|
4
|
+
|
|
5
|
+
Category: charts · Status: beta · Slug: `chart-card`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { ChartCard, BarChart } from '@peerproblem/sw3-ui/charts'
|
|
9
|
+
import { SegmentedControl } from '@peerproblem/sw3-ui'
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## When to use
|
|
13
|
+
- Every chart on a dashboard.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Putting two charts in one ChartCard.
|
|
17
|
+
|
|
18
|
+
## Props
|
|
19
|
+
|
|
20
|
+
| Prop | Type | Default | Description |
|
|
21
|
+
| --- | --- | --- | --- |
|
|
22
|
+
| `title` * | `ReactNode` | | |
|
|
23
|
+
| `description` | `ReactNode` | | Time range or unit. |
|
|
24
|
+
| `value` | `ReactNode` | | Headline number, top right. |
|
|
25
|
+
| `actions` | `ReactNode` | | e.g. a SegmentedControl for the range. |
|
|
26
|
+
| `legend` | `Array<{ key; label?; color? }>` | | Legend under the chart, same order as series. |
|
|
27
|
+
| `...Card props` | `CardProps` | | variant, pattern, radius… |
|
|
28
|
+
|
|
29
|
+
## Examples
|
|
30
|
+
|
|
31
|
+
### With range switch
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
<ChartCard title="Revenue" description="USD" actions={<SegmentedControl size="sm" aria-label="Range" value={r} onValueChange={setR} options={ranges} />}>
|
|
35
|
+
<BarChart aria-label="Revenue by month" data={rows} x="month" series={[{ key: 'revenue' }]} />
|
|
36
|
+
</ChartCard>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## DOM contract (for agents operating the page)
|
|
40
|
+
|
|
41
|
+
- Selector: `[data-sw="chart-card"]`
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# ChartSurface
|
|
2
|
+
|
|
3
|
+
> Themes any raw @unovis/react chart with SW3 tokens — for Sankey, Graph, Timeline, Chord, Heatmap, maps and every other Unovis type.
|
|
4
|
+
|
|
5
|
+
Category: charts · Status: beta · Slug: `chart-surface`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { ChartSurface, ChartCard } from '@peerproblem/sw3-ui/charts'
|
|
9
|
+
import { VisSingleContainer, VisSankey } from '@unovis/react'
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## When to use
|
|
13
|
+
- A chart type without an SW3 wrapper (see the chart gallery on the docs site, #/charts).
|
|
14
|
+
- Composing several Unovis components (crosshair, brush, annotations, plot bands) in one container.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Line, area, bar, scatter, donut, sparkline or treemap charts — use the wrappers.
|
|
18
|
+
- Hex colours inside the chart — use var(--sw-chart-1…8).
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `aria-label` * | `string` | | The takeaway in one sentence. Agents and screen readers cannot read SVG. |
|
|
25
|
+
| `name` | `string` | `'custom'` | Rendered as data-chart, e.g. "sankey" or a gallery slug. |
|
|
26
|
+
| `role` | `'figure' \| 'img'` | `'figure'` | figure keeps legends, buttons and brushes inside operable; img for a static picture. |
|
|
27
|
+
| `children` * | `ReactNode` | | Unovis containers and components. |
|
|
28
|
+
|
|
29
|
+
## Examples
|
|
30
|
+
|
|
31
|
+
### Sankey
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
<ChartCard title="Energy flow" description="Quadrillion Btu">
|
|
35
|
+
<ChartSurface name="sankey" aria-label="Most energy is lost as heat before end use">
|
|
36
|
+
<VisSingleContainer data={{ nodes, links }} height={420}>
|
|
37
|
+
<VisSankey label={(n) => n.label} />
|
|
38
|
+
</VisSingleContainer>
|
|
39
|
+
</ChartSurface>
|
|
40
|
+
</ChartCard>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Rules
|
|
44
|
+
- Wrap the chart in <ChartCard> and give the card a title.
|
|
45
|
+
- Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
|
|
46
|
+
- Use the default palette order; color 1 (blue) is the primary series.
|
|
47
|
+
- Max 5 series per chart. Do not use dual y-axes.
|
|
48
|
+
- When you adapt a chart gallery example, keep its interactions.
|
|
49
|
+
- Tooltip templates use the .sw-tt classes.
|
|
50
|
+
|
|
51
|
+
## DOM contract (for agents operating the page)
|
|
52
|
+
|
|
53
|
+
- Selector: `[data-sw="chart"]`
|
|
54
|
+
- `data-chart`: the name prop
|
|
55
|
+
- `aria-label`: the summary
|
|
56
|
+
- How to operate: Read aria-label for the meaning; legends and controls inside are regular buttons.
|