@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,59 @@
1
+ # Meter
2
+
3
+ > A value in a known range (storage, quota, score), coloured good / so-so / bad from low, high and optimum like a native <meter>.
4
+
5
+ Category: display · Status: beta · Slug: `meter`
6
+
7
+ ```tsx
8
+ import { Meter } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Usage against a limit: tokens, storage, seats.
13
+ - A score where some range is better than others.
14
+
15
+ ## Avoid
16
+ - Task progress over time — use Progress.
17
+ - Colour without a label — always pass `label` (or aria-label) and keep showValue.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `value` * | `number` | | The reading. |
24
+ | `min / max` | `number` | `0 / 100` | Range. |
25
+ | `low / high` | `number` | | Region boundaries. |
26
+ | `optimum` | `number` | | Best value. Without low/high/optimum the bar is neutral ink. Regions colour as --sw-success / --sw-warning / --sw-danger. |
27
+ | `label` | `ReactNode` | | Visible name. |
28
+ | `showValue` | `boolean` | `true` | Formatted value at the right. |
29
+ | `formatOptions` | `Intl.NumberFormatOptions` | `{ style: 'percent' }` | Percent shows position in the range; other styles format the value (e.g. unit: gigabyte). |
30
+ | `locale` | `string` | | Formatting locale. |
31
+ | `getValueLabel` | `(value, formatted) => string` | | Screen-reader text, e.g. "42 of 50 GB". |
32
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Bar 4 / 6 / 10px. |
33
+
34
+ ## Examples
35
+
36
+ ### Quota (lower is better)
37
+
38
+ ```tsx
39
+ <Meter label="Token budget" value={82} low={60} high={90} optimum={0} />
40
+ ```
41
+
42
+ ### Units
43
+
44
+ ```tsx
45
+ <Meter label="Storage" value={42} max={50} formatOptions={{ style: 'unit', unit: 'gigabyte' }}
46
+ getValueLabel={(v) => `${v} of 50 GB used`} />
47
+ ```
48
+
49
+ ## Accessibility
50
+ - role="meter" with aria-valuenow/min/max/valuetext; named by its label.
51
+
52
+ ## DOM contract (for agents operating the page)
53
+
54
+ - Selector: `[data-sw="meter"]`
55
+ - `aria-valuenow`: clamped value
56
+ - `data-state`: neutral | optimum | suboptimum | critical
57
+ - How to operate: Read-only. Agent bridge state: value, min, max, state.
58
+
59
+ Related: `progress`, `stat`
@@ -0,0 +1,98 @@
1
+ # NavigationMenu
2
+
3
+ > Site navigation: a row of triggers that open panels of links on hover or press, plus plain top-level links.
4
+
5
+ Category: navigation · Status: beta · Slug: `navigation-menu`
6
+
7
+ ```tsx
8
+ import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - The header of a marketing site or docs with grouped destinations (Products, Resources).
13
+ - A few top-level sections, each with 2–8 links.
14
+
15
+ ## Avoid
16
+ - Actions (Save, Delete) — use Menu; this is for links.
17
+ - Switching views inside a page — use Tabs.
18
+ - Deep, multi-level trees — use Tree or a side navigation.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `aria-label` * | `string` | | Names the <nav> landmark, e.g. "Main". |
25
+ | `items` | `{ label; value?; href?; current?; columns?: 1 \| 2; links?: { label; href; description?; icon?; current? }[] }[]` | | Shorthand: items with `links` get a trigger + panel; items with `href` are plain links. |
26
+ | `value` | `string \| null` | | The open item; null = closed. Controlled. |
27
+ | `defaultValue` | `string \| null` | `null` | Open item at first. |
28
+ | `onValueChange` | `(value: string \| null) => void` | | Called when a panel opens, switches or closes. |
29
+ | `openOnHover` | `boolean` | `true` | Open when the mouse rests on a trigger. Pressing always works; false = click-only. |
30
+ | `delay` | `number` | `120` | Hover delay before opening (ms). Moving between triggers while open switches at once. |
31
+ | `closeDelay` | `number` | `200` | Delay before closing after the pointer leaves (ms). |
32
+ | `closeOnSelect` | `boolean` | `true` | Close when a link is pressed. |
33
+ | `NavigationMenuItem.value` | `string` | | Identifies the item. Generated when omitted. |
34
+ | `NavigationMenuTrigger` | `ButtonHTMLAttributes` | | The button that opens the item's panel. |
35
+ | `NavigationMenuContent.columns` | `1 \| 2` | `1` | Link grid columns (2 collapses to 1 on phones). |
36
+ | `NavigationMenuContent.keepMounted` | `boolean` | | Keep the links in the DOM (hidden) while closed, for crawlers. |
37
+ | `NavigationMenuLink.href` * | `string` | | Destination. |
38
+ | `NavigationMenuLink.current` | `boolean` | | Marks the current page (aria-current="page"). |
39
+ | `NavigationMenuLink.description` | `ReactNode` | | One short line under the label (in panels). |
40
+ | `NavigationMenuLink.icon` | `ReactNode` | | Bare 16px icon before the label (in panels), muted until hover. |
41
+ | `NavigationMenuLink.closeOnSelect` | `boolean` | | Override closeOnSelect for one link. |
42
+
43
+ ## Examples
44
+
45
+ ### From data
46
+
47
+ ```tsx
48
+ <NavigationMenu
49
+ aria-label="Main"
50
+ items={[
51
+ { label: 'Product', links: [
52
+ { label: 'Agents', href: '/agents', description: 'Run tools on a schedule.', icon: <Icon name="command" /> },
53
+ { label: 'Evals', href: '/evals', description: 'Score every change.', icon: <Icon name="check" /> },
54
+ ] },
55
+ { label: 'Docs', links: [{ label: 'Quickstart', href: '/docs' }, { label: 'API', href: '/docs/api' }] },
56
+ { label: 'Pricing', href: '/pricing' },
57
+ ]}
58
+ />
59
+ ```
60
+
61
+ ### Parts
62
+
63
+ ```tsx
64
+ <NavigationMenu aria-label="Main">
65
+ <NavigationMenuList>
66
+ <NavigationMenuItem value="product">
67
+ <NavigationMenuTrigger>Product</NavigationMenuTrigger>
68
+ <NavigationMenuContent columns={2}>
69
+ <NavigationMenuLink href="/agents" description="Run tools on a schedule.">Agents</NavigationMenuLink>
70
+ <NavigationMenuLink href="/evals" description="Score every change.">Evals</NavigationMenuLink>
71
+ </NavigationMenuContent>
72
+ </NavigationMenuItem>
73
+ <NavigationMenuItem>
74
+ <NavigationMenuLink href="/pricing" current>Pricing</NavigationMenuLink>
75
+ </NavigationMenuItem>
76
+ </NavigationMenuList>
77
+ </NavigationMenu>
78
+ ```
79
+
80
+ ## Rules
81
+ - Trigger labels are nouns (Product, Resources); link descriptions are one short line.
82
+ - Keep 3–6 top-level items.
83
+ - One hover shape everywhere: xs squircle on the bar, panel-concentric squircle in panels. The current page is a neutral fill + 500, never accent text.
84
+
85
+ ## Accessibility
86
+ - APG disclosure navigation: <nav aria-label> with buttons (aria-expanded, aria-controls) revealing lists of ordinary links.
87
+ - Panels render in place (not portaled), so Tab moves from a trigger into its links in order.
88
+ - Left/Right move between top-level items; ArrowDown on a trigger opens it and focuses the first link; Up/Down move between links; Escape closes and returns focus to the trigger.
89
+
90
+ ## DOM contract (for agents operating the page)
91
+
92
+ - Selector: `[data-sw="navigation-menu"]`
93
+ - `aria-expanded`: on each [data-sw="navigation-menu-trigger"]
94
+ - `data-state`: open | closed on root, items and triggers
95
+ - `aria-current`: "page" on the current [data-sw="navigation-menu-link"]
96
+ - How to operate: Click a [data-sw="navigation-menu-trigger"], then click a [data-sw="navigation-menu-link"]. Agent bridge: open(value), close(), setValue(value | null); items = triggers.
97
+
98
+ Related: `tabs`
@@ -0,0 +1,81 @@
1
+ # NumberInput
2
+
3
+ > A number field with − / + steppers, min/max/step snapping, Intl formatting (currency, percent, units) and spinbutton keys.
4
+
5
+ Category: inputs · Status: beta · Slug: `number-input`
6
+
7
+ ```tsx
8
+ import { NumberInput } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Exact numbers: quantities, seats, limits, prices, timeouts.
13
+ - Values with units or currency shown while typing.
14
+
15
+ ## Avoid
16
+ - `<Input type="number">` — it can’t format and its spinners are tiny.
17
+ - Approximate values — use Slider.
18
+ - Phone numbers, codes or ids — use Input / OTPInput.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `value` | `number \| null` | | Controlled value; null = empty. |
25
+ | `defaultValue` | `number \| null` | `null` | Initial value. |
26
+ | `onValueChange` | `(value: number \| null) => void` | | While typing (once valid) and on each step. |
27
+ | `onValueCommit` | `(value: number \| null) => void` | | On blur/Enter and when a key or button is released. |
28
+ | `min / max` | `number` | | Bounds; typed values clamp on commit. |
29
+ | `step` | `number` | `1` | Arrow/button step; committed values snap to it. |
30
+ | `largeStep / smallStep` | `number` | `10 × step / step ÷ 10` | Shift or PageUp/Down / Alt+Arrow. |
31
+ | `formatOptions` | `Intl.NumberFormatOptions` | | Display format. Percent values are fractions (0.25 = 25%). |
32
+ | `locale` | `string` | | Formatting/parsing locale. |
33
+ | `wheel` | `boolean` | `false` | Mouse wheel steps while focused. |
34
+ | `stepper` | `boolean` | `true` | Show − / + buttons. |
35
+ | `name` | `string` | | Submits the raw number (unformatted). |
36
+ | `incrementLabel / decrementLabel` | `string` | `'Increase' / 'Decrease'` | Button names. |
37
+ | `label` | `ReactNode` | | Visible label. Inside `<Field>`, give the label to the Field instead. |
38
+ | `hint` | `ReactNode` | | Help text under the field. |
39
+ | `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
40
+ | `invalid` | `boolean` | | Invalid without a message (a surrounding Field sets it too). |
41
+ | `disabled / required / readOnly` | `boolean` | | Native states. Inherit from a surrounding Field. |
42
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
43
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| number` | `'sm'` | Squircle corner radius of the field frame. |
44
+
45
+ ## Examples
46
+
47
+ ### Seats
48
+
49
+ ```tsx
50
+ <NumberInput label="Seats" defaultValue={5} min={1} max={500} />
51
+ ```
52
+
53
+ ### Currency
54
+
55
+ ```tsx
56
+ <NumberInput label="Spend limit" value={limit} onValueChange={setLimit} min={0} step={10}
57
+ formatOptions={{ style: 'currency', currency: 'USD' }} />
58
+ ```
59
+
60
+ ### Percent in a Field
61
+
62
+ ```tsx
63
+ <Field label="Sampling rate" description="Share of traffic to trace.">
64
+ <NumberInput defaultValue={0.25} min={0} max={1} step={0.05} formatOptions={{ style: 'percent' }} />
65
+ </Field>
66
+ ```
67
+
68
+ ## Rules
69
+ - Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
70
+
71
+ ## Accessibility
72
+ - Native text input with role="spinbutton" (aria-valuenow/min/max/valuetext). ArrowUp/Down step, Shift ×10, Alt ÷10, PageUp/Down, Home/End to min/max, Enter commits. Step buttons are out of the tab order and point at the input with aria-controls.
73
+
74
+ ## DOM contract (for agents operating the page)
75
+
76
+ - Selector: `[data-sw="number-input"] input[role="spinbutton"]`
77
+ - `aria-valuenow`: current number (absent when empty)
78
+ - `aria-valuetext`: formatted text
79
+ - How to operate: Type a number then blur/Enter, or press [data-sw="number-input-increment"] / [data-sw="number-input-decrement"]. Agent bridge: setValue(n | null), increment(), decrement(), clear().
80
+
81
+ Related: `slider`, `input`, `field`
@@ -0,0 +1,67 @@
1
+ # OTPInput
2
+
3
+ > One-time-code entry: N squircle boxes backed by one real input, so paste fills every box and phones autofill the code from a message.
4
+
5
+ Category: inputs · Status: beta · Slug: `otp-input`
6
+
7
+ ```tsx
8
+ import { OTPInput } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Verification codes from email/SMS/authenticator apps (4–8 characters).
13
+ - Verify on the last character: `onComplete`.
14
+
15
+ ## Avoid
16
+ - N separate inputs — breaks paste and autofill. This component already uses one input.
17
+ - Long or free-form codes — use Input.
18
+ - Passwords — use PasswordInput.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `length` | `number` | `6` | Number of characters / boxes. |
25
+ | `value` | `string` | | Controlled code. |
26
+ | `defaultValue` | `string` | `''` | Initial code. |
27
+ | `onValueChange` | `(value: string) => void` | | Called on each change. |
28
+ | `onComplete` | `(value: string) => void` | | Called when a change fills every box. |
29
+ | `pattern` | `'digits' \| 'letters' \| 'alphanumeric' \| RegExp` | `'digits'` | Accepted characters; others are dropped (so "123-456" pastes as 123456). |
30
+ | `groupSize` | `number` | | Dash after every N boxes (3 → 123–456). |
31
+ | `mask` | `boolean` | `false` | Show dots instead of characters. |
32
+ | `autoComplete` | `string` | `'one-time-code'` | Lets phones offer the code from a message. |
33
+ | `name / required / disabled / readOnly / invalid / autoFocus` | `string / boolean` | | Native form behaviour. |
34
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Boxes 36×42 / 44×52 / 52×60. |
35
+ | `aria-label` | `string` | | Name when there is no Field label. |
36
+
37
+ ## Examples
38
+
39
+ ### Verify on complete
40
+
41
+ ```tsx
42
+ <Field label="Verification code" description="We sent it to ada@example.com.">
43
+ <OTPInput length={6} groupSize={3} onComplete={(code) => verify(code)} autoFocus />
44
+ </Field>
45
+ ```
46
+
47
+ ### Alphanumeric
48
+
49
+ ```tsx
50
+ <OTPInput aria-label="Recovery code" length={8} pattern="alphanumeric" groupSize={4} />
51
+ ```
52
+
53
+ ## Rules
54
+ - Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
55
+ - Clear the value and set `invalid` (or Field `error`) when verification fails; don’t disable the input.
56
+
57
+ ## Accessibility
58
+ - Screen readers see one text input with the whole code; the boxes are aria-hidden. Backspace deletes, paste fills.
59
+
60
+ ## DOM contract (for agents operating the page)
61
+
62
+ - Selector: `[data-sw="otp-input"]`
63
+ - `data-state`: complete | incomplete
64
+ - `data-invalid`: present when invalid
65
+ - How to operate: Type or paste the code into [data-sw="otp-input-control"]. Agent bridge (secret, value hidden): setValue(code), clear().
66
+
67
+ Related: `input`, `field`
@@ -0,0 +1,80 @@
1
+ # Pagination
2
+
3
+ > Numbered pages with ellipses and Previous / Next, as buttons (onPageChange) or links (getHref).
4
+
5
+ Category: navigation · Status: beta · Slug: `pagination`
6
+
7
+ ```tsx
8
+ import { Pagination, paginationRange } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Paging through tables, search results or logs with a known number of pages.
13
+ - Server-rendered lists where each page has its own URL (pass getHref).
14
+
15
+ ## Avoid
16
+ - Infinite feeds — use a "Load more" button.
17
+ - Fewer than 2 pages — render nothing.
18
+ - Stepping through a carousel — use Carousel.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `variant` | `'default' \| 'compact'` | `'default'` | compact is '‹ 2 / 5 ›' with 24px ghost Buttons, for a Card or tile header. Pair it with a controlled Carousel (controls and indicators off) to page a tile's content. |
25
+ | `noun` | `string` | `'page'` | Names the compact buttons and status, e.g. "Next region". |
26
+ | `page` | `number` | | Current page, from 1. Controlled. |
27
+ | `defaultPage` | `number` | `1` | Starting page, when uncontrolled. |
28
+ | `onPageChange` | `(page: number) => void` | | Called on page, Previous, Next, First or Last press. |
29
+ | `pageCount` | `number` | | Number of pages. Or pass total + pageSize. |
30
+ | `total` | `number` | | Number of items (with pageSize). |
31
+ | `pageSize` | `number` | `10` | Items per page (with total). |
32
+ | `siblings` | `number` | `1` | Pages shown on each side of the current one. |
33
+ | `boundaries` | `number` | `1` | Pages always shown at each end. |
34
+ | `getHref` | `(page: number) => string` | | Render pages as links to these URLs (work before JS, open in new tabs). |
35
+ | `showFirstLast` | `boolean` | `false` | Add First and Last buttons. |
36
+ | `simple` | `boolean` | `false` | Previous · "3 / 12" · Next, without numbers. |
37
+ | `size` | `'sm' \| 'md'` | `'md'` | 30 / 36px buttons. |
38
+ | `labels` | `{ previous?; next?; first?; last? }` | | Translate the step labels. |
39
+ | `aria-label` | `string` | `'Pagination'` | Names the navigation landmark. |
40
+
41
+ ## Examples
42
+
43
+ ### Buttons
44
+
45
+ ```tsx
46
+ const [page, setPage] = useState(1)
47
+
48
+ <Pagination page={page} onPageChange={setPage} total={482} pageSize={20} />
49
+ ```
50
+
51
+ ### Links
52
+
53
+ ```tsx
54
+ <Pagination defaultPage={4} pageCount={30} getHref={(p) => `/runs?page=${p}`} siblings={2} showFirstLast />
55
+ ```
56
+
57
+ ### Custom markup from the range helper
58
+
59
+ ```tsx
60
+ paginationRange(6, 20, 1, 1) // [1, 'ellipsis-start', 5, 6, 7, 'ellipsis-end', 20]
61
+ ```
62
+
63
+ ## Rules
64
+ - Place it under the list it pages, centred or right-aligned.
65
+ - Keep siblings at 1 on phones; the row wraps rather than scrolling.
66
+
67
+ ## Accessibility
68
+ - <nav aria-label="Pagination"> with a list; the current page has aria-current="page".
69
+ - Previous/Next at the ends get aria-disabled and stay focusable (buttons) or lose href (links).
70
+ - Ellipses are aria-hidden.
71
+
72
+ ## DOM contract (for agents operating the page)
73
+
74
+ - Selector: `[data-sw="pagination"]`
75
+ - `aria-current`: "page" on the current [data-sw="pagination-link"]
76
+ - `data-page`: page number on each [data-sw="pagination-link"]
77
+ - `aria-disabled`: on [data-sw="pagination-previous"] / [data-sw="pagination-next"] at the ends
78
+ - How to operate: Click [data-sw="pagination-link"][data-page="N"], or pagination-next / pagination-previous. Agent bridge: setPage(n), next(), previous(), first(), last(); state = { page, pageCount }.
79
+
80
+ Related: `carousel`
@@ -0,0 +1,67 @@
1
+ # PasswordInput
2
+
3
+ > A password field with an eye / eye-off reveal toggle and a Caps Lock hint. Hides again when its form submits.
4
+
5
+ Category: inputs · Status: beta · Slug: `password-input`
6
+
7
+ ```tsx
8
+ import { PasswordInput } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Sign-in and sign-up passwords, API secrets and tokens people paste.
13
+
14
+ ## Avoid
15
+ - `<Input type="password">` — no reveal toggle.
16
+ - Showing a secret by default — use `defaultVisible` only for generated values the user must copy.
17
+ - Wrong autoComplete: use `new-password` on sign-up so managers offer a strong one.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `onValueChange` | `(value: string) => void` | | Called with the text on each change (value/defaultValue/onChange also work). |
24
+ | `visible` | `boolean` | | Controlled reveal state. |
25
+ | `defaultVisible` | `boolean` | `false` | Initial reveal state. |
26
+ | `onVisibleChange` | `(visible: boolean) => void` | | Called when the toggle (or a form submit) shows/hides. |
27
+ | `autoComplete` | `'current-password' \| 'new-password' \| 'off' \| string` | `'current-password'` | Password-manager hint. |
28
+ | `toggleLabel` | `string` | `'Show password'` | Accessible name of the reveal button (state is aria-pressed). |
29
+ | `prefix` | `ReactNode` | | Icon before the text. |
30
+ | `label` | `ReactNode` | | Visible label. Inside `<Field>`, give the label to the Field instead. |
31
+ | `hint` | `ReactNode` | | Help text under the field. |
32
+ | `error` | `ReactNode` | | Error text; turns the frame red and sets aria-invalid. |
33
+ | `invalid` | `boolean` | | Invalid without a message (a surrounding Field sets it too). |
34
+ | `disabled / required / readOnly` | `boolean` | | Native states. Inherit from a surrounding Field. |
35
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
36
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| number` | `'sm'` | Squircle corner radius of the field frame. |
37
+
38
+ ## Examples
39
+
40
+ ### Sign in
41
+
42
+ ```tsx
43
+ <PasswordInput label="Password" name="password" required />
44
+ ```
45
+
46
+ ### New password
47
+
48
+ ```tsx
49
+ <Field label="New password" description="At least 12 characters.">
50
+ <PasswordInput autoComplete="new-password" minLength={12} />
51
+ </Field>
52
+ ```
53
+
54
+ ## Rules
55
+ - Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
56
+
57
+ ## Accessibility
58
+ - Toggle is a <button aria-pressed> with aria-controls; it does not steal focus from the input. Caps Lock state is data-capslock on the root.
59
+
60
+ ## DOM contract (for agents operating the page)
61
+
62
+ - Selector: `[data-sw="password-input"] input`
63
+ - `data-visible`: present while shown (on root)
64
+ - `data-capslock`: present while Caps Lock is on
65
+ - How to operate: Type into the input; click [data-sw="password-input-toggle"] to reveal. Agent bridge (secret, value hidden): setValue(text), clear(), toggle().
66
+
67
+ Related: `input`, `field`
@@ -0,0 +1,116 @@
1
+ # PillButton
2
+
3
+ > A fully rounded button with an optional leading icon ("Export", "View tasks").
4
+
5
+ Category: extras · Status: beta · Slug: `pill-button`
6
+
7
+ ```tsx
8
+ import { PillButton } from '@peerproblem/sw3-ui/extras'
9
+ ```
10
+
11
+ ## When to use
12
+ - Toolbars and action rows on dark surfaces (tone `night`).
13
+ - Toggles that reveal content: set `aria-expanded` and it keeps its hover fill while open.
14
+ - Navigation over imagery (tone `glass`, size `fluid`).
15
+ - File downloads: `href` + `download`.
16
+
17
+ ## Avoid
18
+ - Hero CTAs — use Button `xl`; PillButton is for secondary rows.
19
+ - Mixing tones in one row. One row, one tone.
20
+ - Glass on a plain white background — there is nothing to blur. Use `soft` instead.
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Default | Description |
25
+ | --- | --- | --- | --- |
26
+ | `children` * | `ReactNode` | | Label. |
27
+ | `icon` | `IconName \| ReactNode` | | Leading icon, e.g. 'import', 'note'. |
28
+ | `trailingIcon` | `IconName \| ReactNode` | | Trailing icon, e.g. 'chevron-down' for menus. |
29
+ | `tone` | `'night' \| 'ink' \| 'soft' \| 'glass'` | `'night'` | night = grey on near-black · ink = solid foreground · soft = muted fill · glass = 50% white + blur, flips to black on hover. |
30
+ | `size` | `'sm' \| 'md' \| 'lg' \| 'fluid'` | `'lg'` | 36 / 48 / 60px, or fluid 48→100px with the viewport. |
31
+ | `href` | `string` | | Render a link. |
32
+ | `download` | `boolean \| string` | | With href: download the file. |
33
+ | `aria-expanded / aria-pressed` | `boolean` | | Toggle state; keeps the hover fill while true. |
34
+
35
+ ## Examples
36
+
37
+ ### Toolbar on a dark card
38
+
39
+ ```tsx
40
+ const [showTasks, setShowTasks] = useState(false)
41
+
42
+ <div style={{ display: 'flex', gap: 6 }}>
43
+ <PillButton icon="import" href="/export.csv" download>Export</PillButton>
44
+ <PillButton icon="note" aria-expanded={showTasks} aria-controls="tasks" onClick={() => setShowTasks(!showTasks)}>
45
+ View tasks
46
+ </PillButton>
47
+ </div>
48
+ ```
49
+
50
+ ### Light surface
51
+
52
+ ```tsx
53
+ <PillButton tone="soft" size="md" icon="plus">Add filter</PillButton>
54
+ ```
55
+
56
+ ### Adjust one place
57
+
58
+ ```tsx
59
+ <div style={{ '--sw-pill-button-radius': '16px' } as React.CSSProperties}>
60
+ <PillButton>Squarer pill</PillButton>
61
+ </div>
62
+ ```
63
+
64
+ ## Variants
65
+
66
+ Rendered as `data-<variant>` on `[data-sw="pill-button"]`.
67
+
68
+ - `tone`: `night` | `ink` | `soft` | `glass` (default `night`)
69
+ - `size`: `sm` | `md` | `lg` | `fluid` (default `lg`)
70
+
71
+ ## CSS variables
72
+
73
+ Set on any ancestor to adjust this component. Never target `.sw-*` selectors.
74
+
75
+ | Variable | Controls |
76
+ | --- | --- |
77
+ | `--sw-pill-button-bg` | Fill. |
78
+ | `--sw-pill-button-bg-hover` | Fill on hover, and while aria-expanded / aria-pressed is true. |
79
+ | `--sw-pill-button-fg` | Text and icon color. |
80
+ | `--sw-pill-button-fg-hover` | Text color on hover / active. |
81
+ | `--sw-pill-button-height` | Height. |
82
+ | `--sw-pill-button-padding-x` | Horizontal padding. |
83
+ | `--sw-pill-button-radius` | Corner radius. 999px = full pill. |
84
+ | `--sw-pill-button-font-size` | Label size. |
85
+ | `--sw-pill-button-font-weight` | Label weight. |
86
+ | `--sw-pill-button-gap` | Space between icon and label. |
87
+ | `--sw-pill-button-blur` | Backdrop blur (5px on glass). |
88
+
89
+ ## Designs
90
+
91
+ Swap the whole look with `data-design` on <html> or any wrapper.
92
+
93
+ - `sdk`: Default. No attribute needed. Neutral tokens and Geist, with an optional app-defined brand accent.
94
+ - `calm`: import '@peerproblem/sw3-ui/themes/calm.css' + data-design="calm". Teal-grey ink, pale tiles, IBM Plex Sans.
95
+ - `frost`: import '@peerproblem/sw3-ui/themes/frost.css' + data-design="frost". Frosted fills that flip to solid on hover, Urbanist.
96
+
97
+ ## Rules
98
+ - Pick looks with `tone` and `size`. Do not write CSS that targets .sw-* class names.
99
+ - To adjust one place, set a `recipe.cssVars` variable on a wrapper: `.toolbar { --sw-pill-button-radius: 16px }`.
100
+ - To change a whole look, use `data-design` with a theme file instead of overriding many variables.
101
+ - Use 6–8px gaps between pills in a row.
102
+
103
+ ## Accessibility
104
+ - Toggles must set aria-expanded (disclosure) or aria-pressed (on/off).
105
+ - Icons are decorative; the label is the name.
106
+
107
+ ## DOM contract (for agents operating the page)
108
+
109
+ - Selector: `[data-sw="pill-button"]`
110
+ - `data-tone`: night | ink | soft | glass
111
+ - `data-size`: sm | md | lg | fluid
112
+ - `aria-expanded`: true while its panel is open
113
+ - `aria-pressed`: true while on
114
+ - How to operate: Click it. Read aria-expanded / aria-pressed for state.
115
+
116
+ Related: `button`
@@ -0,0 +1,85 @@
1
+ # Popover
2
+
3
+ > A small non-modal dialog anchored to its trigger for a quick task with form content: share a link, rename, filter with fields.
4
+
5
+ Category: overlays · Status: beta · Slug: `popover`
6
+
7
+ ```tsx
8
+ import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A short task tied to one control (share, rename, filter) that should not leave the page.
13
+ - Form content beside a trigger: text fields, a filter panel with inputs, Apply/Cancel buttons.
14
+
15
+ ## Avoid
16
+ - Plain-text hints → use Tooltip.
17
+ - A link preview on hover → use HoverCard.
18
+ - Long forms or anything needing full attention → use Dialog (or Drawer on phones).
19
+ - A list of commands → use a Menu.
20
+ - Only on/off settings, with no text field or buttons → use a Menu with MenuCheckboxItem (it stays open while people toggle several).
21
+
22
+ ## Props
23
+
24
+ | Prop | Type | Default | Description |
25
+ | --- | --- | --- | --- |
26
+ | `open` | `boolean` | | Controlled open state of the popover. |
27
+ | `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
28
+ | `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
29
+ | `modal` | `boolean` | `false` | Trap focus and lock page scroll. By default Tab out or a press outside closes it. |
30
+ | `PopoverTrigger.…ButtonProps` | `ButtonProps` | | Default trigger is an outline Button; any Button prop works. |
31
+ | `PopoverTrigger.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. |
32
+ | `PopoverContent.side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Side of the trigger. Flips when there is no room. |
33
+ | `PopoverContent.align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along that side. |
34
+ | `PopoverContent.sideOffset` | `number` | `6` | Gap to the trigger in px. |
35
+ | `PopoverContent.padding` | `'none' \| 'sm' \| 'md'` | `'md'` | Inner padding 0 / 12 / 16px; blocks 16px apart (12 for sm), title → description 6px. Width is 20rem; override with --sw-popover-width. |
36
+ | `PopoverContent.initialFocus` | `RefObject<HTMLElement>` | | Element focused on open. Default: [data-autofocus], else the first focusable, else the panel. |
37
+ | `PopoverTitle / PopoverDescription` | `ReactNode` | | h2 / p; wired to aria-labelledby / aria-describedby automatically. |
38
+ | `PopoverClose.…ButtonProps` | `ButtonProps` | | Closes the popover. Secondary Button by default; `render` to change. |
39
+
40
+ ## Examples
41
+
42
+ ### Share link
43
+
44
+ ```tsx
45
+ <Popover>
46
+ <PopoverTrigger leading={<Icon name="user" />}>Share</PopoverTrigger>
47
+ <PopoverContent align="end">
48
+ <PopoverTitle>Share this run</PopoverTitle>
49
+ <PopoverDescription>Anyone with the link can view the trace.</PopoverDescription>
50
+ <Input readOnly defaultValue="sw3.dev/r/8f2c" aria-label="Link" />
51
+ <PopoverClose variant="primary">Copy link</PopoverClose>
52
+ </PopoverContent>
53
+ </Popover>
54
+ ```
55
+
56
+ ### Controlled, custom trigger element
57
+
58
+ ```tsx
59
+ const [open, setOpen] = useState(false)
60
+
61
+ <Popover open={open} onOpenChange={setOpen}>
62
+ <PopoverTrigger render={<button className="chip" />}>Filters</PopoverTrigger>
63
+ <PopoverContent side="right" padding="sm">…</PopoverContent>
64
+ </Popover>
65
+ ```
66
+
67
+ ## Rules
68
+ - Trigger and Close parts render an SW3 <Button> (trigger variant "outline", close variant "secondary") and accept every Button prop (variant, size, leading…). To use your own element pass `render={<a href="…"/>}`.
69
+ - Always give the content a PopoverTitle (or aria-label on PopoverContent).
70
+ - Mount PopoverContent unconditionally; it portals and animates itself.
71
+ - Keep it small: one task, ≤ ~6 controls.
72
+
73
+ ## Accessibility
74
+ - Trigger: aria-haspopup="dialog", aria-expanded, aria-controls. Content: role="dialog", labelled by its title.
75
+ - Opening moves focus into the content; Escape, a Close part or a press outside closes it and returns focus to the trigger. Tab leaving a non-modal popover closes it.
76
+
77
+ ## DOM contract (for agents operating the page)
78
+
79
+ - Selector: `[data-sw="popover-trigger"], [data-sw="popover-content"]`
80
+ - `aria-expanded`: on the trigger: true while open
81
+ - `data-state`: open | closed (trigger and content)
82
+ - `data-side`: on the content: side it landed on
83
+ - How to operate: Click the trigger to open; the panel is [data-sw="popover-content"][role="dialog"] at the end of <body>. Press Escape or click [data-sw="popover-close"] to close. Agent bridge (kind "popover"): state {open}; actions open(), close(), toggle().
84
+
85
+ Related: `tooltip`, `hover-card`, `dialog`, `drawer`