@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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Peer Problem
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,110 @@
1
- # Temporary Holding Version
1
+ # @peerproblem/sw3-ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An agentic design system for React. Accessible components, design rules and tokens that AI agents can read, build with, check and operate, plus Unovis charts and MapLibre maps as optional entry points.
4
+
5
+ - **Components:** forms, selection, dates, overlays, navigation, layout, feedback and a dashboard frame (`AppShell`, `SidebarNav`, `DashboardGrid`). Keyboard-complete and ARIA-correct.
6
+ - **Docs agents can use:** the package ships `agent/llms.txt`, one file per topic and one per component, plus `registry.json`. Agents read only what the task needs.
7
+ - **Design check:** `sw3-check` flags hard-coded colors and radii, extra accent buttons, unlabeled charts and nested frames, with a suggested fix for each.
8
+ - **Agent bridge:** `@peerproblem/sw3-ui/agent` lets an agent read and change rendered components through their APIs (`snapshot`, `query`, `act`), with permissions and WebMCP support.
9
+ - **Two layers of rules:** structure rules (one primary action, hierarchy, accessibility, tokens) hold in every app. The look is a default theme you change with tokens.
10
+
11
+ Docs and live demos: <https://sw3-ui-sdk.vercel.app>
12
+
13
+ ## Install
14
+
15
+ ```sh
16
+ npm install @peerproblem/sw3-ui
17
+ ```
18
+
19
+ React 18 or 19 is required. Install the optional peers only for the entry points you use:
20
+
21
+ | Entry point | Also install |
22
+ | --- | --- |
23
+ | `@peerproblem/sw3-ui/charts` | `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` |
24
+ | `@peerproblem/sw3-ui/map` | `maplibre-gl@^6.18.0` and its CSS |
25
+
26
+ ## Set up
27
+
28
+ ```tsx
29
+ import '@peerproblem/sw3-ui/styles.css'
30
+ import { SwProvider, Button } from '@peerproblem/sw3-ui'
31
+
32
+ export function App() {
33
+ return (
34
+ <SwProvider>
35
+ <main className="sw-root">
36
+ <Button variant="accent">Publish</Button>
37
+ </main>
38
+ </SwProvider>
39
+ )
40
+ }
41
+ ```
42
+
43
+ The default theme uses Geist and Geist Mono. Install `@fontsource-variable/geist` and `@fontsource-variable/geist-mono` and import them once, or set `--sw-font-sans` and `--sw-font-mono` to your own typefaces.
44
+
45
+ ## A small dashboard
46
+
47
+ ```tsx
48
+ import { AppShell, AppShellHeader, AppShellSidebar, AppShellMain, ShellToggle, SidebarNav, SidebarItem, DashboardGrid, DashboardTile, Heading, Icon } from '@peerproblem/sw3-ui'
49
+ import { TrendChart } from '@peerproblem/sw3-ui/charts'
50
+
51
+ <AppShell autoSaveId="overview">
52
+ <AppShellHeader start={<><ShellToggle /><Heading as="h1" size="sm">Overview</Heading></>} />
53
+ <AppShellSidebar label="Workspace">
54
+ <SidebarNav aria-label="Workspace">
55
+ <SidebarItem icon={<Icon name="home" />} label="Overview" active href="#/" />
56
+ </SidebarNav>
57
+ </AppShellSidebar>
58
+ <AppShellMain padding="none">
59
+ <DashboardGrid aria-label="Overview">
60
+ <DashboardTile id="requests" span={8} title="Requests" count="24h">
61
+ <TrendChart aria-label="Requests peaked at 15:00" values={values} labels={hours} />
62
+ </DashboardTile>
63
+ </DashboardGrid>
64
+ </AppShellMain>
65
+ </AppShell>
66
+ ```
67
+
68
+ A complete dashboard is under Blocks on the docs site.
69
+
70
+ ## Entry points
71
+
72
+ | Import | What |
73
+ | --- | --- |
74
+ | `@peerproblem/sw3-ui` | Components, primitives (`usePopup`, `useListNavigation`, `useFieldControl`…), tokens, motion presets |
75
+ | `@peerproblem/sw3-ui/charts` | Chart components and `ChartSurface` for raw Unovis charts |
76
+ | `@peerproblem/sw3-ui/map` | `MapView` (MapLibre) |
77
+ | `@peerproblem/sw3-ui/extras` | Specialized components: PosterCard, ActionSquare, PillButton, Canvas, WeekSchedule |
78
+ | `@peerproblem/sw3-ui/agent` | Agent bridge: `createAgent`, `agentTools`, `registerTools` |
79
+ | `@peerproblem/sw3-ui/check`, `@peerproblem/sw3-ui/check/source` | Design check for rendered views and for source files |
80
+ | `@peerproblem/sw3-ui/meta`, `@peerproblem/sw3-ui/registry.json` | Component metadata as code or JSON |
81
+ | `@peerproblem/sw3-ui/styles.css`, `@peerproblem/sw3-ui/themes/*.css` | Styles and the `calm` / `frost` designs |
82
+
83
+ ## Using it with an AI agent
84
+
85
+ Tell the agent where the docs are, for example in your `AGENTS.md` or `CLAUDE.md`:
86
+
87
+ ```md
88
+ Build UI with @peerproblem/sw3-ui. Start at node_modules/@peerproblem/sw3-ui/agent/llms.txt,
89
+ read llms/foundations.txt once, then the topic file for the task.
90
+ ```
91
+
92
+ After the agent writes UI, check it:
93
+
94
+ ```sh
95
+ npx --no-install sw3-check src
96
+ ```
97
+
98
+ The checker prints JSON with each finding's file, line and fix. It needs TypeScript in the app.
99
+
100
+ ## Stability
101
+
102
+ Each component's docs show a status. `stable` components follow semver. `beta` components may change in a minor release, and every change is in the changelog. Until 1.0, minor versions (0.x.0) may include breaking changes.
103
+
104
+ ## Known issues
105
+
106
+ With the latest `@types/react` (18 or 19), TypeScript reports an error inside `framer-motion`'s own type definitions (`MotionStyle`). Set `"skipLibCheck": true` in `tsconfig.json`; the Vite and Next.js templates already do.
107
+
108
+ ## License
109
+
110
+ MIT
@@ -0,0 +1,95 @@
1
+ # Accordion
2
+
3
+ > Stacked sections whose headings expand and collapse their panels, with an animated height.
4
+
5
+ Category: layout · Status: beta · Slug: `accordion`
6
+
7
+ ```tsx
8
+ import { Accordion, AccordionItem, AccordionTrigger, AccordionPanel } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - FAQs, settings groups and long pages where readers scan headings and open only what they need.
13
+ - Several related sections of the same weight in a narrow column.
14
+
15
+ ## Avoid
16
+ - Switching between views of the same thing — use Tabs.
17
+ - A single show/hide toggle — use Collapsible.
18
+ - Hiding content everyone must read (errors, required fields) — keep it visible.
19
+ - Putting interactive controls inside AccordionTrigger — the whole trigger is one button.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `size` | `'sm' \| 'md'` | `'md'` | sm is for dashboards: 40px header rows (6px inset, 28px trigger), 13px titles and a 14px frame radius. |
26
+ | `fill` | `boolean` | `false` | Fill the parent height. Open items share it and scroll on their own; folded items shrink to their header. Use it for an inspector or a side column. |
27
+ | `AccordionTrigger.actions` | `ReactNode` | | Controls beside the trigger, not inside it, e.g. `Button size="2xs" variant="ghost" iconOnly`. |
28
+ | `items` | `{ value: string; title: ReactNode; content: ReactNode; disabled?: boolean }[]` | | Shorthand: render items from data instead of parts. |
29
+ | `value` | `string[]` | | Open item values (always an array). Controlled. |
30
+ | `defaultValue` | `string[]` | `[]` | Items open at first, when uncontrolled. |
31
+ | `onValueChange` | `(value: string[]) => void` | | Called when items open or close. |
32
+ | `multiple` | `boolean` | `false` | Allow several items open at once. Otherwise opening one closes the others. |
33
+ | `collapsible` | `boolean` | `true` | Single mode: whether the open item can be closed. false keeps one open (its trigger gets aria-disabled). |
34
+ | `disabled` | `boolean` | `false` | Disable every item. Triggers stay focusable. |
35
+ | `keepMounted` | `boolean` | `false` | Keep closed panels in the DOM (hidden), e.g. to preserve form state. |
36
+ | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading element wrapping each trigger. Match the page outline. |
37
+ | `variant` | `'framed' \| 'plain'` | `'framed'` | framed = squircle frame with hairlines between items; plain = hairlines only. |
38
+ | `radius` | `RadiusValue` | `'lg'` | Corner radius of the framed variant. |
39
+ | `AccordionItem.value` * | `string` | | Unique value; listed in `value` while open. |
40
+ | `AccordionItem.disabled` | `boolean` | | Stops this item from opening or closing. |
41
+ | `AccordionTrigger.meta` | `ReactNode` | | Small trailing text before the chevron (count, status). |
42
+ | `AccordionTrigger.headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | | Override the heading level for one item. |
43
+ | `AccordionPanel.keepMounted` | `boolean` | | Override the Accordion's keepMounted for one panel. |
44
+
45
+ ## Examples
46
+
47
+ ### FAQ from data
48
+
49
+ ```tsx
50
+ <Accordion
51
+ defaultValue={['limits']}
52
+ items={[
53
+ { value: 'limits', title: 'What are the rate limits?', content: '600 requests per minute per key.' },
54
+ { value: 'models', title: 'Which models can I use?', content: 'Every model on your plan, switchable per request.' },
55
+ { value: 'data', title: 'Do you train on my data?', content: 'No. Prompts and outputs are never used for training.' },
56
+ ]}
57
+ />
58
+ ```
59
+
60
+ ### Parts, several open
61
+
62
+ ```tsx
63
+ const [open, setOpen] = useState<string[]>(['general'])
64
+
65
+ <Accordion multiple value={open} onValueChange={setOpen} headingLevel={2}>
66
+ <AccordionItem value="general">
67
+ <AccordionTrigger meta="3">General</AccordionTrigger>
68
+ <AccordionPanel>Name, avatar and workspace URL.</AccordionPanel>
69
+ </AccordionItem>
70
+ <AccordionItem value="billing">
71
+ <AccordionTrigger>Billing</AccordionTrigger>
72
+ <AccordionPanel>Plan, invoices and payment method.</AccordionPanel>
73
+ </AccordionItem>
74
+ </Accordion>
75
+ ```
76
+
77
+ ## Rules
78
+ - A stack of foldable dashboard panels is `<Accordion size="sm" variant="plain|framed" multiple fill>`. Do not stack Cards with gaps.
79
+ - Trigger text is a short noun phrase or question; put details in the panel.
80
+ - Keep it to roughly 3–10 items; more becomes a wall of headings.
81
+
82
+ ## Accessibility
83
+ - Each trigger is a <button aria-expanded aria-controls> inside an <h3> (headingLevel).
84
+ - Panels are role="region" labelled by their trigger.
85
+ - Tab moves between triggers; Enter/Space toggles. No arrow-key navigation, per the current APG pattern.
86
+
87
+ ## DOM contract (for agents operating the page)
88
+
89
+ - Selector: `[data-sw="accordion"]`
90
+ - `data-state`: open | closed on accordion-item, accordion-trigger and accordion-panel
91
+ - `aria-expanded`: on [data-sw="accordion-trigger"]
92
+ - `data-disabled`: on the root or item when disabled
93
+ - How to operate: Click [data-sw="accordion-trigger"] to toggle its item. Agent bridge: expand(value), collapse(value), toggle(value), setValue(values[]); state = { value, multiple, disabled }.
94
+
95
+ Related: `collapsible`, `tabs`
@@ -0,0 +1,106 @@
1
+ # ActionSquare
2
+
3
+ > A text label paired with a squircle icon tile ("Learn more [+]", "Close [−]").
4
+
5
+ Category: extras · Status: beta · Slug: `action-square`
6
+
7
+ ```tsx
8
+ import { ActionSquare } from '@peerproblem/sw3-ui/extras'
9
+ ```
10
+
11
+ ## When to use
12
+ - A quiet secondary action pinned to the corner of media, a card or a sheet.
13
+ - Open/close pairs: "Learn more" (`corner`/`plus`) on the trigger, "Close" (`minus`, tone `ink`) inside the sheet.
14
+ - Inside another clickable surface: pass `decorative` so it renders a span and picks up the parent hover.
15
+
16
+ ## Avoid
17
+ - Primary CTAs — use Button (`primary` / `accent`).
18
+ - Long labels. Keep it 1–3 words; the tile carries the meaning.
19
+ - Nesting a non-decorative ActionSquare inside a button or link (invalid HTML).
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `label` * | `string` | | Visible text and the accessible name. |
26
+ | `icon` | `IconName` | `'corner'` | Icon in the tile: 'corner' | 'plus' | 'minus' | 'close' | 'expand' | 'arrow-up-right' | … |
27
+ | `tone` | `'light' \| 'ink' \| 'glass'` | `'light'` | light = pale tile · ink = solid dark tile · glass = translucent on photos/dark. |
28
+ | `size` | `'md' \| 'lg'` | `'md'` | 48px or 60px tile. |
29
+ | `iconFirst` | `boolean` | `false` | Tile before the label. |
30
+ | `hideLabel` | `boolean` | `false` | Tile only; label stays as the accessible name. |
31
+ | `decorative` | `boolean` | `false` | Render a non-interactive span for use inside another clickable element. |
32
+ | `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. |
33
+
34
+ ## Examples
35
+
36
+ ### Corner action
37
+
38
+ ```tsx
39
+ <ActionSquare label="Learn more" icon="corner" onClick={() => setOpen(true)} />
40
+ ```
41
+
42
+ ### Close inside a sheet
43
+
44
+ ```tsx
45
+ <ActionSquare label="Close" icon="minus" tone="ink" size="lg" onClick={() => setOpen(false)} />
46
+ ```
47
+
48
+ ### Inside a clickable media card
49
+
50
+ ```tsx
51
+ <button className="media" onClick={open}>
52
+ <img src="/lens.png" alt="" />
53
+ <ActionSquare decorative label="Learn more" style={{ position: 'absolute', top: 16, right: 16 }} />
54
+ </button>
55
+ ```
56
+
57
+ ## Variants
58
+
59
+ Rendered as `data-<variant>` on `[data-sw="action-square"]`.
60
+
61
+ - `tone`: `light` | `ink` | `glass` (default `light`)
62
+ - `size`: `md` | `lg` (default `md`)
63
+
64
+ ## CSS variables
65
+
66
+ Set on any ancestor to adjust this component. Never target `.sw-*` selectors.
67
+
68
+ | Variable | Controls |
69
+ | --- | --- |
70
+ | `--sw-action-square-tile-size` | Tile width and height. |
71
+ | `--sw-action-square-tile-bg` | Tile fill. |
72
+ | `--sw-action-square-tile-border` | Tile 1px frame (light tone: --sw-frame; ink and glass: none). |
73
+ | `--sw-action-square-tile-bg-hover` | Tile fill on hover. |
74
+ | `--sw-action-square-tile-bg-active` | Tile fill while pressed. |
75
+ | `--sw-action-square-tile-fg` | Icon color. |
76
+ | `--sw-action-square-fg` | Label color. |
77
+ | `--sw-action-square-gap` | Space between label and tile. |
78
+ | `--sw-action-square-font-size` | Label size. |
79
+
80
+ ## Designs
81
+
82
+ Swap the whole look with `data-design` on <html> or any wrapper.
83
+
84
+ - `sdk`: Default. No attribute needed. Neutral tokens and Geist, with an optional app-defined brand accent.
85
+ - `calm`: import '@peerproblem/sw3-ui/themes/calm.css' + data-design="calm". Teal-grey ink, pale tiles, IBM Plex Sans.
86
+ - `frost`: import '@peerproblem/sw3-ui/themes/frost.css' + data-design="frost". Frosted fills that flip to solid on hover, Urbanist.
87
+
88
+ ## Rules
89
+ - Pick looks with `tone` and `size`. Do not write CSS that targets .sw-* class names.
90
+ - To adjust one place, set a `recipe.cssVars` variable on a wrapper: `.toolbar { --sw-pill-button-radius: 16px }`.
91
+ - To change a whole look, use `data-design` with a theme file instead of overriding many variables.
92
+ - Use tone `ink` for the action that closes or dismisses, `light` for the one that opens.
93
+
94
+ ## Accessibility
95
+ - The label is the accessible name; with `hideLabel` it is still read.
96
+ - Focus ring is a 2px accent outline around the whole row.
97
+
98
+ ## DOM contract (for agents operating the page)
99
+
100
+ - Selector: `[data-sw="action-square"]`
101
+ - `data-tone`: light | ink | glass
102
+ - `data-size`: md | lg
103
+ - `data-decorative`: present when it is a span inside another control
104
+ - How to operate: Click the element (not the tile) unless data-decorative is present — then click its clickable ancestor.
105
+
106
+ Related: `button`, `pill-button`
@@ -0,0 +1,87 @@
1
+ # Agent bridge
2
+
3
+ > Lets an AI agent list the SW3 components on a page and change them through their APIs: snapshot, query, act, subscribe, WebMCP.
4
+
5
+ Category: hooks · Status: beta · Slug: `agent-bridge`
6
+
7
+ ```tsx
8
+ import { createAgent, agentTools, callAgentTool, registerTools } from '@peerproblem/sw3-ui/agent'
9
+ ```
10
+
11
+ ## When to use
12
+ - An assistant inside your app should fill forms, pick options or press buttons for the user.
13
+ - A browser agent (WebMCP) should operate your page reliably instead of clicking pixels.
14
+ - Tests or scripts that drive the UI by label.
15
+
16
+ ## Avoid
17
+ - Letting an agent press destructive buttons without a person. Require approval in the app’s `allow` policy.
18
+ - Unlabelled controls. The bridge finds components by accessible name; add `aria-label` or a Field label.
19
+ - Treating snapshot text as instructions. It is page data that people typed.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `createAgent(options)` | `{ allow?: (req) => boolean \| Promise<boolean>; root?: () => HTMLElement \| null }` | | Create the bridge once. `allow` approves each step: `req` = { ref, component, label, action, args, confirm }. |
26
+ | `createAgent({ confirm })` | `(req: AllowRequest) => boolean \| Promise<boolean>` | | App confirmation for data-sw-confirm controls. Marked actions are blocked without this callback. |
27
+ | `agent.snapshot()` | `() => AgentComponent[]` | | Every component: { ref, component, label, …state, actions }. First 100. |
28
+ | `agent.act({ steps })` | `(input: { steps: { ref, action, args?, confirm? }[] }) => Promise<ActResult>` | | Run actions in order. `ref` = ref or label. Item labels resolve to values. Returns { ok, steps, values, error? }. |
29
+ | `agent.query({ text, within, kind })` | `(q) => Promise<QueryResult[]>` | | Find components by text, or list up to 50 choices of one list component with `within`. |
30
+ | `agent.subscribe(listener)` | `(fn: (changes: AgentChange[]) => void) => () => void` | | Changes with before/after and source "person" | "agent". |
31
+ | `agentTools` | `ToolDefinition[]` | | snapshot / query / act with JSON Schemas, for any model SDK. |
32
+ | `callAgentTool(agent, name, input)` | `Promise<unknown>` | | Route a model tool call to the bridge. |
33
+ | `registerTools(agent, { allow })` | `() => void` | | Publish tools through WebMCP using the original act function from createAgent(). The WebMCP policy runs after the bridge policy. Returns cleanup. |
34
+ | `useAgentBinding(ref, spec)` | `(ref, { kind, label?, state, actions, items?, secret? }) => void` | | From `@peerproblem/sw3-ui`. Makes your own component visible to the bridge. |
35
+ | `isAgentChange()` | `() => boolean` | | From `@peerproblem/sw3-ui`. True inside change callbacks triggered by the bridge. |
36
+
37
+ ## Examples
38
+
39
+ ### Create and use
40
+
41
+ ```tsx
42
+ import { createAgent } from '@peerproblem/sw3-ui/agent'
43
+
44
+ const agent = createAgent({ allow: ({ confirm, action, label }) =>
45
+ action === 'press' || confirm ? window.confirm(`${action} ${label}?`) : true,
46
+ })
47
+
48
+ agent.snapshot()
49
+ await agent.act({ steps: [
50
+ { ref: 'Project name', action: 'setValue', args: ['Atlas'] },
51
+ { ref: 'Save changes', action: 'press', confirm: true },
52
+ ] })
53
+ ```
54
+
55
+ ### Give the tools to a model
56
+
57
+ ```tsx
58
+ import { agentTools, callAgentTool } from '@peerproblem/sw3-ui/agent'
59
+
60
+ // register agentTools with your model SDK, then for each tool call:
61
+ const output = await callAgentTool(agent, call.name, call.input)
62
+ ```
63
+
64
+ ### WebMCP
65
+
66
+ ```tsx
67
+ import { registerTools } from '@peerproblem/sw3-ui/agent'
68
+
69
+ const unregister = registerTools(agent, { allow: ({ action }) => action !== 'press' || window.confirm('Allow?') })
70
+ ```
71
+
72
+ ## Rules
73
+ - Create one bridge per app. It discovers components as they mount.
74
+ - Every control needs an accessible name. That name is its handle for agents.
75
+ - Use the app’s `allow` policy to decide which actions need a person to approve them. Treat `confirm: true` as a caller request for confirmation.
76
+ - Wrap private regions in `data-sw-agent="off"`.
77
+
78
+ ## Accessibility
79
+ - The bridge uses the same accessible names that assistive tech uses, so good a11y = good agent access.
80
+
81
+ ## DOM contract (for agents operating the page)
82
+
83
+ - Selector: `[data-sw]`
84
+ - `data-sw-agent="off"`: Region hidden from the bridge
85
+ - How to operate: Call snapshot() first, then act() with labels or refs. Each component meta lists its actions under dom.operate.
86
+
87
+ Related: `input`, `select`, `button`
@@ -0,0 +1,123 @@
1
+ # AgentConsole
2
+
3
+ > A chat panel that turns a request into agent-bridge steps and runs them one at a time: it marks each field it changes, logs the exact agent.act() call and its result, then sums up.
4
+
5
+ Category: agents · Status: beta · Slug: `agent-console`
6
+
7
+ ```tsx
8
+ import { AgentConsole } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - An in-app assistant that changes a form or settings page for the person, in plain sight.
13
+ - Demos and onboarding that show what an agent does on the page, step by step.
14
+ - Debugging an agent integration: every step shows its call and the before/after the bridge reported.
15
+
16
+ ## Avoid
17
+ - A general chat UI with no page actions — use your own message list; this console only narrates bridge steps.
18
+ - Running actions a person must approve without an app policy. Pass `agent={createAgent({ root, allow })}` and decide which actions need approval in `allow`.
19
+ - Putting the console inside the agent root: it hides its own composer from the bridge, but keep the console and the app side by side.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `plan` * | `(message: string) => AgentStep[] \| { steps: AgentStep[]; reply?: string } \| Promise<…>` | | Turns the request into bridge steps. Real apps call a model with agent.snapshot() and agentTools; return { steps: [], reply } to answer without acting. |
26
+ | `root` | `(() => HTMLElement \| null) \| RefObject<HTMLElement>` | | The part of the page the agent works on. Creates the agent when `agent` is omitted and scopes the field marks. |
27
+ | `agent` | `Agent` | | A bridge from createAgent(). Use it to add `allow`, or to share one agent with WebMCP / your model loop. |
28
+ | `summarize` | `(result: ActResult, message: string) => string` | | The closing sentence. Default lists the labels that changed, or the error. |
29
+ | `defaultMessage` | `string` | `''` | Initial composer text; Reset puts it back. |
30
+ | `message` | `string` | | Controlled composer text (with onMessageChange). |
31
+ | `onMessageChange` | `(message: string) => void` | | Composer text changed. |
32
+ | `placeholder` | `string` | `'Ask the agent to change something'` | Composer placeholder. |
33
+ | `stepDelay` | `number` | `700` | Milliseconds between steps, so people can follow. Always 0 with reduced motion. |
34
+ | `onRunComplete` | `(result: ActResult, message: string) => void` | | After every run, with the combined steps, final values and any error. |
35
+ | `onReset` | `() => void` | | Reset pressed: restore your app's defaults. The console clears its own log and marks. |
36
+ | `title` | `ReactNode` | `'Agent'` | Mono header label; also names the region. |
37
+ | `variant` | `'framed' \| 'plain'` | `'framed'` | Own squircle frame, or plain to fill a pane of a larger frame. |
38
+ | `radius` | `RadiusToken \| number` | `'lg'` | Frame radius when framed. |
39
+ | `sendLabel` | `string` | `'Send'` | Composer button label. |
40
+ | `resetLabel` | `string` | `'Reset'` | Button label after a run while the composer is empty. |
41
+
42
+ ## Examples
43
+
44
+ ### Settings assistant next to the form
45
+
46
+ ```tsx
47
+ const settings = useRef<HTMLDivElement>(null)
48
+
49
+ <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
50
+ <AgentConsole
51
+ root={settings}
52
+ plan={async (message) => {
53
+ // Send message + agent.snapshot() to your model with agentTools; return its act() steps.
54
+ return [
55
+ { ref: 'Region', action: 'setValue', args: ['Asia Pacific'] },
56
+ { ref: 'Preview deployments', action: 'setChecked', args: [true] },
57
+ ]
58
+ }}
59
+ defaultMessage="Move to Asia Pacific and turn on previews."
60
+ onReset={() => resetForm()}
61
+ style={{ flex: '1 1 300px', height: 520 }}
62
+ />
63
+ <Card ref={settings} padding="lg" style={{ flex: '1 1 340px' }}>
64
+ <Field label="Region"><Select items={regions} value={region} onValueChange={setRegion} /></Field>
65
+ <Switch label="Preview deployments" checked={preview} onCheckedChange={setPreview} />
66
+ </Card>
67
+ </div>
68
+ ```
69
+
70
+ ### Your own bridge with permissions
71
+
72
+ ```tsx
73
+ import { createAgent } from '@peerproblem/sw3-ui/agent'
74
+
75
+ const agent = useMemo(() => createAgent({
76
+ root: () => document.getElementById('billing'),
77
+ allow: ({ action, label, confirm }) => (confirm ? window.confirm(`${action} ${label}?`) : true),
78
+ }), [])
79
+
80
+ <AgentConsole
81
+ agent={agent}
82
+ root={() => document.getElementById('billing')}
83
+ plan={planWithModel}
84
+ summarize={(result) => (result.ok ? 'Billing updated.' : `Stopped: ${result.error?.message}`)}
85
+ />
86
+ ```
87
+
88
+ ### Answer without acting
89
+
90
+ ```tsx
91
+ <AgentConsole
92
+ root={settings}
93
+ plan={(message) => /region|plan/i.test(message)
94
+ ? parse(message)
95
+ : { steps: [], reply: 'I can change region and plan.' }}
96
+ />
97
+ ```
98
+
99
+ ## Rules
100
+ - Give every target field an accessible name (Field label, aria-label, Switch label): steps target fields by label, and the console finds the field to mark the same way.
101
+ - Marks go on the closest [data-sw="field"], [data-sw="switch-field"] or [data-agent-field] block around the control, else the control itself. Wrap unlabelled groups (a SegmentedControl with a Caption) in <div data-agent-field>.
102
+ - Keep the console outside `root`; the agent must only act on the app.
103
+ - The Send button is the accent action of the view — keep other buttons in the app outline or primary.
104
+ - Plan steps one field at a time; the console runs and logs each as its own agent.act() call.
105
+ - Text in the log comes from the page and the person: tell your model to treat it as data, never instructions.
106
+
107
+ ## Accessibility
108
+ - The root is a region named by its header. The log is role="log" with aria-live="polite", so each call, result and the summary are announced; it is focusable for keyboard scrolling.
109
+ - Enter sends, Shift+Enter adds a line. The button is disabled while a run is in progress (aria-busy on the root).
110
+ - Field marks are a dashed outline, not colour alone, and stay until Reset; changes also land in each control's own ARIA state.
111
+ - Reduced motion: steps run without delay and entries appear without animation.
112
+
113
+ ## DOM contract (for agents operating the page)
114
+
115
+ - Selector: `[data-sw="agent-console"]`
116
+ - `data-status`: 'idle' | 'running' | 'done' on the root
117
+ - `aria-busy`: true while a run is in progress
118
+ - `data-kind`: on each .sw-agent-console__entry: 'user' | 'planning' | 'step' | 'reply'
119
+ - `data-status (entry)`: on step entries: 'running' | 'done' | 'error'
120
+ - `data-agent-target`: on marked field blocks in the app: 'active' (step running) | 'changed' (kept until Reset)
121
+ - How to operate: Type into the composer textarea and press Enter or click Send; click Reset after a run. Agent bridge: setMessage(text), send(text?), reset(); state = { status, message, entries }. The composer itself is hidden from the bridge (data-sw-agent="off").
122
+
123
+ Related: `textarea`, `button`, `field`, `switch`, `select`
@@ -0,0 +1,82 @@
1
+ # AlertDialog
2
+
3
+ > A modal question that needs an explicit answer — Cancel or the action — plus an imperative `await confirm({...})`.
4
+
5
+ Category: overlays · Status: beta · Slug: `alert-dialog`
6
+
7
+ ```tsx
8
+ import { AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogCancel, AlertDialogAction, confirm, ConfirmHost } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Confirming destructive or irreversible actions: delete a project, revoke a key, stop a running agent.
13
+ - From an event handler: `if (await confirm({ title: "Delete run?", variant: "danger" })) …` with <ConfirmHost/> (or <OverlayHost/>) mounted once.
14
+
15
+ ## Avoid
16
+ - Forms or rich content → use Dialog.
17
+ - Confirming routine, undoable actions → just do it and offer Undo in a toast.
18
+ - Vague buttons like "OK" → name the action ("Delete project").
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `open` | `boolean` | | Controlled open state of the alert dialog. |
25
+ | `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
26
+ | `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
27
+ | `dismissible` | `boolean` | `true` | Whether Escape closes it (as Cancel). Pressing outside never closes it. |
28
+ | `AlertDialogTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default Button. An element is cloned with the part's props merged in (handlers chained, refs merged); a function gets the props and { open } and must spread them onto a focusable element. There is no asChild. |
29
+ | `AlertDialogContent.size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Max width. |
30
+ | `AlertDialogCancel` | `ButtonProps` | `children "Cancel"` | The safe answer. Gets initial focus. Put it first. |
31
+ | `AlertDialogAction.variant` | `'primary' \| 'danger' \| …ButtonVariant` | `'primary'` | Use danger for destructive actions. |
32
+ | `AlertDialogAction.onClick` | `(e) => unknown \| Promise<unknown>` | | Runs, then the dialog closes. Return a Promise to show loading until it resolves; a rejection keeps it open. Call e.preventDefault() to keep it open. |
33
+ | `confirm(options)` | `({ title, description?, confirmLabel?, cancelLabel?, variant?: "primary" \| "danger" }) => Promise<boolean>` | | Ask from anywhere; resolves true for confirm, false for Cancel/Escape. Calls queue. Needs <ConfirmHost/> or <OverlayHost/>. |
34
+
35
+ ## Examples
36
+
37
+ ### Delete project
38
+
39
+ ```tsx
40
+ <AlertDialog>
41
+ <AlertDialogTrigger variant="danger">Delete project</AlertDialogTrigger>
42
+ <AlertDialogContent>
43
+ <AlertDialogHeader>
44
+ <AlertDialogTitle>Delete “support-bot”?</AlertDialogTitle>
45
+ <AlertDialogDescription>Its runs, traces and API keys are removed for everyone. This can’t be undone.</AlertDialogDescription>
46
+ </AlertDialogHeader>
47
+ <AlertDialogFooter>
48
+ <AlertDialogCancel />
49
+ <AlertDialogAction variant="danger" onClick={() => api.deleteProject(id)}>Delete project</AlertDialogAction>
50
+ </AlertDialogFooter>
51
+ </AlertDialogContent>
52
+ </AlertDialog>
53
+ ```
54
+
55
+ ### confirm() from a handler
56
+
57
+ ```tsx
58
+ // once, near the root:
59
+ <OverlayHost />
60
+
61
+ async function revoke(key: string) {
62
+ const yes = await confirm({ title: 'Revoke this key?', description: 'Running jobs using it will fail.', confirmLabel: 'Revoke', variant: 'danger' })
63
+ if (yes) await api.revoke(key)
64
+ }
65
+ ```
66
+
67
+ ## Rules
68
+ - Title is the question; description says what happens.
69
+ - Cancel first, the action last; label the action with its verb.
70
+ - Only one AlertDialogAction.
71
+
72
+ ## Accessibility
73
+ - role="alertdialog" + aria-modal, labelled and described. Focus starts on Cancel and is trapped; Escape cancels; outside presses are ignored.
74
+
75
+ ## DOM contract (for agents operating the page)
76
+
77
+ - Selector: `[data-sw="alert-dialog-trigger"], [data-sw="alert-dialog-content"][role="alertdialog"]`
78
+ - `data-state`: open | closed
79
+ - `data-pending`: on the action while its Promise runs
80
+ - How to operate: Answer by clicking [data-sw="alert-dialog-cancel"] or [data-sw="alert-dialog-action"]. Agent bridge (kind "alert-dialog"): state {open}; actions open(), close() (close = cancel), toggle().
81
+
82
+ Related: `dialog`, `toast`