@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,76 @@
|
|
|
1
|
+
# Toggle / ToggleGroup
|
|
2
|
+
|
|
3
|
+
> A button that stays pressed (aria-pressed). ToggleGroup is a row of them for toolbars and filters: several on at once, or one that can be cleared. One tab stop, arrow-key focus.
|
|
4
|
+
|
|
5
|
+
Category: actions · Status: beta · Slug: `toggle`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Toggle, ToggleGroup } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Formatting buttons in a Toolbar (bold, italic, text alignment).
|
|
13
|
+
- Turning tools or filters on and off in place (`multiple`).
|
|
14
|
+
- Highlighting one item that can also be cleared.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- Picking one value or view that always has a value (Week / Month, grid / list) — use SegmentedControl. checkDesign reports `toggle-group-choice`.
|
|
18
|
+
- Settings with a label and description — use Switch.
|
|
19
|
+
- Navigation between pages — use Tabs or links.
|
|
20
|
+
- Icon-only toggles without `aria-label`.
|
|
21
|
+
|
|
22
|
+
## Props
|
|
23
|
+
|
|
24
|
+
| Prop | Type | Default | Description |
|
|
25
|
+
| --- | --- | --- | --- |
|
|
26
|
+
| `pressed` | `boolean` | | Controlled state (standalone). |
|
|
27
|
+
| `defaultPressed` | `boolean` | `false` | Initial state. |
|
|
28
|
+
| `onPressedChange` | `(pressed: boolean) => void` | | Called on press. |
|
|
29
|
+
| `value` | `string` | | Identifies it inside a ToggleGroup. |
|
|
30
|
+
| `icon` | `ReactNode` | | Icon before the label; alone it makes a square icon toggle. |
|
|
31
|
+
| `variant` | `'ghost' \| 'outline'` | `'ghost'` | outline adds a 1px frame at rest. On a ToggleGroup, outline frames the track. |
|
|
32
|
+
| `radius` | `RadiusToken \| number` | | Corner radius. In a group, items default to the concentric track radius − 3px. |
|
|
33
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 30 / 36 / 44px. |
|
|
34
|
+
| `ToggleGroup.value` | `string[]` | | Pressed values (controlled). |
|
|
35
|
+
| `ToggleGroup.defaultValue` | `string[]` | `[]` | Initial pressed values. |
|
|
36
|
+
| `ToggleGroup.onValueChange` | `(value: string[]) => void` | | Called on any press. |
|
|
37
|
+
| `ToggleGroup.multiple` | `boolean` | `false` | Allow several pressed at once. |
|
|
38
|
+
| `ToggleGroup.deselectable` | `boolean` | `true` | Single mode: pressing the pressed one releases it. |
|
|
39
|
+
| `ToggleGroup.items` | `{ value, label?, icon?, disabled?, 'aria-label'? }[]` | | Shorthand. |
|
|
40
|
+
| `ToggleGroup.radius` | `RadiusToken \| number` | `'sm'` | Track radius. |
|
|
41
|
+
| `ToggleGroup.orientation / loop / disabled / name` | `'horizontal' \| 'vertical' / boolean / boolean / string` | | Keys, wrapping, state, form name. |
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
### Standalone
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
<Toggle icon={<Icon name="star" />} aria-label="Pin run" />
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Multiple
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
<ToggleGroup multiple aria-label="Sources" value={sources} onValueChange={setSources}>
|
|
55
|
+
<Toggle value="web">Web</Toggle>
|
|
56
|
+
<Toggle value="docs">Docs</Toggle>
|
|
57
|
+
<Toggle value="code">Code</Toggle>
|
|
58
|
+
</ToggleGroup>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Rules
|
|
62
|
+
- Pressed items use the foreground as a solid fill and the background for icons and labels. Unpressed hover keeps a quiet fill or emphasizes the label.
|
|
63
|
+
- A ToggleGroup keeps a muted track behind the items. Use SegmentedControl when exactly one option must always be chosen.
|
|
64
|
+
|
|
65
|
+
## Accessibility
|
|
66
|
+
- Native <button aria-pressed>. Group is role="group" with one tab stop; Arrow/Home/End move focus; Space/Enter press. Disabled toggles in a group stay focusable with aria-disabled.
|
|
67
|
+
|
|
68
|
+
## DOM contract (for agents operating the page)
|
|
69
|
+
|
|
70
|
+
- Selector: `[data-sw="toggle"]`
|
|
71
|
+
- `aria-pressed`: true when pressed
|
|
72
|
+
- `data-state`: on | off
|
|
73
|
+
- `data-value`: value in a group
|
|
74
|
+
- How to operate: Click it. Agent bridge (toggle): toggle(), setChecked(bool). Group [data-sw="toggle-group"]: setValue(values[]), toggle(value), select(value), clear(); items = toggles.
|
|
75
|
+
|
|
76
|
+
Related: `segmented-control`, `switch`
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Token Input
|
|
2
|
+
|
|
3
|
+
> A text field that mixes editable text with tokens (people, files, tags) shown as chips; tokens come from Enter/comma, a Trigger Menu or code.
|
|
4
|
+
|
|
5
|
+
Category: inputs · Status: beta · Slug: `token-input`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { TokenInput, TokenInputEditor, TokenInputToken, TokenInputTokenRemove, TriggerMenu, type TokenInputValue } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Prompt boxes that reference files, people or skills inline.
|
|
13
|
+
- Tag / recipient fields: `createToken` turns typed words into chips on Enter or comma.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Plain text — use Textarea / Input.
|
|
17
|
+
- Choosing from a fixed list only — use Combobox multiple.
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `value / defaultValue / onValueChange` | `Array<string \| { type, value, label, id?, status?, data? }>` | | Text and tokens in order. Give controlled tokens stable `id`s (or reuse the same objects). |
|
|
24
|
+
| `onSubmit` | `(value) => void` | | Runs on the submit shortcut (not while a trigger menu is open). Without it the shortcut submits the surrounding form. |
|
|
25
|
+
| `submitShortcut` | `'enter' \| 'mod+enter'` | `'enter'` | Enter submits (Shift+Enter = new line), or ⌘/Ctrl+Enter submits. |
|
|
26
|
+
| `createToken` | `(text) => Token \| null` | | Turn the word before the caret into a token on Enter or comma. |
|
|
27
|
+
| `renderToken` | `(token) => ReactNode` | | Custom chip; usually `<TokenInputToken icon={…} />`. Default: icon by type + label + remove. |
|
|
28
|
+
| `format` | `(token) => string` | ``[label](type:value)`` | How tokens are written in the submitted `name` text. |
|
|
29
|
+
| `placeholder` | `string` | | For the default editor (or set it on TokenInputEditor). |
|
|
30
|
+
| `name / form / disabled / readOnly / required / invalid` | `string / boolean` | | Form + states; inherit from Field. |
|
|
31
|
+
| `children` | `ReactNode` | | `<TokenInputEditor placeholder aria-label />` and optionally a `<TriggerMenu>` for suggestions. |
|
|
32
|
+
|
|
33
|
+
## Examples
|
|
34
|
+
|
|
35
|
+
### Prompt with @files
|
|
36
|
+
|
|
37
|
+
```tsx
|
|
38
|
+
<TokenInput defaultValue={['Explain ', { type: 'file', value: 'src/routes.ts', label: 'routes.ts' }, ' ']} onSubmit={send}>
|
|
39
|
+
<TokenInputEditor aria-label="Prompt" placeholder="Ask anything — @ to add a file" />
|
|
40
|
+
<TriggerMenu triggers={[{ char: '@', type: 'file', items: files }]} />
|
|
41
|
+
</TokenInput>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Tags from Enter / comma
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
<TokenInput aria-label="Tags" name="tags" placeholder="Add tags…" createToken={(text) => ({ type: 'tag', value: text, label: text })} />
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Rules
|
|
51
|
+
- Each token moves and deletes as one piece; label tokens with what people read (file name, person name).
|
|
52
|
+
- Use `type` consistently: mention, file, tag, skill.
|
|
53
|
+
|
|
54
|
+
## Accessibility
|
|
55
|
+
- Editor role="textbox" aria-multiline; tokens read as "label type"; the ✕ is hidden from assistive tech because Backspace/Delete remove a token in one press.
|
|
56
|
+
- Enter submits (or inserts the highlighted suggestion), Shift+Enter is a new line; arrows step over a token.
|
|
57
|
+
|
|
58
|
+
## DOM contract (for agents operating the page)
|
|
59
|
+
|
|
60
|
+
- Selector: `[data-sw="token-input"]`
|
|
61
|
+
- `data-empty`: present while empty
|
|
62
|
+
- `[data-sw="token-input-token"]`: one per token: data-type, data-value
|
|
63
|
+
- `[data-sw="token-input-editor"]`: the contenteditable textbox
|
|
64
|
+
- How to operate: Click into [data-sw="token-input-editor"] and type; type a trigger (e.g. @) to pick a token. Agent bridge: setValue(value | text), add(tokenOrText), remove(valueOrId), clear(); state.text = readable text, state.tokens = token list.
|
|
65
|
+
|
|
66
|
+
Related: `trigger-menu`, `combobox`, `textarea`
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Toolbar
|
|
2
|
+
|
|
3
|
+
> A row of buttons, toggles, links and fields with a single tab stop; arrow keys move between them.
|
|
4
|
+
|
|
5
|
+
Category: actions · Status: beta · Slug: `toolbar`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Toolbar, ToolbarButton, ToolbarToggle, ToolbarGroup, ToolbarSeparator, ToolbarLink, ToolbarInput, Icon } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Editor formatting bars (bold, italic, align).
|
|
13
|
+
- Compact action rows above a table, canvas or code view.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- A page's main call to action — use Button.
|
|
17
|
+
- One or two buttons — plain Buttons are fine.
|
|
18
|
+
- Navigation between pages — use links or NavigationMenu.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `aria-label` * | `string` | | Names the toolbar, e.g. "Text formatting". |
|
|
25
|
+
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Which arrow keys move focus. |
|
|
26
|
+
| `loop` | `boolean` | `true` | Arrow keys wrap. |
|
|
27
|
+
| `disabled` | `boolean` | `false` | Disable every item (they stay focusable with aria-disabled). |
|
|
28
|
+
| `size` | `'sm' \| 'md'` | `'md'` | 28 / 32px items. |
|
|
29
|
+
| `variant` | `'framed' \| 'plain'` | `'framed'` | framed = squircle frame around the bar. |
|
|
30
|
+
| `ToolbarButton.icon` | `ReactNode` | | Icon before the label. Icon-only buttons need aria-label. |
|
|
31
|
+
| `ToolbarButton.disabled` | `boolean` | | aria-disabled; still reachable with arrows. |
|
|
32
|
+
| `ToolbarButton.focusableWhenDisabled` | `boolean` | `true` | false = natively disabled and skipped. |
|
|
33
|
+
| `ToolbarToggle.pressed` | `boolean` | | Controlled pressed state (aria-pressed). |
|
|
34
|
+
| `ToolbarToggle.defaultPressed` | `boolean` | `false` | Initial pressed state. |
|
|
35
|
+
| `ToolbarToggle.onPressedChange` | `(pressed: boolean) => void` | | Called on press. |
|
|
36
|
+
| `ToolbarGroup.aria-label` | `string` | | Names a set of related items. |
|
|
37
|
+
| `ToolbarGroup.disabled` | `boolean` | | Disable every item in the group. |
|
|
38
|
+
| `ToolbarInput.prefix` | `ReactNode` | | Icon inside the field. |
|
|
39
|
+
| `ToolbarLink.href` | `string` | | A link item. |
|
|
40
|
+
|
|
41
|
+
## Examples
|
|
42
|
+
|
|
43
|
+
### Formatting bar
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
<Toolbar aria-label="Text formatting">
|
|
47
|
+
<ToolbarGroup aria-label="Style">
|
|
48
|
+
<ToolbarToggle aria-label="Bold" defaultPressed>B</ToolbarToggle>
|
|
49
|
+
<ToolbarToggle aria-label="Italic"><i>I</i></ToolbarToggle>
|
|
50
|
+
</ToolbarGroup>
|
|
51
|
+
<ToolbarSeparator />
|
|
52
|
+
<ToolbarButton icon={<Icon name="copy" />} aria-label="Copy" />
|
|
53
|
+
<ToolbarButton icon={<Icon name="trash" />} aria-label="Delete" disabled />
|
|
54
|
+
<ToolbarSeparator />
|
|
55
|
+
<ToolbarInput aria-label="Search" placeholder="Find…" prefix={<Icon name="search" />} />
|
|
56
|
+
</Toolbar>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Rules
|
|
60
|
+
- Group related items and separate groups with ToolbarSeparator.
|
|
61
|
+
- Icon-only items always get aria-label (and ideally a Tooltip).
|
|
62
|
+
- Buttons, toggles and fields share one concentric squircle radius (toolbar radius − 4px inset). Pressed toggles use the foreground as a solid fill and the background for their labels and icons.
|
|
63
|
+
|
|
64
|
+
## Accessibility
|
|
65
|
+
- role="toolbar" with aria-orientation; separators have role="separator".
|
|
66
|
+
- One tab stop with roving focus; Tab returns to the item focused last.
|
|
67
|
+
- Arrow keys move; Home/End jump (except inside a field, where the caret keeps them). Toggles use aria-pressed; moving focus never presses them.
|
|
68
|
+
|
|
69
|
+
## DOM contract (for agents operating the page)
|
|
70
|
+
|
|
71
|
+
- Selector: `[data-sw="toolbar"]`
|
|
72
|
+
- `aria-pressed`: on [data-sw="toolbar-button"] toggles
|
|
73
|
+
- `aria-disabled`: on disabled items
|
|
74
|
+
- How to operate: Click the [data-sw="toolbar-button"] whose aria-label or text matches; type into [data-sw="toolbar-input"]. Items are native buttons/inputs, so the bridge reads them through the DOM fallback.
|
|
75
|
+
|
|
76
|
+
Related: `button`, `segmented-control`
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Tooltip
|
|
2
|
+
|
|
3
|
+
> A short plain-text hint that names or describes a control on hover and keyboard focus.
|
|
4
|
+
|
|
5
|
+
Category: overlays · Status: beta · Slug: `tooltip`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Tooltip, TooltipTrigger, TooltipContent } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Naming icon-only buttons.
|
|
13
|
+
- A few words of extra context or a keyboard shortcut for a control.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Links, buttons or anything interactive inside → use Popover or HoverCard.
|
|
17
|
+
- Essential information (touch users never see tooltips) → put it in the page.
|
|
18
|
+
- Wrapping a disabled native button (it gets no hover/focus) → wrap a span, or keep the button enabled with aria-disabled.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `content` | `ReactNode` | | Shorthand: the tip text. The single child element becomes the trigger: <Tooltip content="Copy"><Button/></Tooltip>. |
|
|
25
|
+
| `open` | `boolean` | | Controlled open state of the tooltip. |
|
|
26
|
+
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
|
|
27
|
+
| `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
|
|
28
|
+
| `delay` | `number` | `600` | ms the pointer rests before opening. Once one tooltip is open, neighbours open instantly (grouping is automatic). |
|
|
29
|
+
| `closeDelay` | `number` | `100` | ms before closing after the pointer leaves trigger and tip. |
|
|
30
|
+
| `disabled` | `boolean` | `false` | Never open; the trigger keeps working. |
|
|
31
|
+
| `type` | `'label' \| 'description'` | | Whether the tip names the trigger (aria-labelledby) or describes it (aria-describedby). Default: label when the trigger has no name of its own. |
|
|
32
|
+
| `closeOnPress` | `boolean` | `true` | Close when the trigger is pressed. |
|
|
33
|
+
| `side / align / sideOffset` | `Side / Align / number` | `'top' / 'center' / 6` | Placement (on Tooltip for the shorthand, on TooltipContent when composing). |
|
|
34
|
+
| `TooltipTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default outline 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. |
|
|
35
|
+
| `TooltipContent.shortcut` | `ReactNode` | | Keyboard hint shown after the text, e.g. "⌘C". |
|
|
36
|
+
|
|
37
|
+
## Examples
|
|
38
|
+
|
|
39
|
+
### Icon button
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
<Tooltip content="Copy code">
|
|
43
|
+
<Button variant="ghost" size="sm" iconOnly aria-label="Copy code" leading={<Icon name="copy" />} />
|
|
44
|
+
</Tooltip>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Composed, with shortcut
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
<Tooltip delay={300}>
|
|
51
|
+
<TooltipTrigger variant="secondary">Run</TooltipTrigger>
|
|
52
|
+
<TooltipContent side="bottom" shortcut="⌘↵">Run the agent</TooltipContent>
|
|
53
|
+
</Tooltip>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### On a popover trigger
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
<Popover>
|
|
60
|
+
<Tooltip content="Share with your team">
|
|
61
|
+
<PopoverTrigger>Share</PopoverTrigger>
|
|
62
|
+
</Tooltip>
|
|
63
|
+
<PopoverContent>…</PopoverContent>
|
|
64
|
+
</Popover>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Rules
|
|
68
|
+
- A few words of plain text. No sentences, no links. (Surface: radius xs, 4×8px padding, 12px text.)
|
|
69
|
+
- The child must be one element that forwards its ref and accepts event props (SW3 Button, native button, a).
|
|
70
|
+
- Icon-only triggers still need aria-label; the tooltip adds the visible hint.
|
|
71
|
+
|
|
72
|
+
## Accessibility
|
|
73
|
+
- Content has role="tooltip"; a hidden copy is always in the page so the trigger is labelled/described before it opens.
|
|
74
|
+
- Keyboard focus opens it at once, Escape closes it without closing a dialog or popover under it, pressing the trigger closes it.
|
|
75
|
+
|
|
76
|
+
## DOM contract (for agents operating the page)
|
|
77
|
+
|
|
78
|
+
- Selector: `[data-sw="tooltip-trigger"], [data-sw="tooltip-content"][role="tooltip"]`
|
|
79
|
+
- `data-state`: open | closed (on the trigger when it is a plain tooltip trigger)
|
|
80
|
+
- `data-instant`: on the content when it opened without delay
|
|
81
|
+
- How to operate: Read the tip without opening it via the trigger's aria-describedby / aria-labelledby target. Hover or focus the trigger to show it. No agent bridge actions (it is a hint, not a control).
|
|
82
|
+
|
|
83
|
+
Related: `popover`, `hover-card`
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Tracker
|
|
2
|
+
|
|
3
|
+
> Status ticks over time, one per day or run (uptime, checks, job runs). Hover or use ←/→ to read a tick.
|
|
4
|
+
|
|
5
|
+
Category: charts · Status: beta · Slug: `tracker`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Tracker } from '@peerproblem/sw3-ui/charts'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Uptime or check history on a service tile.
|
|
13
|
+
- The outcome of each recent run of a job.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Continuous values. Use TrendChart.
|
|
17
|
+
- Fewer than about 14 ticks. A short list says it better.
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `items` * | `{ status: 'ok' \| 'degraded' \| 'down' \| 'none'; label: string }[]` | | One tick per period, oldest first. 30–90 read best. |
|
|
24
|
+
| `height` | `number` | `24` | Tick height in px. |
|
|
25
|
+
| `aria-label` * | `string` | | The summary, e.g. "API uptime, last 60 days: 99.94%". |
|
|
26
|
+
|
|
27
|
+
## Examples
|
|
28
|
+
|
|
29
|
+
### Uptime
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
<Tracker aria-label="API uptime, 60 days: 99.94%" items={days.map((d) => ({ status: d.ok ? 'ok' : 'down', label: `${d.date} · ${d.uptime}` }))} />
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Rules
|
|
36
|
+
- Status colors only: success, warning, danger, and muted for no data.
|
|
37
|
+
- Put the summary number (99.94%) in the tile header, not over the ticks.
|
|
38
|
+
|
|
39
|
+
## Accessibility
|
|
40
|
+
- role="img" named by the summary. It is focusable, ←/→ read ticks, and the active tick is announced.
|
|
41
|
+
|
|
42
|
+
## DOM contract (for agents operating the page)
|
|
43
|
+
|
|
44
|
+
- Selector: `[data-sw="tracker"]`
|
|
45
|
+
- `data-status`: on each tick
|
|
46
|
+
|
|
47
|
+
Related: `trend-chart`, `badge`
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Tree
|
|
2
|
+
|
|
3
|
+
> A hierarchy with expandable branches, folder/file icons and single or multiple selection (APG tree view).
|
|
4
|
+
|
|
5
|
+
Category: display · Status: beta · Slug: `tree`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Tree, type TreeItemData } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- File and folder browsers.
|
|
13
|
+
- Nested categories, org charts, outline navigation in docs.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Flat lists — use a Listbox or a table.
|
|
17
|
+
- Two levels of simple sections — use Accordion.
|
|
18
|
+
- Hiding everything behind deep nesting; flatten when you can.
|
|
19
|
+
|
|
20
|
+
## Props
|
|
21
|
+
|
|
22
|
+
| Prop | Type | Default | Description |
|
|
23
|
+
| --- | --- | --- | --- |
|
|
24
|
+
| `items` * | `{ id: string; label: string; children?: TreeItemData[]; icon?: ReactNode; disabled?: boolean; meta?: ReactNode }[]` | | The hierarchy. An item with `children` (even []) is a branch. |
|
|
25
|
+
| `aria-label` | `string` | | Names the tree, e.g. "Project files". Or aria-labelledby. |
|
|
26
|
+
| `multiple` | `boolean` | `false` | Several items can be selected; value becomes string[]. |
|
|
27
|
+
| `value` | `string \| null (string[] when multiple)` | | Selected id(s). Controlled. |
|
|
28
|
+
| `defaultValue` | `string \| null (string[] when multiple)` | | Initial selection. |
|
|
29
|
+
| `onValueChange` | `(value: string \| null) => void (string[] when multiple)` | | Called when the selection changes. |
|
|
30
|
+
| `expanded` | `string[]` | | Expanded branch ids. Controlled. |
|
|
31
|
+
| `defaultExpanded` | `string[]` | `[]` | Branches expanded at first. |
|
|
32
|
+
| `onExpandedChange` | `(expanded: string[]) => void` | | Called when branches expand or collapse. |
|
|
33
|
+
| `onAction` | `(id: string, item: TreeItemData) => void` | | Runs on press or Enter, e.g. open the file. |
|
|
34
|
+
| `selectionFollowsFocus` | `boolean` | `false` | Single mode: arrow keys select as they move. |
|
|
35
|
+
| `expandOnPress` | `boolean` | `true` | Pressing a branch row toggles it (the chevron always does). |
|
|
36
|
+
| `showIcons` | `boolean` | `true` | Folder / file icons. |
|
|
37
|
+
| `renderLabel` | `(item, { expanded, selected, level }) => ReactNode` | | Custom row content. |
|
|
38
|
+
| `size` | `'sm' \| 'md'` | `'md'` | 28 / 32px rows. |
|
|
39
|
+
| `disabled` | `boolean` | `false` | Disable every item (still focusable). |
|
|
40
|
+
| `framed` | `boolean` | `true` | Own 1px squircle frame with a 4px inset; rows are concentric with it. Set false inside a pane that already frames it. |
|
|
41
|
+
| `radius` | `RadiusToken \| number` | `'md'` | Frame radius. |
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
### File browser
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
const files: TreeItemData[] = [
|
|
49
|
+
{ id: 'src', label: 'src', children: [
|
|
50
|
+
{ id: 'src/agent.ts', label: 'agent.ts' },
|
|
51
|
+
{ id: 'src/tools', label: 'tools', children: [{ id: 'src/tools/search.ts', label: 'search.ts' }] },
|
|
52
|
+
] },
|
|
53
|
+
{ id: 'package.json', label: 'package.json' },
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
<Tree aria-label="Project files" items={files} defaultExpanded={['src']} defaultValue="src/agent.ts"
|
|
57
|
+
onAction={(id) => openFile(id)} />
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Multiple selection, controlled
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
const [picked, setPicked] = useState<string[]>([])
|
|
64
|
+
|
|
65
|
+
<Tree aria-label="Sources" items={sources} multiple value={picked} onValueChange={setPicked} />
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Rules
|
|
69
|
+
- Ids are unique across the whole tree (paths make good ids).
|
|
70
|
+
- Labels are plain text so typeahead works; use renderLabel for decoration.
|
|
71
|
+
- Framed by default — do not wrap it in a Card. Use framed={false} inside a Resizable pane or sidebar.
|
|
72
|
+
- Selected rows are a neutral fill + 500 weight; accent is only the focus ring and the multi-select check.
|
|
73
|
+
|
|
74
|
+
## Accessibility
|
|
75
|
+
- role="tree" > role="treeitem" (aria-level, aria-setsize, aria-posinset, aria-expanded on branches, aria-selected) > role="group".
|
|
76
|
+
- One tab stop. Up/Down move, Right expands or enters, Left collapses or goes to the parent, Home/End, * expands siblings, Alt+Right/Left expand/collapse all below, typing jumps.
|
|
77
|
+
- Enter selects and runs onAction; Space selects (toggles when multiple); Shift+Up/Down extends and Ctrl/Cmd+A selects all visible when multiple.
|
|
78
|
+
|
|
79
|
+
## DOM contract (for agents operating the page)
|
|
80
|
+
|
|
81
|
+
- Selector: `[data-sw="tree"]`
|
|
82
|
+
- `aria-expanded`: on branch [data-sw="tree-item"]
|
|
83
|
+
- `aria-selected`: on each [data-sw="tree-item"]
|
|
84
|
+
- `data-id`: the item id on each [data-sw="tree-item"]
|
|
85
|
+
- How to operate: Click the [data-sw="tree-item-label"] row inside [data-sw="tree-item"][data-id="…"]. Agent bridge: select(id), setValue(id | ids), expand(id), collapse(id), toggle(id); items = every node; state = { value, expanded, multiple }.
|
|
86
|
+
|
|
87
|
+
Related: `accordion`, `collapsible`
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Treemap
|
|
2
|
+
|
|
3
|
+
> Part-to-whole for many items, optionally grouped one level deep. Squircle tiles with concentric inner corners and HTML labels that fit the tile.
|
|
4
|
+
|
|
5
|
+
Category: charts · Status: beta · Slug: `treemap`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Treemap, ChartCard } from '@peerproblem/sw3-ui/charts'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- Comparing the size of many items (10–200) against a total.
|
|
13
|
+
- Showing which group holds most of a total, and what is inside each group.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- Fewer than 6 items — use DonutChart or BarChart.
|
|
17
|
+
- Values that can be negative.
|
|
18
|
+
- Change over time — use LineChart or AreaChart.
|
|
19
|
+
- More than one level of nesting.
|
|
20
|
+
|
|
21
|
+
## Props
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `data` * | `D[]` | | One row per leaf tile. |
|
|
26
|
+
| `value` * | `keyof D \| (d) => number` | | Tile size. Negative values count as 0. |
|
|
27
|
+
| `label` * | `keyof D \| (d) => string` | | Tile name. |
|
|
28
|
+
| `groupBy` | `keyof D \| (d) => string` | | Nests tiles into labelled, colored groups. Leave out for a flat treemap. |
|
|
29
|
+
| `groups` | `Array<{ key: string; label?: string; color?: string }>` | | Group order, labels and colors. Pass the same array to <ChartCard legend> so the legend matches. |
|
|
30
|
+
| `height` | `number` | `320` | Pixels. Width fills the parent. |
|
|
31
|
+
| `valueFormat` | `(v: number) => string` | `compact` | Formats tile, group and tooltip values. |
|
|
32
|
+
| `radius` | `RadiusToken \| number` | `'sm'` | Group corner radius. Tiles inside a group get radius − gap so the corners nest. |
|
|
33
|
+
| `gap` | `number` | `4` | Space between tiles and the group inset, px. |
|
|
34
|
+
| `tooltip` | `boolean` | `true` | Tooltip with value and share of total on hover and focus. |
|
|
35
|
+
| `onTileClick` | `(datum: D) => void` | | Makes leaf tiles buttons (keyboard operable). |
|
|
36
|
+
| `aria-label` | `string` | | The takeaway in one sentence. Always set it. |
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
40
|
+
### Grouped
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
const groups = [{ key: 'losing', label: 'Losing' }, { key: 'fighting', label: 'Fighting' }, { key: 'earning', label: 'Earning' }]
|
|
44
|
+
|
|
45
|
+
<ChartCard title="Putting billions in perspective" description="USD billions" legend={groups}>
|
|
46
|
+
<Treemap
|
|
47
|
+
aria-label="The financial crisis and COVID cost more than everything else combined"
|
|
48
|
+
data={rows}
|
|
49
|
+
value="billions"
|
|
50
|
+
label="name"
|
|
51
|
+
groupBy="category"
|
|
52
|
+
groups={groups}
|
|
53
|
+
valueFormat={(v) => `$${v.toLocaleString('en-US')}B`}
|
|
54
|
+
/>
|
|
55
|
+
</ChartCard>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Rules
|
|
59
|
+
- Wrap the chart in <ChartCard> and give the card a title.
|
|
60
|
+
- Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
|
|
61
|
+
- Use the default palette order; color 1 (blue) is the primary series.
|
|
62
|
+
- Max 5 series per chart. Do not use dual y-axes.
|
|
63
|
+
- Sort is automatic (largest top-left). Do not pre-sort or colour tiles by hand.
|
|
64
|
+
- Keep group labels short; tiles too small for a label still show it in the tooltip.
|
|
65
|
+
|
|
66
|
+
## DOM contract (for agents operating the page)
|
|
67
|
+
|
|
68
|
+
- Selector: `[data-sw="chart"][data-chart="treemap"]`
|
|
69
|
+
- `data-total`: sum of all values
|
|
70
|
+
- `aria-label`: the summary
|
|
71
|
+
- `data-tile / data-group / data-value`: on each leaf (.sw-treemap__leaf)
|
|
72
|
+
- How to operate: Read aria-label for the meaning and data-tile / data-value on leaves for the numbers. With onTileClick, leaves are buttons named "<name>, <value>, <group>".
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# TrendChart
|
|
2
|
+
|
|
3
|
+
> A small time-series chart for dashboard tiles and KPI cells. The fill fades to nothing, the line is 2px, the latest value gets a dot, a crosshair scrubs, and there are options for a previous period, a threshold, event markers and an unfinished last bucket.
|
|
4
|
+
|
|
5
|
+
Category: charts · Status: beta · Slug: `trend-chart`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { TrendChart } from '@peerproblem/sw3-ui/charts'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- One metric over time in a DashboardTile or a Card with a title: requests per hour, latency per day.
|
|
13
|
+
- The panel of `<Tabs variant="metric">`, plotting the selected KPI.
|
|
14
|
+
- Counts per bucket (`variant="bars"`), with a threshold line for an SLO.
|
|
15
|
+
|
|
16
|
+
## Avoid
|
|
17
|
+
- More than one main series, or several metrics with different units. Use LineChart/AreaChart from @peerproblem/sw3-ui/charts.
|
|
18
|
+
- Showing the previous period in a second color. `compare` draws it as a paler tint of the same hue.
|
|
19
|
+
- Flat fills with a hard bottom edge, default axes, or long draw-in animations. These are what make charts look generic.
|
|
20
|
+
|
|
21
|
+
## Props
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `values` * | `number[]` | | The series, oldest first. |
|
|
26
|
+
| `labels` | `string[]` | | Label per value. The x axis shows the first, the last and up to three between. |
|
|
27
|
+
| `compare` | `number[]` | | Previous period, drawn as a pale tint of the same hue. |
|
|
28
|
+
| `seriesLabels` | `[string, string]` | `['Now', 'Previous']` | Names in the tooltip. |
|
|
29
|
+
| `variant` | `'area' \| 'line' \| 'bars'` | `'area'` | Area: a fill that fades to 0. Bars: counts per bucket, with the latest bar at full strength. |
|
|
30
|
+
| `tone` | `'chart' \| 'neutral' \| 'success' \| 'warning' \| 'danger'` | `'chart'` | Color source. Use neutral ink for quiet tiles and status colors only for status. |
|
|
31
|
+
| `height` | `number` | `180 (spark 36)` | Keep tiles in a row the same height. |
|
|
32
|
+
| `spark` | `boolean` | `false` | No axes, grid or padding. The shape runs to the edges. |
|
|
33
|
+
| `incomplete` | `boolean` | `false` | The last bucket is still filling. Its segment is dashed so it does not read as a drop. |
|
|
34
|
+
| `threshold` | `{ value: number; label?: string }` | | Target or limit, drawn as a dashed warning line. With bars, bars above it take the warning color. |
|
|
35
|
+
| `markers` | `{ index: number; label: string }[]` | | Events (deploys, incidents) as ticks on the baseline, named in the tooltip. |
|
|
36
|
+
| `format` | `(n) => string` | `compact (1.2k)` | Value format for labels and the tooltip. |
|
|
37
|
+
| `onScrub` | `(index \| null) => void` | | Fires while scrubbing. Use it to rewrite the header number, Stripe style. |
|
|
38
|
+
| `live` | `boolean` | `false` | The latest dot pulses. For streaming data only. |
|
|
39
|
+
| `aria-label` * | `string` | | The takeaway in one sentence. |
|
|
40
|
+
|
|
41
|
+
## Examples
|
|
42
|
+
|
|
43
|
+
### Tile with the previous period, deploys and an unfinished hour
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
<DashboardTile id="requests" span={8} title="Requests" count="24h">
|
|
47
|
+
<TrendChart
|
|
48
|
+
aria-label="Requests peaked near 75k at 15:00, above yesterday"
|
|
49
|
+
values={today} compare={yesterday} seriesLabels={['Today', 'Yesterday']}
|
|
50
|
+
labels={hours} incomplete
|
|
51
|
+
markers={[{ index: 10, label: 'Deploy api@4.12.0' }]}
|
|
52
|
+
/>
|
|
53
|
+
</DashboardTile>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Scrub the header number
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
const [i, setI] = useState<number | null>(null)
|
|
60
|
+
<Card title="Requests" actions={<span>{fmt(values[i ?? values.length - 1])}</span>}>
|
|
61
|
+
<TrendChart aria-label="…" values={values} labels={hours} onScrub={setI} />
|
|
62
|
+
</Card>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Rules
|
|
66
|
+
- One question per chart. The tile title says what it measures.
|
|
67
|
+
- Area and bars start at 0. Line and spark zoom to the data.
|
|
68
|
+
- Animation runs once, on first mount, for about 500ms. Hover feedback stays at 100ms or less.
|
|
69
|
+
- Label the axis sparsely: at most 5 x labels, and 2–3 y values inside the plot.
|
|
70
|
+
|
|
71
|
+
## Accessibility
|
|
72
|
+
- role="img" named by aria-label. It is focusable: ←/→ step through points, Home/End jump, and each value is announced in a polite live region.
|
|
73
|
+
|
|
74
|
+
## DOM contract (for agents operating the page)
|
|
75
|
+
|
|
76
|
+
- Selector: `[data-sw="trend-chart"]`
|
|
77
|
+
- `data-variant`: area | line | bars
|
|
78
|
+
- `data-scrubbing`: present while a point is active
|
|
79
|
+
|
|
80
|
+
Related: `tabs`, `stat`, `dashboard-grid`, `bar-list`, `tracker`, `line-chart`
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Trigger Menu
|
|
2
|
+
|
|
3
|
+
> Suggestions at the caret when a trigger like @, / or # is typed in a textarea, input or Token Input; inserts the chosen item.
|
|
4
|
+
|
|
5
|
+
Category: inputs · Status: beta · Slug: `trigger-menu`
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { TriggerMenu, TriggerMenuInput } from '@peerproblem/sw3-ui'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
- @mentions, /commands and #tags inside a message or prompt box.
|
|
13
|
+
- Inside a `<TokenInput>` to insert chips instead of text.
|
|
14
|
+
|
|
15
|
+
## Avoid
|
|
16
|
+
- A standalone pick-one field — use Combobox.
|
|
17
|
+
- Search suggestions for a whole field — use Autocomplete.
|
|
18
|
+
|
|
19
|
+
## Props
|
|
20
|
+
|
|
21
|
+
| Prop | Type | Default | Description |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| `triggers` * | `Array<{ char: string; items?: ListEntry[] \| (query, signal) => ListEntry[] \| Promise<ListEntry[]>; type?: string; spaces?: boolean; maxLength?: number; boundary?: 'whitespace' \| 'any'; filter?; insert?(item) => string \| Token }>` | | What opens the menu and what it lists. A loader function is called per query (results not filtered again). `type` is the token kind inserted inside a TokenInput. |
|
|
24
|
+
| `onSelect` | `(value, { trigger, item }) => void` | | Runs after an item is inserted. |
|
|
25
|
+
| `onQueryChange / onOpenChange` | `(query, { trigger }) => void / (open) => void` | | Text after the trigger; open state. |
|
|
26
|
+
| `loading / emptyMessage / autoHighlight` | `boolean / ReactNode / boolean` | `false / "No matches" / true` | Loading row; empty text; highlight the first match so Enter/Tab choose it. |
|
|
27
|
+
| `TriggerMenuInput: value / defaultValue / onValueChange, multiline, label, invalid + textarea props` | `string, boolean = true` | | The squircle field (textarea, or a single-line input with multiline={false}). Leave it out inside a TokenInput. |
|
|
28
|
+
|
|
29
|
+
## Examples
|
|
30
|
+
|
|
31
|
+
### Mentions and commands in a textarea
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
<TriggerMenu triggers={[
|
|
35
|
+
{ char: '@', items: [{ value: 'ada', label: 'Ada' }, { value: 'grace', label: 'Grace' }] },
|
|
36
|
+
{ char: '/', items: [{ value: 'summarize', label: 'summarize' }, { value: 'translate', label: 'translate' }] },
|
|
37
|
+
]}>
|
|
38
|
+
<TriggerMenuInput aria-label="Message" placeholder="Type @ to mention, / for commands" />
|
|
39
|
+
</TriggerMenu>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Inside a Token Input
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
<TokenInput>
|
|
46
|
+
<TokenInputEditor aria-label="Prompt" placeholder="Ask anything — @ to add a file" />
|
|
47
|
+
<TriggerMenu triggers={[{ char: '@', type: 'file', items: files }]} />
|
|
48
|
+
</TokenInput>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Rules
|
|
52
|
+
- Default insertion is `char + label + space` in text fields, a token inside a TokenInput.
|
|
53
|
+
- Keep lists short (≤ 8 visible); use a loader for large sets.
|
|
54
|
+
|
|
55
|
+
## Accessibility
|
|
56
|
+
- Focus stays in the field; it gets aria-autocomplete="list", aria-haspopup, aria-controls and aria-activedescendant; an <input> is role="combobox" with aria-expanded.
|
|
57
|
+
- ArrowUp/Down move, Enter/Tab insert, Escape dismisses the match (typing on does not reopen it).
|
|
58
|
+
|
|
59
|
+
## DOM contract (for agents operating the page)
|
|
60
|
+
|
|
61
|
+
- Selector: `[data-sw="trigger-menu"]`
|
|
62
|
+
- `data-state`: 'open' | 'closed'
|
|
63
|
+
- `data-trigger`: the active trigger char
|
|
64
|
+
- `[data-sw="trigger-menu-item"]`: suggestions in the portaled [data-sw="trigger-menu-content"]
|
|
65
|
+
- How to operate: Type the trigger + query into [data-sw="trigger-menu-input"], then click a suggestion. Agent bridge (trigger-menu): select(valueOrLabel) while open, close(); items = current suggestions. (trigger-menu-input): setValue(text), clear().
|
|
66
|
+
|
|
67
|
+
Related: `token-input`, `combobox`, `autocomplete`
|