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