@peerproblem/sw3-ui 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -2
  3. package/agent/components/accordion.md +95 -0
  4. package/agent/components/action-square.md +106 -0
  5. package/agent/components/agent-bridge.md +87 -0
  6. package/agent/components/agent-console.md +123 -0
  7. package/agent/components/alert-dialog.md +82 -0
  8. package/agent/components/app-shell.md +105 -0
  9. package/agent/components/area-chart.md +56 -0
  10. package/agent/components/async-options.md +47 -0
  11. package/agent/components/autocomplete.md +69 -0
  12. package/agent/components/avatar.md +88 -0
  13. package/agent/components/badge.md +51 -0
  14. package/agent/components/bar-chart.md +56 -0
  15. package/agent/components/bar-list.md +49 -0
  16. package/agent/components/breadcrumbs.md +43 -0
  17. package/agent/components/button.md +109 -0
  18. package/agent/components/calendar.md +114 -0
  19. package/agent/components/canvas.md +105 -0
  20. package/agent/components/card.md +78 -0
  21. package/agent/components/carousel.md +113 -0
  22. package/agent/components/chart-card.md +41 -0
  23. package/agent/components/chart-surface.md +56 -0
  24. package/agent/components/checkbox.md +88 -0
  25. package/agent/components/citation-chip.md +61 -0
  26. package/agent/components/collapsible.md +69 -0
  27. package/agent/components/color-picker.md +82 -0
  28. package/agent/components/combobox.md +104 -0
  29. package/agent/components/command.md +92 -0
  30. package/agent/components/dashboard-grid.md +73 -0
  31. package/agent/components/date-input.md +87 -0
  32. package/agent/components/date-picker.md +122 -0
  33. package/agent/components/dialog.md +97 -0
  34. package/agent/components/donut-chart.md +50 -0
  35. package/agent/components/drawer.md +101 -0
  36. package/agent/components/empty-state.md +52 -0
  37. package/agent/components/field.md +80 -0
  38. package/agent/components/file-input.md +84 -0
  39. package/agent/components/hover-card.md +64 -0
  40. package/agent/components/image-cropper.md +77 -0
  41. package/agent/components/input.md +49 -0
  42. package/agent/components/label.md +53 -0
  43. package/agent/components/line-chart.md +60 -0
  44. package/agent/components/listbox.md +84 -0
  45. package/agent/components/map-view.md +104 -0
  46. package/agent/components/menu.md +117 -0
  47. package/agent/components/menubar.md +67 -0
  48. package/agent/components/meter.md +59 -0
  49. package/agent/components/navigation-menu.md +98 -0
  50. package/agent/components/number-input.md +81 -0
  51. package/agent/components/otp-input.md +67 -0
  52. package/agent/components/pagination.md +80 -0
  53. package/agent/components/password-input.md +67 -0
  54. package/agent/components/pill-button.md +116 -0
  55. package/agent/components/popover.md +85 -0
  56. package/agent/components/poster-card.md +61 -0
  57. package/agent/components/preferences.md +92 -0
  58. package/agent/components/progress.md +63 -0
  59. package/agent/components/provider.md +47 -0
  60. package/agent/components/radio.md +91 -0
  61. package/agent/components/rating.md +66 -0
  62. package/agent/components/reorder.md +61 -0
  63. package/agent/components/resizable.md +87 -0
  64. package/agent/components/scatter-chart.md +49 -0
  65. package/agent/components/scroll-area.md +81 -0
  66. package/agent/components/segmented-control.md +56 -0
  67. package/agent/components/select.md +130 -0
  68. package/agent/components/separator.md +60 -0
  69. package/agent/components/shortcuts.md +50 -0
  70. package/agent/components/sidebar-nav.md +68 -0
  71. package/agent/components/skeleton.md +58 -0
  72. package/agent/components/slider.md +79 -0
  73. package/agent/components/sparkline.md +39 -0
  74. package/agent/components/squircle.md +58 -0
  75. package/agent/components/stat.md +58 -0
  76. package/agent/components/switch.md +48 -0
  77. package/agent/components/table.md +58 -0
  78. package/agent/components/tabs.md +108 -0
  79. package/agent/components/textarea.md +68 -0
  80. package/agent/components/time-input.md +84 -0
  81. package/agent/components/timeline.md +91 -0
  82. package/agent/components/toast.md +85 -0
  83. package/agent/components/toggle.md +76 -0
  84. package/agent/components/token-input.md +66 -0
  85. package/agent/components/toolbar.md +76 -0
  86. package/agent/components/tooltip.md +83 -0
  87. package/agent/components/tracker.md +47 -0
  88. package/agent/components/tree.md +87 -0
  89. package/agent/components/treemap.md +72 -0
  90. package/agent/components/trend-chart.md +80 -0
  91. package/agent/components/trigger-menu.md +67 -0
  92. package/agent/components/typography.md +51 -0
  93. package/agent/components/waterfall.md +78 -0
  94. package/agent/components/week-schedule.md +113 -0
  95. package/agent/llms/actions-and-layout.txt +1749 -0
  96. package/agent/llms/agents.txt +505 -0
  97. package/agent/llms/charts.txt +778 -0
  98. package/agent/llms/dashboards.txt +457 -0
  99. package/agent/llms/extend.txt +132 -0
  100. package/agent/llms/extras.txt +527 -0
  101. package/agent/llms/forms.txt +2152 -0
  102. package/agent/llms/foundations.txt +674 -0
  103. package/agent/llms/hooks.txt +178 -0
  104. package/agent/llms/maps.txt +229 -0
  105. package/agent/llms/overlays-and-navigation.txt +1167 -0
  106. package/agent/llms-full.txt +8717 -0
  107. package/agent/llms.txt +145 -0
  108. package/agent/registry.json +11289 -0
  109. package/agent/tokens.md +66 -0
  110. package/dist/agent/index.d.ts +235 -0
  111. package/dist/agent/index.js +21 -0
  112. package/dist/card-Ipm-Cj5f.d.ts +490 -0
  113. package/dist/charts/index.d.ts +289 -0
  114. package/dist/charts/index.js +815 -0
  115. package/dist/check/cli.d.ts +1 -0
  116. package/dist/check/cli.js +48 -0
  117. package/dist/check/rendered.d.ts +11 -0
  118. package/dist/check/rendered.js +77 -0
  119. package/dist/check/source.d.ts +13 -0
  120. package/dist/check/source.js +182 -0
  121. package/dist/chunk-3DXBM65D.js +65 -0
  122. package/dist/chunk-3H5X4ZP6.js +55 -0
  123. package/dist/chunk-6XC4BC5C.js +92 -0
  124. package/dist/chunk-7H6TEAWD.js +507 -0
  125. package/dist/chunk-I63ZTJOI.js +1089 -0
  126. package/dist/chunk-JCIRUM4W.js +33 -0
  127. package/dist/chunk-LTBEHZ3P.js +25 -0
  128. package/dist/chunk-QDPPLO4U.js +60 -0
  129. package/dist/chunk-U2XFBPU4.js +56 -0
  130. package/dist/chunk-UY2WH5AY.js +681 -0
  131. package/dist/extras.d.ts +203 -0
  132. package/dist/extras.js +904 -0
  133. package/dist/icons-BJiGEAnU.d.ts +68 -0
  134. package/dist/index.d.ts +3737 -0
  135. package/dist/index.js +14477 -0
  136. package/dist/map/index.d.ts +115 -0
  137. package/dist/map/index.js +394 -0
  138. package/dist/meta/index.d.ts +3314 -0
  139. package/dist/meta/index.js +5106 -0
  140. package/dist/rules-1RIZ_JZr.d.ts +38 -0
  141. package/dist/styles.css +4037 -0
  142. package/dist/themes/calm.css +42 -0
  143. package/dist/themes/frost.css +40 -0
  144. package/package.json +142 -4
@@ -0,0 +1,58 @@
1
+ # Squircle
2
+
3
+ > Smoothed corners for any element. Use <Squircle> or combine useSquircle() with <SquircleLayers>.
4
+
5
+ Category: foundation · Status: stable · Slug: `squircle`
6
+
7
+ ```tsx
8
+ import { Squircle, useSquircle, SquircleLayers } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Building a new component that needs the system corner shape.
13
+ - Wrapping custom content (image, video) in a smoothed frame.
14
+
15
+ ## Avoid
16
+ - CSS border-radius on new surfaces — it will not match buttons and cards.
17
+ - Squircles on elements under ~20px tall; a plain pill is indistinguishable.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'md'` | Squircle corner radius (token or px). |
24
+ | `smoothing` | `'none' \| 'soft' \| 'max' \| number` | `'soft' (0.6)` | Corner smoothing from 0 to 1. SW3 uses 0.6 by default. |
25
+ | `borderWidth` | `number` | `1` | Border drawn inside the shape. Color via --sw-sq-border. |
26
+ | `clipContent` | `boolean` | `false` | Clip children to the shape. |
27
+ | `preserveSmoothing` | `boolean` | `true` | Keep smoothing when the radius must shrink. |
28
+
29
+ ## Examples
30
+
31
+ ### Framed image
32
+
33
+ ```tsx
34
+ <Squircle radius="xl" clipContent style={{ width: 320, height: 200 }}>
35
+ <img src="/cover.jpg" alt="" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />
36
+ </Squircle>
37
+ ```
38
+
39
+ ### Custom component
40
+
41
+ ```tsx
42
+ function Tile({ children }) {
43
+ const sq = useSquircle<HTMLDivElement>({ radius: 'lg' })
44
+ return (
45
+ <div ref={sq.ref} className="sw-sq" style={{ '--sw-sq-bg': 'var(--sw-muted)', padding: 16 } as React.CSSProperties}>
46
+ <SquircleLayers paths={sq.paths} radius={sq.radius} borderWidth={0} />
47
+ {children}
48
+ </div>
49
+ )
50
+ }
51
+ ```
52
+
53
+ ## Rules
54
+ - Colors are CSS variables on the host: --sw-sq-bg (fill), --sw-sq-border (stroke), --sw-sq-ring (focus ring). Change them in :hover/[data-state] selectors.
55
+
56
+ ## DOM contract (for agents operating the page)
57
+
58
+ - Selector: `[data-sw="squircle"], .sw-sq`
@@ -0,0 +1,58 @@
1
+ # Stat
2
+
3
+ > A KPI: mono label, big tabular number, colored delta, optional sparkline.
4
+
5
+ Category: display · Status: stable · Slug: `stat`
6
+
7
+ ```tsx
8
+ import { Stat } from '@peerproblem/sw3-ui'
9
+ import { Sparkline } from '@peerproblem/sw3-ui/charts'
10
+ ```
11
+
12
+ ## When to use
13
+ - Dashboard headline numbers.
14
+ - Map or chart overlays.
15
+
16
+ ## Avoid
17
+ - More than 4–5 stats in a row.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `size` | `'sm' \| 'md'` | `'md'` | md is the poster KPI (mono caps label, 32px number). sm is the dashboard metric: a sentence-case 13px label, a 24px tabular number, a tinted delta pill and no warning badge, so cells keep one height. |
24
+ | `caption` | `ReactNode` | | Context under the number, e.g. "vs last week". |
25
+ | `label` * | `ReactNode` | | Short name, rendered mono uppercase. |
26
+ | `value` * | `ReactNode` | | Pre-formatted number, e.g. "12.4k". |
27
+ | `delta` | `string` | | e.g. "+8%". A leading "-" makes it red. |
28
+ | `trend` | `'up' \| 'down' \| 'flat'` | | Override delta color. |
29
+ | `tone` | `'neutral' \| 'warning' \| 'success' \| 'danger'` | `'neutral'` | Colors the value independently of delta. Warning also shows a text badge. |
30
+ | `warningLabel` | `string` | `Warning` | Visible text for a warning, with support for translation or a more specific status. |
31
+ | `children` | `ReactNode` | | Visual under the number (Sparkline). |
32
+
33
+ ## Examples
34
+
35
+ ### With sparkline
36
+
37
+ ```tsx
38
+ <Stat label="Visitors" value="12.4k" delta="+8%">
39
+ <Sparkline data={[4, 8, 6, 9, 12, 10, 14]} />
40
+ </Stat>
41
+ ```
42
+
43
+ ### Capacity warning
44
+
45
+ ```tsx
46
+ <Stat label="Shelter occupancy" value="92%" delta="+8 pp" trend="up" tone="warning" warningLabel="Near capacity" />
47
+ ```
48
+
49
+ ## Rules
50
+ - A dashboard KPI row is `<Tabs variant="metric">` with one `<Stat size="sm">` per tab. The panel plots the chosen metric with a TrendChart. Do not add a spark under every number.
51
+
52
+ ## Accessibility
53
+ - Give warnings meaningful visible text so the status is readable without color. The delta keeps its own trend.
54
+
55
+ ## DOM contract (for agents operating the page)
56
+
57
+ - Selector: `[data-sw="stat"]`
58
+ - `data-tone`: neutral | warning | success | danger
@@ -0,0 +1,48 @@
1
+ # Switch
2
+
3
+ > An on/off toggle with a spring-animated thumb, optionally with label and description.
4
+
5
+ Category: inputs · Status: stable · Slug: `switch`
6
+
7
+ ```tsx
8
+ import { Switch } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Settings that apply immediately (notifications, features).
13
+
14
+ ## Avoid
15
+ - Actions that need a Save button — use a checkbox in a form.
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ | --- | --- | --- | --- |
21
+ | `checked` * | `boolean` | | Controlled state. |
22
+ | `onCheckedChange` * | `(checked: boolean) => void` | | Called on toggle. |
23
+ | `label` | `ReactNode` | | Renders a label row (label left, switch right). |
24
+ | `description` | `ReactNode` | | Quiet line under the label. |
25
+ | `size` | `'sm' \| 'md'` | `'md'` | Track 34 or 44px wide. |
26
+ | `disabled` | `boolean` | `false` | |
27
+
28
+ ## Examples
29
+
30
+ ### Settings list
31
+
32
+ ```tsx
33
+ <Switch label="Weekly digest" description="A summary of your week, every Monday." checked={digest} onCheckedChange={setDigest} />
34
+ <Switch label="Mentions" description="Only when someone mentions you." checked={mentions} onCheckedChange={setMentions} />
35
+ ```
36
+
37
+ ## Rules
38
+ - The track uses the smooth capsule curve and the thumb is circular.
39
+
40
+ ## Accessibility
41
+ - Native button with role="switch" and aria-checked.
42
+
43
+ ## DOM contract (for agents operating the page)
44
+
45
+ - Selector: `[data-sw="switch"]`
46
+ - `aria-checked`: true | false
47
+ - `data-state`: on | off
48
+ - How to operate: Click to toggle. The label is the <label for> of the button.
@@ -0,0 +1,58 @@
1
+ # Table
2
+
3
+ > Read structured rows and columns with sortable headers and keyboard-accessible horizontal scrolling.
4
+
5
+ Category: display · Status: beta · Slug: `table`
6
+
7
+ ```tsx
8
+ import { Table, type TableColumn, type TableRow } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Road closures, inventories, reports and other data with shared column headers.
13
+
14
+ ## Avoid
15
+ - Page layout or spreadsheet-style cell editing.
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ | --- | --- | --- | --- |
21
+ | `caption` * | `string` | | Visible name for the table and its scroll region. |
22
+ | `columns` * | `readonly TableColumn[]` | | Ordered columns with unique ids, labels, optional end alignment, and optional row headers. |
23
+ | `rows` * | `readonly TableRow[]` | | Rows with stable ids and ReactNode cells keyed by column id. |
24
+ | `TableColumn.compare` | `(a: TableRow, b: TableRow) => number` | | Compare underlying values to make a column sortable. |
25
+ | `sort / defaultSort` | `TableSort \| null` | | Controlled or initial order with columnId and direction. |
26
+ | `onSortChange` | `(sort: TableSort) => void` | | Runs on sort header activation. |
27
+ | `emptyMessage` | `ReactNode` | `No rows` | Content shown in a full-width cell when there are no rows. |
28
+
29
+ ## Examples
30
+
31
+ ### Road closures
32
+
33
+ ```tsx
34
+ <Table
35
+ caption="Road closures"
36
+ columns={[
37
+ { id: 'road', label: 'Road', rowHeader: true },
38
+ { id: 'status', label: 'Status' },
39
+ ]}
40
+ rows={[{ id: 'espoo-1', cells: { road: 'Ring I', status: 'One lane closed' } }]}
41
+ emptyMessage="No closures reported"
42
+ />
43
+ ```
44
+
45
+ ## Rules
46
+ - Provide a descriptive caption and clear column labels. Use end alignment for comparable figures.
47
+
48
+ ## Accessibility
49
+ - Native caption, column headers and optional row headers preserve table navigation for screen readers.
50
+ - When the table overflows horizontally, Tab enters the named scroll region. Left and Right scroll it, and Tab continues to links, buttons or the next part of the page.
51
+
52
+ ## DOM contract (for agents operating the page)
53
+
54
+ - Selector: `[data-sw="table"]`
55
+ - `tabindex="0"`: on [data-sw="table-viewport"] when the table overflows horizontally
56
+ - How to operate: Read rows and headers from the native table. Agent bridge state includes rowCount and columnCount. Operate links and buttons in cells through their own bindings.
57
+
58
+ Related: `scroll-area`, `badge`
@@ -0,0 +1,108 @@
1
+ # Tabs
2
+
3
+ > A list of tabs with a sliding indicator, each showing one panel. Automatic or manual activation, horizontal or vertical.
4
+
5
+ Category: navigation · Status: beta · Slug: `tabs`
6
+
7
+ ```tsx
8
+ import { Tabs, TabsList, Tab, TabsPanel } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Switching between peer views of the same object (Overview / Logs / Settings).
13
+ - Keeping a long settings page in sections without leaving the page.
14
+
15
+ ## Avoid
16
+ - Picking a value for a form or filter — use SegmentedControl (a radio group).
17
+ - Sequential steps — use a stepper or wizard.
18
+ - Site-wide navigation between pages — use NavigationMenu or links.
19
+ - Many tabs that overflow on phones without thought — keep labels short; the list scrolls horizontally.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `variant: 'metric'` | `variant` | | Equal-width cells, each holding a `<Stat size="sm">`, with a full-width indicator. The panel plots the selected metric. This is the KPI row of a dashboard (the Plausible / Vercel Analytics pattern). |
26
+ | `items` | `{ value: string; label: ReactNode; content: ReactNode; icon?: ReactNode; disabled?: boolean }[]` | | Shorthand: render the list and panels from data. Pass aria-label for the list. |
27
+ | `value` | `string \| null` | | Selected tab. Controlled. |
28
+ | `defaultValue` | `string \| null` | `first enabled tab` | Tab selected at first. |
29
+ | `onValueChange` | `(value: string) => void` | | Called when a tab is selected. |
30
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout and which arrow keys move. |
31
+ | `activation` | `'automatic' \| 'manual'` | `'automatic'` | automatic selects on arrow focus; manual waits for Enter/Space (use when panels are slow to render). |
32
+ | `loop` | `boolean` | `true` | Arrow keys wrap. |
33
+ | `variant` | `'line' \| 'pill'` | `'line'` | line = underline indicator on a hairline; pill = muted track with a sliding squircle pill. |
34
+ | `size` | `'sm' \| 'md'` | `'md'` | Tab height 32 / 40px. |
35
+ | `keepMounted` | `boolean` | `false` | Keep hidden panels mounted. |
36
+ | `aria-label` | `string` | | With items: names the tab list. |
37
+ | `TabsList.aria-label` | `string` | | Names the list when there is no visible heading. |
38
+ | `Tab.value` * | `string` | | Pairs the tab with the TabsPanel of the same value. |
39
+ | `Tab.disabled` | `boolean` | | Focusable but not selectable (aria-disabled). |
40
+ | `Tab.icon` | `ReactNode` | | Icon before the label. |
41
+ | `TabsPanel.value` * | `string` | | The tab this panel belongs to. |
42
+ | `TabsPanel.keepMounted` | `boolean` | | Override keepMounted for one panel. |
43
+
44
+ ## Examples
45
+
46
+ ### From data
47
+
48
+ ```tsx
49
+ <Tabs
50
+ aria-label="Deployment"
51
+ items={[
52
+ { value: 'overview', label: 'Overview', content: <Text>Ready · 2m ago</Text> },
53
+ { value: 'logs', label: 'Logs', content: <Text>Build finished in 41s.</Text> },
54
+ { value: 'settings', label: 'Settings', content: <Text>Region: fra1</Text> },
55
+ ]}
56
+ />
57
+ ```
58
+
59
+ ### Parts, controlled, pill variant
60
+
61
+ ```tsx
62
+ const [tab, setTab] = useState('runs')
63
+
64
+ <Tabs value={tab} onValueChange={setTab} variant="pill">
65
+ <TabsList aria-label="Agent">
66
+ <Tab value="runs">Runs</Tab>
67
+ <Tab value="tools">Tools</Tab>
68
+ <Tab value="memory" disabled>Memory</Tab>
69
+ </TabsList>
70
+ <TabsPanel value="runs">…</TabsPanel>
71
+ <TabsPanel value="tools">…</TabsPanel>
72
+ <TabsPanel value="memory">…</TabsPanel>
73
+ </Tabs>
74
+ ```
75
+
76
+ ### Vertical, manual activation
77
+
78
+ ```tsx
79
+ <Tabs orientation="vertical" activation="manual" defaultValue="general">
80
+ <TabsList aria-label="Settings">
81
+ <Tab value="general">General</Tab>
82
+ <Tab value="members">Members</Tab>
83
+ </TabsList>
84
+ <TabsPanel value="general">…</TabsPanel>
85
+ <TabsPanel value="members">…</TabsPanel>
86
+ </Tabs>
87
+ ```
88
+
89
+ ## Rules
90
+ - Labels are one or two words.
91
+ - Every Tab has a TabsPanel with the same value.
92
+ - Use 2–7 tabs; beyond that, use a select or a side navigation.
93
+
94
+ ## Accessibility
95
+ - role="tablist" / "tab" / "tabpanel" with aria-selected, aria-controls and aria-labelledby.
96
+ - One tab stop (roving tabindex). Arrow keys move along the orientation, Home/End jump; Enter/Space select in manual mode.
97
+ - Disabled tabs stay focusable with aria-disabled, as the pattern asks.
98
+
99
+ ## DOM contract (for agents operating the page)
100
+
101
+ - Selector: `[data-sw="tabs"]`
102
+ - `aria-selected`: true on the selected [data-sw="tabs-tab"]
103
+ - `data-state`: active | inactive on tabs and panels
104
+ - `data-value`: each tab's and panel's value
105
+ - `data-orientation`: horizontal | vertical
106
+ - How to operate: Click the [data-sw="tabs-tab"] whose text matches. Agent bridge: setValue(value), select(value); items = tabs; state = { value, orientation }.
107
+
108
+ Related: `segmented-control`, `navigation-menu`, `accordion`
@@ -0,0 +1,68 @@
1
+ # Textarea
2
+
3
+ > Multi-line text field that grows with its content between minRows and maxRows, with an optional character count.
4
+
5
+ Category: inputs · Status: beta · Slug: `textarea`
6
+
7
+ ```tsx
8
+ import { Textarea } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Prompts, messages, descriptions, notes — anything longer than one line.
13
+ - Chat composers: `submitShortcut="enter"` + `onSubmitShortcut`.
14
+
15
+ ## Avoid
16
+ - Single-line values (names, emails) — use Input.
17
+ - A fixed huge height — let it autosize with `minRows`/`maxRows`.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `value` | `string` | | Controlled text. |
24
+ | `defaultValue` | `string` | | Initial text when uncontrolled. |
25
+ | `onValueChange` | `(value: string) => void` | | Called on every edit. |
26
+ | `autoResize` | `boolean` | `true` | Grow and shrink with the text. |
27
+ | `minRows` | `number` | `3` | Rows when empty. |
28
+ | `maxRows` | `number` | | Stop growing and scroll after this many rows. |
29
+ | `showCount` | `boolean` | `false` | Show "count / maxLength" under the field. Set `maxLength` to enforce the limit. |
30
+ | `submitShortcut` | `'enter' \| 'mod+enter'` | | Keys that submit. `enter` keeps Shift+Enter for new lines. |
31
+ | `onSubmitShortcut` | `(value: string) => void` | | Runs on the shortcut; without it the surrounding form submits. |
32
+ | `label` | `ReactNode` | | Visible label. Inside `<Field>`, give the label to the Field instead. |
33
+ | `hint` | `ReactNode` | | Help text under the field. |
34
+ | `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
35
+ | `invalid` | `boolean` | | Invalid without a message (a surrounding Field sets it too). |
36
+ | `disabled / required / readOnly` | `boolean` | | Native states. Inherit from a surrounding Field. |
37
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
38
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| number` | `'sm'` | Squircle corner radius of the field frame. |
39
+ | `...rest` | `TextareaHTMLAttributes` | | placeholder, maxLength, name, onChange… |
40
+
41
+ ## Examples
42
+
43
+ ### Prompt with count
44
+
45
+ ```tsx
46
+ <Textarea label="System prompt" placeholder="You are a helpful agent…" maxLength={500} showCount minRows={3} maxRows={8} />
47
+ ```
48
+
49
+ ### Chat composer
50
+
51
+ ```tsx
52
+ <Textarea aria-label="Message" minRows={1} maxRows={6} submitShortcut="enter" onSubmitShortcut={(text) => send(text)} />
53
+ ```
54
+
55
+ ## Rules
56
+ - Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
57
+
58
+ ## Accessibility
59
+ - Native <textarea>. The count is aria-live="polite".
60
+
61
+ ## DOM contract (for agents operating the page)
62
+
63
+ - Selector: `[data-sw="textarea"] textarea`
64
+ - `aria-invalid`: true on error
65
+ - `data-full`: on [data-sw="textarea-count"] when at maxLength
66
+ - How to operate: Type into the <textarea>. Agent bridge: setValue(text), clear().
67
+
68
+ Related: `input`, `field`
@@ -0,0 +1,84 @@
1
+ # TimeInput
2
+
3
+ > Segmented time entry — hour, minute, optional second and AM/PM on 12-hour locales. Value is 24-hour ISO "HH:mm".
4
+
5
+ Category: dates · Status: beta · Slug: `time-input`
6
+
7
+ ```tsx
8
+ import { TimeInput } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A time of day: a meeting start, a cron run time, opening hours.
13
+
14
+ ## Avoid
15
+ - Durations ("2h 30m") → use a number input.
16
+ - Converting the value to 12-hour yourself → the value is always 24-hour "HH:mm"; the display follows the locale.
17
+
18
+ ## Props
19
+
20
+ | Prop | Type | Default | Description |
21
+ | --- | --- | --- | --- |
22
+ | `value` | `string \| null` | | 24-hour time "14:30" ("14:30:15" with seconds). Null until complete. Pass to control. |
23
+ | `defaultValue` | `string \| null` | `null` | Initial value (restored on form reset). |
24
+ | `onValueChange` | `(value: string \| null) => void` | | Runs with the time once complete, null when cleared. |
25
+ | `granularity` | `'minute' \| 'second'` | `'minute'` | Smallest unit shown. |
26
+ | `hourCycle` | `12 \| 24` | `locale's` | Clock to show. |
27
+ | `min` | `string ("HH:mm")` | | Earliest valid time; earlier marks it invalid. |
28
+ | `max` | `string ("HH:mm")` | | Latest valid time. |
29
+ | `locale` | `string` | `page lang, then browser` | Locale for separators, clock and AM/PM labels. |
30
+ | `label` | `ReactNode` | | Visible label. Omit inside <Field> (the Field labels it) or pass aria-label. |
31
+ | `hint` | `ReactNode` | | Help text under the field. |
32
+ | `error` | `ReactNode` | | Error text; also marks the field invalid. |
33
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
34
+ | `inline` | `boolean` | `false` | Shrink the box to its content. By default it fills the width, like Input. |
35
+ | `disabled` | `boolean` | `false` | Cannot be focused or changed. |
36
+ | `readOnly` | `boolean` | `false` | Value is visible but cannot change. |
37
+ | `required` | `boolean` | `false` | Blocks form submit while empty. |
38
+ | `invalid` | `boolean` | | Force the invalid look (also set automatically when out of range). |
39
+ | `name` | `string` | | Submits the ISO value under this name through a hidden input. |
40
+ | `form` | `string` | | id of the form it belongs to when outside it. |
41
+ | `aria-label` | `string` | | Accessible name when there is no visible label. |
42
+ | `suffix` | `ReactNode` | | Content inside the box after the segments. |
43
+
44
+ ## Examples
45
+
46
+ ### Meeting time
47
+
48
+ ```tsx
49
+ <TimeInput label="Starts at" name="start" defaultValue="09:30" />
50
+ ```
51
+
52
+ ### 24-hour with seconds
53
+
54
+ ```tsx
55
+ <TimeInput aria-label="Run at" hourCycle={24} granularity="second" defaultValue="02:00:00" />
56
+ ```
57
+
58
+ ### Date + time together
59
+
60
+ ```tsx
61
+ <div style={{ display: 'flex', gap: 8 }}>
62
+ <DatePicker aria-label="Date" value={date} onValueChange={setDate} />
63
+ <TimeInput aria-label="Time" value={time} onValueChange={setTime} />
64
+ </div>
65
+ ```
66
+
67
+ ## Rules
68
+ - Value is 24-hour regardless of the displayed clock.
69
+ - The AM/PM segment reserves room for the wider localized label.
70
+ - Pair with DatePicker for a date-time; keep both values as ISO strings.
71
+
72
+ ## Accessibility
73
+ - Root is role="group"; each unit is role="spinbutton" ("hour", "minute", "AM/PM") with aria-valuenow/min/max/valuetext.
74
+ - Same keys as DateInput; on the AM/PM segment, A or P chooses (also the first letter of localized labels), ↑/↓ toggles.
75
+
76
+ ## DOM contract (for agents operating the page)
77
+
78
+ - Selector: `[data-sw="time-input"]`
79
+ - `data-invalid`: outside min/max or error
80
+ - `[data-sw="time-input-segment"][data-type]`: hour | minute | second | dayPeriod
81
+ - `input[name] (hidden)`: 24-hour value submitted with the form
82
+ - How to operate: Focus the hour segment and type e.g. 0230 then P. Agent bridge: setValue("HH:mm"), clear(); state = { value, min, max, disabled, readOnly, invalid }.
83
+
84
+ Related: `date-input`, `date-picker`
@@ -0,0 +1,91 @@
1
+ # Timeline
2
+
3
+ > Dated events in order — activity feeds, changelogs, run or order progress — with complete/current/upcoming markers and one tab stop that arrow keys move.
4
+
5
+ Category: display · Status: beta · Slug: `timeline`
6
+
7
+ ```tsx
8
+ import { Timeline, TimelineItem, TimelineMarker, TimelineConnector, TimelineContent, TimelineTitle, TimelineTime, TimelineDescription } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - An activity feed or audit log.
13
+ - Progress of a multi-step process (agent run, order, deploy) with `status`.
14
+ - A roadmap or changelog: `orientation="horizontal"`.
15
+
16
+ ## Avoid
17
+ - A step-by-step form wizard the user drives. Use a Stepper/Tabs instead; Timeline is a record, not navigation.
18
+ - Tables of events with many columns. Use a Table; Timeline is for title + time + short description.
19
+ - Timing data (durations, overlaps). Use Waterfall.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `items` | `{ value?, title, time?, dateTime?, description?, status?, importance?, icon?, content? }[]` | | Shorthand: one event per entry. |
26
+ | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Vertical feed or horizontal roadmap. Changes the arrow keys too. |
27
+ | `loop` | `boolean` | `true` | Arrow keys wrap from last to first. |
28
+ | `size` | `'sm' \| 'md'` | `'md'` | Marker 14 / 22px. |
29
+ | `aria-label` * | `string` | | Names the list, e.g. "Deploy activity". |
30
+ | `TimelineItem.status` | `'complete' \| 'current' \| 'upcoming'` | | current sets aria-current="step" and takes the tab stop first. |
31
+ | `TimelineItem.importance` | `'normal' \| 'high'` | `'normal'` | High importance adds a visible label independently of status. |
32
+ | `TimelineItem.value` | `string` | | Names the event (generated when omitted). |
33
+ | `TimelineMarker.children` | `ReactNode` | | Icon or tiny avatar inside the marker; default is a dot (check when complete). |
34
+ | `TimelineTime.dateTime` | `string` | | Machine-readable time; the text stays friendly. |
35
+
36
+ ## Examples
37
+
38
+ ### Run progress
39
+
40
+ ```tsx
41
+ <Timeline aria-label="Run #4821" items={[
42
+ { title: 'Queued', time: '14:02', status: 'complete' },
43
+ { title: 'Running tests', time: '14:03', description: '128 of 412 passed', status: 'current' },
44
+ { title: 'Deploy', time: 'Pending', status: 'upcoming' },
45
+ ]} />
46
+ ```
47
+
48
+ ### Compound parts
49
+
50
+ ```tsx
51
+ <Timeline aria-label="Activity">
52
+ <TimelineItem>
53
+ <TimelineMarker />
54
+ <TimelineConnector />
55
+ <TimelineContent>
56
+ <TimelineTitle>Deployed to production</TimelineTitle>
57
+ <TimelineTime dateTime="2026-11-10T14:32">2:32 PM</TimelineTime>
58
+ <TimelineDescription>Version 2.4.1 is live.</TimelineDescription>
59
+ </TimelineContent>
60
+ </TimelineItem>
61
+ </Timeline>
62
+ ```
63
+
64
+ ### Roadmap
65
+
66
+ ```tsx
67
+ <Timeline aria-label="Roadmap" orientation="horizontal" size="sm" items={[
68
+ { title: 'v2.4', time: 'Nov', status: 'complete' },
69
+ { title: 'v2.5', time: 'Dec', status: 'current' },
70
+ { title: 'v3.0', time: 'Jan', status: 'upcoming' },
71
+ ]} />
72
+ ```
73
+
74
+ ## Rules
75
+ - Order events consistently (newest first for feeds, chronological for processes) and keep one `current` at most.
76
+ - Keep titles short; put detail in the description, and links/buttons in `content`.
77
+ - The accent appears only on the current marker.
78
+
79
+ ## Accessibility
80
+ - role="list" of role="listitem" events; each event is named by its title and described by its time and description.
81
+ - One tab stop: the current event, else the first, then the last focused. Up/Down (Left/Right when horizontal), Home/End move; Tab enters links inside an event.
82
+
83
+ ## DOM contract (for agents operating the page)
84
+
85
+ - Selector: `[data-sw="timeline"]`
86
+ - `data-orientation`: 'vertical' | 'horizontal'
87
+ - `data-status (item)`: 'complete' | 'current' | 'upcoming'
88
+ - `aria-current="step"`: the current event
89
+ - How to operate: Display only. Read events from [data-sw="timeline-item"] (title in [data-sw="timeline-title"], time in time[datetime]).
90
+
91
+ Related: `waterfall`, `avatar`, `badge`
@@ -0,0 +1,85 @@
1
+ # Toast
2
+
3
+ > Imperative notifications — `toast("Saved")` — stacked in a <Toaster/> host: actions, promise states, pause on hover, swipe to dismiss, announced politely.
4
+
5
+ Category: display · Status: beta · Slug: `toast`
6
+
7
+ ```tsx
8
+ import { Toaster, OverlayHost, toast } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Confirming something finished: saved, deployed, copied.
13
+ - Offering Undo after an action.
14
+ - Progress of an async task: toast.promise(run(), { loading, success, error }).
15
+
16
+ ## Avoid
17
+ - Errors the user must fix in a form → show them inline (Field / Input error).
18
+ - Questions that need an answer → use AlertDialog / confirm().
19
+ - Long text or several actions → use a Dialog or an inline banner.
20
+ - Mounting several <Toaster/>s — place exactly one (or one <OverlayHost/>).
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Default | Description |
25
+ | --- | --- | --- | --- |
26
+ | `toast(title, options?)` | `(title: ReactNode, o?: ToastOptions) => string` | | Show a toast; returns its id. Also toast.success / toast.danger (alias toast.error) / toast.loading. |
27
+ | `options.description` | `ReactNode` | | Second line. |
28
+ | `options.variant` | `'default' \| 'success' \| 'danger' \| 'loading'` | `'default'` | Icon + announcement priority (danger is assertive). loading stays until updated. |
29
+ | `options.duration` | `number` | `5000` | ms; Infinity keeps it until dismissed. Pauses while hovered/focused or the tab is hidden. |
30
+ | `options.action` | `{ label: ReactNode; onClick?: (e) => unknown \| Promise<unknown> }` | | One button, e.g. Undo. A returned Promise shows loading; the toast closes when it resolves. |
31
+ | `options.cancel` | `{ label: ReactNode; onClick?: () => void }` | | A quiet button that just closes it. |
32
+ | `options.id` | `string` | | Reuse to update a showing toast in place. |
33
+ | `options.dismissible` | `boolean` | `true` | Whether swipe, Escape and × can close it. |
34
+ | `options.onDismiss` | `(id: string) => void` | | Called once it closes. |
35
+ | `toast.promise(p, { loading, success, error })` | `(Promise \| () => Promise, messages) => string` | | Loading toast that becomes success/danger. Messages: ReactNode, { title, description, action }, or a function of the result/error. |
36
+ | `toast.update(id, patch) / toast.dismiss(id?)` | `functions` | | Change a showing toast; dismiss one or all. |
37
+ | `Toaster.side / align` | `'top' \| 'bottom' / 'start' \| 'center' \| 'end'` | `'bottom' / 'end'` | Corner of the viewport. Full width on phones. |
38
+ | `Toaster.maxVisible` | `number` | `3` | Shown at once; the rest wait with timers stopped. |
39
+ | `Toaster.expanded` | `boolean` | `false` | Keep the stack expanded (otherwise it expands on hover/focus). |
40
+ | `Toaster.duration` | `number` | `5000` | Default duration. |
41
+ | `Toaster.closeButton` | `boolean` | `true` | Show × on dismissible toasts, as a small badge on the top-left corner (on hover/focus; always on touch). It never takes space from the text. |
42
+ | `Toaster.shortcut` | `string \| null` | `'F6'` | Key that moves focus to the newest toast and back. |
43
+ | `OverlayHost` | `ToasterProps` | | <Toaster/> + <ConfirmHost/> in one — the host for toast() and confirm(). |
44
+
45
+ ## Examples
46
+
47
+ ### Host + simple toasts
48
+
49
+ ```tsx
50
+ // once, near the root
51
+ <OverlayHost />
52
+
53
+ toast('Prompt copied')
54
+ toast.success('Deployed to production', { description: 'v42 · 18s' })
55
+ toast('Run archived', { action: { label: 'Undo', onClick: () => restore(runId) } })
56
+ ```
57
+
58
+ ### Promise
59
+
60
+ ```tsx
61
+ toast.promise(api.deploy(), {
62
+ loading: 'Deploying…',
63
+ success: (r) => ({ title: 'Deployed', description: r.url }),
64
+ error: (e) => ({ title: 'Deploy failed', description: String(e), action: { label: 'Retry', onClick: deploy } }),
65
+ })
66
+ ```
67
+
68
+ ## Rules
69
+ - Title ≤ ~6 words, past tense ("Changes saved"); description optional, one line.
70
+ - At most one action; prefer Undo over asking first.
71
+ - Use danger only for failures; don’t toast every success.
72
+
73
+ ## Accessibility
74
+ - Messages are announced once through hidden aria-live regions (polite; assertive for danger) without moving focus.
75
+ - The region is a landmark named "Notifications". F6 moves focus to the newest toast and back; Escape dismisses the focused toast. Timers pause while hovered or focused.
76
+
77
+ ## DOM contract (for agents operating the page)
78
+
79
+ - Selector: `[data-sw="toaster"] [data-sw="toast"]`
80
+ - `data-variant`: default | success | danger | loading
81
+ - `data-front`: newest toast
82
+ - `data-expanded`: on the region while expanded
83
+ - How to operate: Read titles from [data-sw="toast-title"]. Click [data-sw="toast-action"] or [data-sw="toast-close"]. Agent bridge (kind "toaster"): items = visible toasts {value: id, label}; action dismiss(id?) (no id = all).
84
+
85
+ Related: `alert-dialog`, `dialog`