@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,527 @@
1
+ # SW3 UI SDK · Extras
2
+
3
+ > @peerproblem/sw3-ui/extras: PosterCard, ActionSquare, PillButton, Canvas, WeekSchedule. Use only when the request names the pattern.
4
+
5
+ Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
6
+ Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
7
+ Index of all topics and components: llms.txt.
8
+
9
+ ---
10
+
11
+ # Components
12
+
13
+ # PosterCard
14
+
15
+ > A gallery tile: tight display words (outlined + solid) top-left, a mono caption under them, and a live component below. Height follows content.
16
+
17
+ Category: extras · Status: stable · Slug: `poster-card`
18
+
19
+ ```tsx
20
+ import { PosterCard } from '@peerproblem/sw3-ui/extras'
21
+ ```
22
+
23
+ ## When to use
24
+ - Showcasing a component, feature or behavior in a grid.
25
+ - Landing-page galleries (3 columns ≥1280px, 2 ≥640px, 1 on phones).
26
+
27
+ ## Avoid
28
+ - Long titles — 1–2 short words. Hyphenate long words manually: ["Accor-", "dion"].
29
+ - Captions longer than 3 lines or ~28 characters per line.
30
+ - Dense forms inside — show one control.
31
+
32
+ ## Props
33
+
34
+ | Prop | Type | Default | Description |
35
+ | --- | --- | --- | --- |
36
+ | `title` * | `string \| string[]` | | Display words. String splits on spaces; pass an array to control lines. |
37
+ | `outline` | `'first' \| 'last' \| 'none' \| 'all' \| 'muted-first'` | `'first'` | Which word renders as stroked outline type (muted-first = grey instead of stroked). |
38
+ | `caption` | `string[]` | | 1–3 short instruction lines, e.g. ["Pick a color", "Drag or type a value"]. |
39
+ | `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. |
40
+ | `bordered` | `boolean` | `true for the surface variant` | Set false for tiles without a frame. |
41
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'lg'` | Squircle corner radius (token or px). |
42
+ | `children` | `ReactNode` | | The live demo, centred. |
43
+
44
+ ## Examples
45
+
46
+ ### Gallery tile
47
+
48
+ ```tsx
49
+ <PosterCard title="Switch" caption={['Turn things on and off', 'Tap a switch']}>
50
+ <Switch checked={on} onCheckedChange={setOn} />
51
+ </PosterCard>
52
+ ```
53
+
54
+ ### Gallery grid
55
+
56
+ ```tsx
57
+ <div style={{ display: 'grid', gap: 12, gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))' }}>
58
+ <PosterCard title="Segmented Control" outline="muted-first" caption={['Pick one option', 'Tap to switch']}>…</PosterCard>
59
+ <PosterCard title="Number Input" outline="muted-first" caption={['Pick a number']}>…</PosterCard>
60
+ </div>
61
+ ```
62
+
63
+ ## Rules
64
+ - Title and caption always sit top-left; the demo goes below. No background patterns.
65
+ - Type scales with the card width (container queries) — never set font-size on the words.
66
+ - Captions are instructions in plain words: "Tap a star", not "Interactive rating component".
67
+
68
+ ## DOM contract (for agents operating the page)
69
+
70
+ - Selector: `[data-sw="poster-card"]`
71
+ - How to operate: aria-label holds the title. The demo inside is a normal component.
72
+
73
+ Related: `card`
74
+
75
+ ---
76
+
77
+ # ActionSquare
78
+
79
+ > A text label paired with a squircle icon tile ("Learn more [+]", "Close [−]").
80
+
81
+ Category: extras · Status: beta · Slug: `action-square`
82
+
83
+ ```tsx
84
+ import { ActionSquare } from '@peerproblem/sw3-ui/extras'
85
+ ```
86
+
87
+ ## When to use
88
+ - A quiet secondary action pinned to the corner of media, a card or a sheet.
89
+ - Open/close pairs: "Learn more" (`corner`/`plus`) on the trigger, "Close" (`minus`, tone `ink`) inside the sheet.
90
+ - Inside another clickable surface: pass `decorative` so it renders a span and picks up the parent hover.
91
+
92
+ ## Avoid
93
+ - Primary CTAs — use Button (`primary` / `accent`).
94
+ - Long labels. Keep it 1–3 words; the tile carries the meaning.
95
+ - Nesting a non-decorative ActionSquare inside a button or link (invalid HTML).
96
+
97
+ ## Props
98
+
99
+ | Prop | Type | Default | Description |
100
+ | --- | --- | --- | --- |
101
+ | `label` * | `string` | | Visible text and the accessible name. |
102
+ | `icon` | `IconName` | `'corner'` | Icon in the tile: 'corner' | 'plus' | 'minus' | 'close' | 'expand' | 'arrow-up-right' | … |
103
+ | `tone` | `'light' \| 'ink' \| 'glass'` | `'light'` | light = pale tile · ink = solid dark tile · glass = translucent on photos/dark. |
104
+ | `size` | `'md' \| 'lg'` | `'md'` | 48px or 60px tile. |
105
+ | `iconFirst` | `boolean` | `false` | Tile before the label. |
106
+ | `hideLabel` | `boolean` | `false` | Tile only; label stays as the accessible name. |
107
+ | `decorative` | `boolean` | `false` | Render a non-interactive span for use inside another clickable element. |
108
+ | `radius / smoothing` | `RadiusValue / SmoothingValue` | `14 (md), 18 (lg) / soft` | Squircle of the tile. In a card corner, use card radius − inset (e.g. 24 − 16 = 8) so the corners nest. |
109
+
110
+ ## Examples
111
+
112
+ ### Corner action
113
+
114
+ ```tsx
115
+ <ActionSquare label="Learn more" icon="corner" onClick={() => setOpen(true)} />
116
+ ```
117
+
118
+ ### Close inside a sheet
119
+
120
+ ```tsx
121
+ <ActionSquare label="Close" icon="minus" tone="ink" size="lg" onClick={() => setOpen(false)} />
122
+ ```
123
+
124
+ ### Inside a clickable media card
125
+
126
+ ```tsx
127
+ <button className="media" onClick={open}>
128
+ <img src="/lens.png" alt="" />
129
+ <ActionSquare decorative label="Learn more" style={{ position: 'absolute', top: 16, right: 16 }} />
130
+ </button>
131
+ ```
132
+
133
+ ## Variants
134
+
135
+ Rendered as `data-<variant>` on `[data-sw="action-square"]`.
136
+
137
+ - `tone`: `light` | `ink` | `glass` (default `light`)
138
+ - `size`: `md` | `lg` (default `md`)
139
+
140
+ ## CSS variables
141
+
142
+ Set on any ancestor to adjust this component. Never target `.sw-*` selectors.
143
+
144
+ | Variable | Controls |
145
+ | --- | --- |
146
+ | `--sw-action-square-tile-size` | Tile width and height. |
147
+ | `--sw-action-square-tile-bg` | Tile fill. |
148
+ | `--sw-action-square-tile-border` | Tile 1px frame (light tone: --sw-frame; ink and glass: none). |
149
+ | `--sw-action-square-tile-bg-hover` | Tile fill on hover. |
150
+ | `--sw-action-square-tile-bg-active` | Tile fill while pressed. |
151
+ | `--sw-action-square-tile-fg` | Icon color. |
152
+ | `--sw-action-square-fg` | Label color. |
153
+ | `--sw-action-square-gap` | Space between label and tile. |
154
+ | `--sw-action-square-font-size` | Label size. |
155
+
156
+ ## Designs
157
+
158
+ Swap the whole look with `data-design` on <html> or any wrapper.
159
+
160
+ - `sdk`: Default. No attribute needed. Neutral tokens and Geist, with an optional app-defined brand accent.
161
+ - `calm`: import '@peerproblem/sw3-ui/themes/calm.css' + data-design="calm". Teal-grey ink, pale tiles, IBM Plex Sans.
162
+ - `frost`: import '@peerproblem/sw3-ui/themes/frost.css' + data-design="frost". Frosted fills that flip to solid on hover, Urbanist.
163
+
164
+ ## Rules
165
+ - Pick looks with `tone` and `size`. Do not write CSS that targets .sw-* class names.
166
+ - To adjust one place, set a `recipe.cssVars` variable on a wrapper: `.toolbar { --sw-pill-button-radius: 16px }`.
167
+ - To change a whole look, use `data-design` with a theme file instead of overriding many variables.
168
+ - Use tone `ink` for the action that closes or dismisses, `light` for the one that opens.
169
+
170
+ ## Accessibility
171
+ - The label is the accessible name; with `hideLabel` it is still read.
172
+ - Focus ring is a 2px accent outline around the whole row.
173
+
174
+ ## DOM contract (for agents operating the page)
175
+
176
+ - Selector: `[data-sw="action-square"]`
177
+ - `data-tone`: light | ink | glass
178
+ - `data-size`: md | lg
179
+ - `data-decorative`: present when it is a span inside another control
180
+ - How to operate: Click the element (not the tile) unless data-decorative is present — then click its clickable ancestor.
181
+
182
+ Related: `button`, `pill-button`
183
+
184
+ ---
185
+
186
+ # PillButton
187
+
188
+ > A fully rounded button with an optional leading icon ("Export", "View tasks").
189
+
190
+ Category: extras · Status: beta · Slug: `pill-button`
191
+
192
+ ```tsx
193
+ import { PillButton } from '@peerproblem/sw3-ui/extras'
194
+ ```
195
+
196
+ ## When to use
197
+ - Toolbars and action rows on dark surfaces (tone `night`).
198
+ - Toggles that reveal content: set `aria-expanded` and it keeps its hover fill while open.
199
+ - Navigation over imagery (tone `glass`, size `fluid`).
200
+ - File downloads: `href` + `download`.
201
+
202
+ ## Avoid
203
+ - Hero CTAs — use Button `xl`; PillButton is for secondary rows.
204
+ - Mixing tones in one row. One row, one tone.
205
+ - Glass on a plain white background — there is nothing to blur. Use `soft` instead.
206
+
207
+ ## Props
208
+
209
+ | Prop | Type | Default | Description |
210
+ | --- | --- | --- | --- |
211
+ | `children` * | `ReactNode` | | Label. |
212
+ | `icon` | `IconName \| ReactNode` | | Leading icon, e.g. 'import', 'note'. |
213
+ | `trailingIcon` | `IconName \| ReactNode` | | Trailing icon, e.g. 'chevron-down' for menus. |
214
+ | `tone` | `'night' \| 'ink' \| 'soft' \| 'glass'` | `'night'` | night = grey on near-black · ink = solid foreground · soft = muted fill · glass = 50% white + blur, flips to black on hover. |
215
+ | `size` | `'sm' \| 'md' \| 'lg' \| 'fluid'` | `'lg'` | 36 / 48 / 60px, or fluid 48→100px with the viewport. |
216
+ | `href` | `string` | | Render a link. |
217
+ | `download` | `boolean \| string` | | With href: download the file. |
218
+ | `aria-expanded / aria-pressed` | `boolean` | | Toggle state; keeps the hover fill while true. |
219
+
220
+ ## Examples
221
+
222
+ ### Toolbar on a dark card
223
+
224
+ ```tsx
225
+ const [showTasks, setShowTasks] = useState(false)
226
+
227
+ <div style={{ display: 'flex', gap: 6 }}>
228
+ <PillButton icon="import" href="/export.csv" download>Export</PillButton>
229
+ <PillButton icon="note" aria-expanded={showTasks} aria-controls="tasks" onClick={() => setShowTasks(!showTasks)}>
230
+ View tasks
231
+ </PillButton>
232
+ </div>
233
+ ```
234
+
235
+ ### Light surface
236
+
237
+ ```tsx
238
+ <PillButton tone="soft" size="md" icon="plus">Add filter</PillButton>
239
+ ```
240
+
241
+ ### Adjust one place
242
+
243
+ ```tsx
244
+ <div style={{ '--sw-pill-button-radius': '16px' } as React.CSSProperties}>
245
+ <PillButton>Squarer pill</PillButton>
246
+ </div>
247
+ ```
248
+
249
+ ## Variants
250
+
251
+ Rendered as `data-<variant>` on `[data-sw="pill-button"]`.
252
+
253
+ - `tone`: `night` | `ink` | `soft` | `glass` (default `night`)
254
+ - `size`: `sm` | `md` | `lg` | `fluid` (default `lg`)
255
+
256
+ ## CSS variables
257
+
258
+ Set on any ancestor to adjust this component. Never target `.sw-*` selectors.
259
+
260
+ | Variable | Controls |
261
+ | --- | --- |
262
+ | `--sw-pill-button-bg` | Fill. |
263
+ | `--sw-pill-button-bg-hover` | Fill on hover, and while aria-expanded / aria-pressed is true. |
264
+ | `--sw-pill-button-fg` | Text and icon color. |
265
+ | `--sw-pill-button-fg-hover` | Text color on hover / active. |
266
+ | `--sw-pill-button-height` | Height. |
267
+ | `--sw-pill-button-padding-x` | Horizontal padding. |
268
+ | `--sw-pill-button-radius` | Corner radius. 999px = full pill. |
269
+ | `--sw-pill-button-font-size` | Label size. |
270
+ | `--sw-pill-button-font-weight` | Label weight. |
271
+ | `--sw-pill-button-gap` | Space between icon and label. |
272
+ | `--sw-pill-button-blur` | Backdrop blur (5px on glass). |
273
+
274
+ ## Designs
275
+
276
+ Swap the whole look with `data-design` on <html> or any wrapper.
277
+
278
+ - `sdk`: Default. No attribute needed. Neutral tokens and Geist, with an optional app-defined brand accent.
279
+ - `calm`: import '@peerproblem/sw3-ui/themes/calm.css' + data-design="calm". Teal-grey ink, pale tiles, IBM Plex Sans.
280
+ - `frost`: import '@peerproblem/sw3-ui/themes/frost.css' + data-design="frost". Frosted fills that flip to solid on hover, Urbanist.
281
+
282
+ ## Rules
283
+ - Pick looks with `tone` and `size`. Do not write CSS that targets .sw-* class names.
284
+ - To adjust one place, set a `recipe.cssVars` variable on a wrapper: `.toolbar { --sw-pill-button-radius: 16px }`.
285
+ - To change a whole look, use `data-design` with a theme file instead of overriding many variables.
286
+ - Use 6–8px gaps between pills in a row.
287
+
288
+ ## Accessibility
289
+ - Toggles must set aria-expanded (disclosure) or aria-pressed (on/off).
290
+ - Icons are decorative; the label is the name.
291
+
292
+ ## DOM contract (for agents operating the page)
293
+
294
+ - Selector: `[data-sw="pill-button"]`
295
+ - `data-tone`: night | ink | soft | glass
296
+ - `data-size`: sm | md | lg | fluid
297
+ - `aria-expanded`: true while its panel is open
298
+ - `aria-pressed`: true while on
299
+ - How to operate: Click it. Read aria-expanded / aria-pressed for state.
300
+
301
+ Related: `button`
302
+
303
+ ---
304
+
305
+ # WeekSchedule
306
+
307
+ > A week board — day columns × hour rows with meeting, focus and away blocks you drag to move, drag by the bottom edge to resize, or nudge with arrow keys; shows the hours booked.
308
+
309
+ Category: extras · Status: beta · Slug: `week-schedule`
310
+
311
+ ```tsx
312
+ import { WeekSchedule } from '@peerproblem/sw3-ui/extras'
313
+ ```
314
+
315
+ ## When to use
316
+ - Planning a working week: placing meetings and focus blocks, seeing what is booked at a glance.
317
+ - Letting a person (or an agent) reschedule a handful of events by dragging or by keyboard.
318
+ - A compact, read-only "my week" view on a dashboard (readOnly, summary off).
319
+
320
+ ## Avoid
321
+ - Month views or picking a single date — use Calendar / DatePicker.
322
+ - Many overlapping events per slot (shared team calendars) — events in the same slot overlap here instead of splitting into lanes.
323
+ - Choosing one time — use TimeInput.
324
+ - Long ordered histories — use Timeline.
325
+
326
+ ## Props
327
+
328
+ | Prop | Type | Default | Description |
329
+ | --- | --- | --- | --- |
330
+ | `events` | `WeekEvent[]` | | Controlled events: { id, title, day (0-based into days), start, end (minutes from midnight), kind?: "meeting" | "focus" | "away" }. |
331
+ | `defaultEvents` | `WeekEvent[]` | `[]` | Initial events when uncontrolled. |
332
+ | `onEventsChange` | `(events: WeekEvent[]) => void` | | Every change: each drag frame, key press and agent action. |
333
+ | `onEventCommit` | `(event: WeekEvent, events: WeekEvent[]) => void` | | Once a move or resize ends (pointer up, key handled, agent action). Save here. |
334
+ | `onEventActivate` | `(event: WeekEvent) => void` | | Click without dragging, Enter or Space on an event — open its details. |
335
+ | `days` | `string[]` | `['Mon','Tue','Wed','Thu','Fri']` | Column labels, one column each. |
336
+ | `startHour` | `number` | `9` | First visible hour. |
337
+ | `endHour` | `number` | `17` | Hour the board ends at (exclusive). Events are clamped inside startHour–endHour. |
338
+ | `step` | `number` | `15` | Snap and arrow-key step in minutes; also the shortest event. |
339
+ | `hourHeight` | `number` | `60` | Pixels per hour row. |
340
+ | `hourFormat` | `'24h' \| '12h'` | | Controlled clock format. 24h shows "10:00–12:00"; 12h shows "10–12 PM". |
341
+ | `defaultHourFormat` | `'24h' \| '12h'` | `'24h'` | Initial clock format. |
342
+ | `onHourFormatChange` | `(format: '24h' \| '12h') => void` | | Clock switch changed. |
343
+ | `summary` | `boolean` | `true` | Show the big total of booked hours (away time is not counted). |
344
+ | `summaryLabel` | `string` | `'Hours booked'` | Mono label next to the total. |
345
+ | `clockToggle` | `boolean` | `true` | Show the 24h / 12h SegmentedControl in the footer. |
346
+ | `legend` | `boolean` | `true` | Show the meeting / focus / away legend in the footer. |
347
+ | `readOnly` | `boolean` | `false` | Events can be focused and activated but not moved or resized. |
348
+ | `radius` | `RadiusToken \| number` | `'lg'` | Frame squircle radius. |
349
+
350
+ ## Examples
351
+
352
+ ### Uncontrolled week, save on commit
353
+
354
+ ```tsx
355
+ <WeekSchedule
356
+ aria-label="This week"
357
+ defaultEvents={[
358
+ { id: 'standup', title: 'Standup', day: 0, start: 540, end: 570, kind: 'meeting' },
359
+ { id: 'focus', title: 'Focus time', day: 0, start: 600, end: 720, kind: 'focus' },
360
+ { id: 'flight', title: 'Flight to Berlin', day: 4, start: 840, end: 1020, kind: 'away' },
361
+ ]}
362
+ onEventCommit={(event, events) => save(events)}
363
+ />
364
+ ```
365
+
366
+ ### Controlled, 12h, Mon–Sun 8–20, no chrome
367
+
368
+ ```tsx
369
+ const [events, setEvents] = useState(initial)
370
+ <WeekSchedule
371
+ aria-label="Team week"
372
+ events={events}
373
+ onEventsChange={setEvents}
374
+ days={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
375
+ startHour={8}
376
+ endHour={20}
377
+ step={30}
378
+ hourHeight={44}
379
+ defaultHourFormat="12h"
380
+ summary={false}
381
+ clockToggle={false}
382
+ legend={false}
383
+ />
384
+ ```
385
+
386
+ ### Read-only, custom total label
387
+
388
+ ```tsx
389
+ <WeekSchedule aria-label="My week" readOnly summaryLabel="Hours in meetings" events={events} onEventActivate={(e) => openEvent(e.id)} />
390
+ ```
391
+
392
+ ## Rules
393
+ - Give it an aria-label ("This week", "Team week"); it is a labelled group.
394
+ - The board has its own squircle frame — do not wrap it in a Card.
395
+ - Times are minutes from midnight in the API and "HH:MM" strings in agent state/actions; days are 0-based indexes into `days`.
396
+ - Use kind for meaning: meeting (outlined), focus (solid), away (hatched, not counted as booked). Do not recolour events.
397
+ - Save in onEventCommit, not onEventsChange (which fires on every drag frame).
398
+ - Keep it to one week (≤ 7 columns). It fits day columns to its container and shows Previous/Next days when the whole week cannot fit. Left/Right on an event moves it across days and follows it into the next range.
399
+
400
+ ## Accessibility
401
+ - Each event is a focusable role="button" with aria-roledescription="event" and an aria-label with its title, time, day and kind, plus how to move it.
402
+ - Keys on a focused event: ArrowUp/ArrowDown move by step, ArrowLeft/ArrowRight move a day, Shift+ArrowUp/ArrowDown shorten/lengthen it, Enter/Space activate, Escape cancels a drag.
403
+ - Every committed move is announced in a polite live region ("Review, Wed 11:15–12:15.").
404
+ - Kinds are told apart by shape (outline / fill / hatch) and the legend. Keyboard focus shows an inset ring. Editable events show a resize grip on hover or focus.
405
+ - Day and hour labels are decorative (aria-hidden) because every event label already names its day and time.
406
+
407
+ ## DOM contract (for agents operating the page)
408
+
409
+ - Selector: `[data-sw="week-schedule"]`
410
+ - `data-hour-format`: '24h' | '12h' on the root
411
+ - `data-dragging`: 'move' | 'resize' on the root and on the event being dragged
412
+ - `data-event-id / data-day / data-start / data-end / data-kind`: on each .sw-week-schedule__event (start/end as "HH:MM")
413
+ - `data-selected`: on the focused event
414
+ - `.sw-week-schedule__total[data-value]`: hours booked, e.g. "9.5"
415
+ - How to operate: Focus an event ([role="button"][aria-roledescription="event"]) and press arrow keys, or drag it / its bottom edge. Agent bridge: moveEvent(titleOrId, day (name or index), start "HH:MM"), resizeEvent(titleOrId, end "HH:MM"), setHourFormat("24h" | "12h"); state = { events: [{ id, title, day, dayIndex, start, end, kind }], hourFormat, hoursBooked, days, hours, step }.
416
+
417
+ Related: `calendar`, `time-input`, `timeline`, `segmented-control`
418
+
419
+ ---
420
+
421
+ # Canvas
422
+
423
+ > 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.
424
+
425
+ Category: extras · Status: beta · Slug: `canvas`
426
+
427
+ ```tsx
428
+ import { Canvas } from '@peerproblem/sw3-ui/extras'
429
+ ```
430
+
431
+ ## When to use
432
+ - Letting people arrange a few blocks on a poster, card or slide layout and nudge them precisely.
433
+ - Demonstrating or prototyping direct manipulation (select, move, resize, inspect) that an agent can also drive.
434
+ - Editing a small, fixed set of shapes whose position, size, fill and opacity are the whole model.
435
+
436
+ ## Avoid
437
+ - A full vector editor (paths, groups, rotation, undo history) — Canvas is a fixed-set layout board; build on a dedicated editor.
438
+ - Charts or data plots — use the chart components in @peerproblem/sw3-ui/charts.
439
+ - Image cropping or framing — use ImageCropper.
440
+ - Arranging list items in order — use a sortable list, not free positioning.
441
+ - More than ~12 shapes: every shape is a tab stop and a layers row.
442
+
443
+ ## Props
444
+
445
+ | Prop | Type | Default | Description |
446
+ | --- | --- | --- | --- |
447
+ | `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. |
448
+ | `defaultShapes` | `CanvasShape[]` | `[]` | Initial shapes when uncontrolled. |
449
+ | `onShapesChange` | `(shapes: CanvasShape[]) => void` | | Every change: each drag frame, arrow key and inspector edit. |
450
+ | `onShapesCommit` | `(shapes: CanvasShape[]) => void` | | Once an interaction ends (pointer up, key, field blur/Enter, swatch, slider release). Save here. |
451
+ | `selectedId` | `string \| null` | | Id of the selected shape, null for none. Controlled. |
452
+ | `defaultSelectedId` | `string \| null` | `null` | Initially selected shape. |
453
+ | `onSelectedIdChange` | `(id: string \| null) => void` | | Selection changed (click, focus, layers row, Escape, empty-board click). |
454
+ | `width` | `number` | `560` | Artboard width in units. The board fills the container width and keeps width:height. |
455
+ | `height` | `number` | `320` | Artboard height in units. |
456
+ | `inspector` | `boolean` | `true` | Show LAYERS, X/Y/W/H, FILL and OPACITY under the board. |
457
+ | `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. |
458
+ | `snap` | `number` | `1` | Drag and resize snap, in units. |
459
+ | `radius` | `RadiusToken \| number` | `'lg'` | Outer squircle frame radius. |
460
+ | `aria-label` | `string` | | Names the canvas, e.g. "Poster canvas". |
461
+
462
+ ## Examples
463
+
464
+ ### Poster layout, ellipse selected
465
+
466
+ ```tsx
467
+ <Canvas
468
+ aria-label="Poster canvas"
469
+ width={460}
470
+ height={312}
471
+ defaultSelectedId="ellipse"
472
+ defaultShapes={[
473
+ { id: 'rect', type: 'rect', name: 'Rectangle', x: 24, y: 24, w: 240, h: 168, fill: 'hatch', opacity: 100 },
474
+ { id: 'ellipse', type: 'ellipse', name: 'Ellipse', x: 300, y: 56, w: 136, h: 136, fill: 'white', opacity: 100 },
475
+ { id: 'text', type: 'text', name: 'Text', x: 120, y: 222, w: 220, h: 56, fill: 'white', opacity: 100, text: 'Behaviors.' },
476
+ ]}
477
+ />
478
+ ```
479
+
480
+ ### Embedded artboard, saved on commit
481
+
482
+ ```tsx
483
+ const [shapes, setShapes] = useState(initialShapes)
484
+ const [selected, setSelected] = useState<string | null>(null)
485
+
486
+ <Canvas
487
+ aria-label="Card layout"
488
+ shapes={shapes}
489
+ onShapesChange={setShapes}
490
+ onShapesCommit={(s) => save(s)}
491
+ selectedId={selected}
492
+ onSelectedIdChange={setSelected}
493
+ inspector={false}
494
+ framed={false}
495
+ />
496
+ ```
497
+
498
+ ## Rules
499
+ - 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.
500
+ - 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.
501
+ - Shapes always stay inside the artboard (min 8 × 8); do not pass coordinates you expect to overflow.
502
+ - Fills are a fixed monochrome set (ink, gray, white, hatch) that flips with the theme — do not try to colour shapes with the accent.
503
+ - Use framed={false} inside an existing card or gallery preview. Keep the artboard boundary visible so users can see the editable area.
504
+ - Use onShapesCommit (not onShapesChange) to save or sync — onShapesChange fires on every drag frame.
505
+
506
+ ## Accessibility
507
+ - Each shape is a focusable role="button" with aria-roledescription="shape", aria-label "<Name>. Arrow keys move it." and aria-pressed = selected.
508
+ - 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).
509
+ - Resize from the keyboard with the W / H number fields (Arrow Up/Down, Shift = ×10). The corner handles are pointer-only.
510
+ - 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.
511
+ - 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.
512
+ - Selection is shown by a dashed box plus corner handles and a solid layers row — never colour alone.
513
+
514
+ ## DOM contract (for agents operating the page)
515
+
516
+ - Selector: `[data-sw="canvas"]`
517
+ - `data-selected`: on the root: id of the selected shape (absent when none)
518
+ - `data-framed`: on the root when the outer surface is shown
519
+ - `data-dragging`: on the root while a move or resize drag is in progress
520
+ - `aria-pressed`: on each .sw-canvas__shape[role="button"]: true when selected
521
+ - `data-id / data-shape / data-fill`: on each shape: its id, rect|ellipse|text and fill
522
+ - `style left/top/width/height`: each shape's box in percent of the artboard (units = percent × width or height / 100)
523
+ - 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.
524
+
525
+ Related: `toggle`, `number-input`, `slider`, `resizable`, `image-cropper`
526
+
527
+ ---