@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
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
|
-
#
|
|
1
|
+
# @peerproblem/sw3-ui
|
|
2
2
|
|
|
3
|
-
|
|
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`
|