@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,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.