@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,122 @@
1
+ # DatePicker
2
+
3
+ > DateInput plus Calendar in a popup: type a date or pick it from the month grid. Single date or a range, optional presets; submits ISO.
4
+
5
+ Category: dates · Status: beta · Slug: `date-picker`
6
+
7
+ ```tsx
8
+ import { DatePicker, todayISO, addDays } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Any form field for a date where people may want to see the calendar: due dates, scheduling, filters.
13
+ - Date ranges (`mode="range"`, two inputs) such as report periods or stays, with `presets` for "Last 7 days".
14
+
15
+ ## Avoid
16
+ - Always-visible dates → use Calendar inline.
17
+ - Birthdays and other known dates far in the past → DateInput is faster than paging through months.
18
+ - Computing presets with Date math in local time → use the ISO helpers (addDays, todayISO).
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `mode` | `'single' \| 'range'` | `'single'` | One date, or a [start, end] range with an input for each end. |
25
+ | `value` | `string \| null · [start, end] \| null` | | ISO date, or an inclusive ISO range. Pass to control. |
26
+ | `defaultValue` | `same as value` | `null` | Initial value (restored on form reset). |
27
+ | `onValueChange` | `(value) => void` | | Runs when a day is picked, a typed date completes, a preset or Clear is pressed. Ranges report once both ends are set. |
28
+ | `open` | `boolean` | | Whether the calendar popup is open. Pass to control. |
29
+ | `defaultOpen` | `boolean` | `false` | Initial open state. |
30
+ | `onOpenChange` | `(open: boolean) => void` | | Runs when the popup opens or closes. |
31
+ | `min` | `string (ISO date)` | | Earliest date that can be picked, e.g. "2026-11-01". |
32
+ | `max` | `string (ISO date)` | | Latest date that can be picked. |
33
+ | `isDateUnavailable` | `(date: string) => boolean` | | Return true for dates that cannot be picked (booked days). They stay focusable so keyboard users hear them. |
34
+ | `unavailable` | `DateMatcher \| DateMatcher[]` | | The same as data: ISO dates, `{ from, to }`, `{ before }`, `{ after }`, `{ weekday: [0, 6] }` (weekends) or a function. |
35
+ | `locale` | `string` | `page lang, then browser` | BCP 47 locale for names, order and week start. |
36
+ | `weekStartsOn` | `number (0–6)` | `locale's` | First day of the week in the calendar. |
37
+ | `months` | `number` | `1` | Months shown side by side in the popup. |
38
+ | `fixedWeeks` | `boolean` | `false` | Calendar always shows six weeks. |
39
+ | `minDays / maxDays` | `number` | | Range length limits, ends included. |
40
+ | `today` | `string (ISO date)` | | Override today. |
41
+ | `timeZone` | `string` | | IANA zone deciding today. |
42
+ | `closeOnSelect` | `boolean` | `true` | Close after a pick (a range's end) or a preset. |
43
+ | `presets` | `Array<{ label: ReactNode; value: string \| [string, string] }>` | | Shortcuts shown beside the calendar; the matching one shows aria-pressed. |
44
+ | `clearable` | `boolean` | `false` | Show a clear (×) button while there is a value. |
45
+ | `placement` | `Placement` | `'bottom-start'` | Popup placement. |
46
+ | `label` | `ReactNode` | | Visible label. Omit inside <Field> (the Field labels it) or pass aria-label. |
47
+ | `hint` | `ReactNode` | | Help text under the field. |
48
+ | `error` | `ReactNode` | | Error text; also marks the field invalid. |
49
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Heights 32 / 40 / 52px. |
50
+ | `inline` | `boolean` | `false` | Shrink the box to its content. By default it fills the width, like Input. |
51
+ | `disabled` | `boolean` | `false` | Cannot be focused or changed. |
52
+ | `readOnly` | `boolean` | `false` | Value is visible but cannot change. |
53
+ | `required` | `boolean` | `false` | Blocks form submit while empty. |
54
+ | `invalid` | `boolean` | | Force the invalid look (also set automatically when out of range). |
55
+ | `form` | `string` | | id of the form it belongs to when outside it. |
56
+ | `aria-label` | `string` | | Accessible name when there is no visible label. |
57
+ | `name` | `string` | | Submit name (ISO). In range mode both ends submit under it unless startName / endName are set. |
58
+ | `startName / endName` | `string` | | Range: separate submit names for each end. |
59
+ | `startLabel / endLabel` | `string` | `'Start date' / 'End date'` | Range: accessible names of the two inputs. |
60
+
61
+ ## Anatomy
62
+
63
+ ```
64
+ DatePicker
65
+ ├─ field DateInput's segmented field (month / day / year)
66
+ ├─ calendar button
67
+ └─ popup PopupPanel
68
+ ├─ presets optional
69
+ └─ Calendar one month grid, or a range
70
+ ```
71
+
72
+ Built from: `DateInput`, `Calendar`, `PopupPanel (usePopup)`.
73
+
74
+ ## Examples
75
+
76
+ ### Due date in a form
77
+
78
+ ```tsx
79
+ <DatePicker label="Due date" name="due" defaultValue="2026-11-20" min="2026-11-14" clearable />
80
+ ```
81
+
82
+ ### Report range with presets
83
+
84
+ ```tsx
85
+ const today = todayISO()
86
+ const [range, setRange] = useState<[string, string] | null>(null)
87
+ <DatePicker
88
+ mode="range"
89
+ label="Period"
90
+ months={2}
91
+ value={range}
92
+ onValueChange={setRange}
93
+ presets={[
94
+ { label: 'Last 7 days', value: [addDays(today, -6), today] },
95
+ { label: 'Last 30 days', value: [addDays(today, -29), today] },
96
+ ]}
97
+ />
98
+ ```
99
+
100
+ ## Rules
101
+ - Values are ISO strings; ranges are [start, end] with start ≤ end.
102
+ - Use a visible label (or Field). The trigger is named "Choose date, selected …" automatically.
103
+ - Presets are computed by the app (use addDays/todayISO from @peerproblem/sw3-ui). They render as list rows: the matching one gets the neutral selected fill + 500 weight, not accent.
104
+ - Fills the width like Input; pass `inline` to size it to its content (e.g. next to a TimeInput).
105
+
106
+ ## Accessibility
107
+ - Follows the WAI-ARIA date picker dialog: segmented spinbutton input(s), a button with aria-haspopup="dialog" and aria-expanded, and a role="dialog" popup holding the Calendar grid.
108
+ - Opening focuses the selected day (else today). Picking a day or Escape closes and returns focus to the button. Alt+ArrowDown in the input opens it; Tab out closes it.
109
+
110
+ ## DOM contract (for agents operating the page)
111
+
112
+ - Selector: `[data-sw="date-picker"]`
113
+ - `data-state`: open | closed
114
+ - `data-mode`: single | range
115
+ - `data-invalid`: typed date out of range / unavailable
116
+ - `[data-sw="date-picker-trigger"][aria-expanded]`: popup open
117
+ - `[data-sw="date-picker-input"][data-part]`: segment group (start / end in range mode)
118
+ - `[data-sw="date-picker-content"]`: the popup (portaled to body) containing [data-sw="calendar"]
119
+ - `[data-sw="date-picker-preset"][aria-pressed]`: preset matching the value
120
+ - How to operate: Click `[data-sw="date-picker-trigger"]`, then a `[data-sw="calendar-day"][data-value="YYYY-MM-DD"]` in the popup; or type into the segments. Agent bridge: setValue("YYYY-MM-DD" | "start/end"), clear(), open(), close(), toggle(); state = { mode, value, open, min, max, disabled, readOnly, invalid }.
121
+
122
+ Related: `calendar`, `date-input`, `time-input`
@@ -0,0 +1,97 @@
1
+ # Dialog
2
+
3
+ > A modal squircle panel over a dimmed page for a focused task, with focus trap, scroll lock, Escape and backdrop dismissal.
4
+
5
+ Category: overlays · Status: beta · Slug: `dialog`
6
+
7
+ ```tsx
8
+ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter, DialogClose } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A task that needs full attention: edit a record, create an API key, review terms.
13
+ - Forms of a few fields that should not navigate away.
14
+
15
+ ## Avoid
16
+ - Confirming a destructive action → use AlertDialog (or confirm()).
17
+ - A quick edit next to a control → use Popover.
18
+ - Phone-first sheets that should be swiped away → use Drawer.
19
+ - Status messages → use toast().
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `open` | `boolean` | | Controlled open state of the dialog. |
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
+ | `modal` | `boolean` | `true` | Trap focus, lock scroll and show the backdrop. false = a panel beside the page. |
29
+ | `dismissible` | `boolean` | `true` | Whether Escape and backdrop presses close it. Close parts always can. Set false while a form is dirty. |
30
+ | `closeOnOutsidePress` | `boolean` | `true` | Whether pressing the backdrop closes it. |
31
+ | `DialogTrigger.…ButtonProps` | `ButtonProps` | | Outline Button by default. |
32
+ | `DialogTrigger.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. |
33
+ | `DialogContent.size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Max width 400 / 520 / 720px. Under 640px it is full width, docked 8px above the bottom. |
34
+ | `DialogContent.closeButton` | `boolean` | `true` | Show the × in the corner. |
35
+ | `DialogContent.initialFocus` | `RefObject<HTMLElement>` | | Element focused on open. Default [data-autofocus], else the first focusable. |
36
+ | `DialogHeader / DialogBody / DialogFooter` | `div` | | Layout: header (title + description), scrollable body, right-aligned action row (stacked on phones). |
37
+ | `DialogTitle / DialogDescription` | `ReactNode` | | h2 / p; wired to aria-labelledby / aria-describedby. |
38
+ | `DialogClose.…ButtonProps` | `ButtonProps` | | Closes the dialog. Secondary Button by default. |
39
+
40
+ ## Examples
41
+
42
+ ### Create API key
43
+
44
+ ```tsx
45
+ <Dialog>
46
+ <DialogTrigger variant="primary">New key</DialogTrigger>
47
+ <DialogContent size="sm">
48
+ <DialogHeader>
49
+ <DialogTitle>Create API key</DialogTitle>
50
+ <DialogDescription>Keys can call every agent in this workspace.</DialogDescription>
51
+ </DialogHeader>
52
+ <DialogBody>
53
+ <Input label="Name" placeholder="ci-runner" data-autofocus />
54
+ </DialogBody>
55
+ <DialogFooter>
56
+ <DialogClose>Cancel</DialogClose>
57
+ <Button variant="accent" onClick={create}>Create key</Button>
58
+ </DialogFooter>
59
+ </DialogContent>
60
+ </Dialog>
61
+ ```
62
+
63
+ ### Controlled, opened from code
64
+
65
+ ```tsx
66
+ const [open, setOpen] = useState(false)
67
+
68
+ <Button onClick={() => setOpen(true)}>Review changes</Button>
69
+ <Dialog open={open} onOpenChange={setOpen}>
70
+ <DialogContent size="lg">
71
+ <DialogHeader><DialogTitle>Review changes</DialogTitle></DialogHeader>
72
+ <DialogBody>{/* long diff scrolls here */}</DialogBody>
73
+ <DialogFooter><DialogClose variant="primary">Done</DialogClose></DialogFooter>
74
+ </DialogContent>
75
+ </Dialog>
76
+ ```
77
+
78
+ ## Rules
79
+ - 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="…"/>}`.
80
+ - Overlay spacing scale: padding 24 (Dialog) / 20 (Drawer) / 16 (Popover, Hover Card); blocks 16px apart; title → description 6px.
81
+ - Always include a DialogTitle.
82
+ - Put long content in DialogBody so the title and actions stay visible.
83
+ - One accent button in the footer; the cancel/close action comes first.
84
+
85
+ ## Accessibility
86
+ - role="dialog" + aria-modal, labelled by the title, described by the description. Focus moves in, Tab is trapped, focus returns to the trigger on close.
87
+ - Escape closes the top-most layer only (a Select inside closes first). Toasts stay usable while it is open.
88
+
89
+ ## DOM contract (for agents operating the page)
90
+
91
+ - Selector: `[data-sw="dialog-trigger"], [data-sw="dialog-content"][role="dialog"]`
92
+ - `aria-expanded`: on the trigger
93
+ - `data-state`: open | closed
94
+ - `data-size`: sm | md | lg
95
+ - How to operate: Click the trigger; the panel is [data-sw="dialog-content"] at the end of <body>. Close with [data-sw="dialog-close"] or Escape. Agent bridge (kind "dialog"): state {open}; actions open(), close(), toggle().
96
+
97
+ Related: `alert-dialog`, `drawer`, `popover`
@@ -0,0 +1,50 @@
1
+ # DonutChart
2
+
3
+ > Part-to-whole for 2–6 slices with a central label. Built on Unovis VisDonut.
4
+
5
+ Category: charts · Status: beta · Slug: `donut-chart`
6
+
7
+ ```tsx
8
+ import { DonutChart, ChartCard } from '@peerproblem/sw3-ui/charts'
9
+ ```
10
+
11
+ ## When to use
12
+ - Share of a total with few slices.
13
+
14
+ ## Avoid
15
+ - More than 6 slices or slices that are close in size — use BarChart.
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ | --- | --- | --- | --- |
21
+ | `data` * | `Array<{ label: string; value: number; color?: string }>` | | |
22
+ | `centralLabel` | `string` | | Short value at the center, typically the total. |
23
+ | `centralSubLabel` | `string` | | Short unit label below the value. Use sentence case and include the value and unit in the chart’s aria-label when they are meaningful. |
24
+ | `arcWidth` | `number` | `18` | Ring thickness px. |
25
+ | `height` | `number` | `200` | |
26
+
27
+ ## Examples
28
+
29
+ ### Traffic sources
30
+
31
+ ```tsx
32
+ const sources = [{ label: 'Search', value: 52 }, { label: 'Direct', value: 28 }, { label: 'Social', value: 20 }]
33
+
34
+ <ChartCard title="Traffic sources" legend={sources.map((s) => ({ key: s.label }))}>
35
+ <DonutChart aria-label="12,400 visits. Search accounts for 52%." data={sources} centralLabel="12.4k" centralSubLabel="Visits" />
36
+ </ChartCard>
37
+ ```
38
+
39
+ ## Rules
40
+ - Wrap the chart in <ChartCard> and give the card a title.
41
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
42
+ - Use the default palette order; color 1 (blue) is the primary series.
43
+ - Max 5 series per chart. Do not use dual y-axes.
44
+
45
+ ## DOM contract (for agents operating the page)
46
+
47
+ - Selector: `[data-sw="chart"]`
48
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
49
+ - `aria-label`: the summary
50
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
@@ -0,0 +1,101 @@
1
+ # Drawer
2
+
3
+ > A sheet that slides in from an edge (bottom by default); drag it toward its edge to dismiss, with optional snap points.
4
+
5
+ Category: overlays · Status: beta · Slug: `drawer`
6
+
7
+ ```tsx
8
+ import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerBody, DrawerFooter, DrawerClose } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Phone-first tasks and action sheets.
13
+ - Side panels: filters, run details, settings (side="right").
14
+ - Map-style sheets that rest at several heights (snapPoints).
15
+
16
+ ## Avoid
17
+ - Short confirmations → use AlertDialog.
18
+ - Tiny edits next to a control on desktop → use Popover.
19
+ - Putting the only way to close behind a swipe — keep a DrawerClose.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `open` | `boolean` | | Controlled open state of the drawer. |
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
+ | `side` | `'bottom' \| 'top' \| 'left' \| 'right'` | `'bottom'` | Edge it slides from. |
29
+ | `modal` | `boolean` | `true` | Trap focus, lock scroll and dim the page. |
30
+ | `dismissible` | `boolean` | `true` | Whether Escape, backdrop press and swipe can close it (it rubber-bands otherwise). |
31
+ | `closeOnOutsidePress` | `boolean` | `true` | Whether pressing the backdrop closes it. |
32
+ | `snapPoints` | `number[]` | | Resting sizes: fractions of the viewport (≤ 1) or px (> 1), e.g. [0.4, 0.9]. The sheet is sized to the largest. |
33
+ | `snapPoint / defaultSnapPoint / onSnapPointChange` | `number / number / (p: number) => void` | | Controlled / initial (default: smallest) snap point. |
34
+ | `DrawerTrigger.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. |
35
+ | `DrawerContent.handle` | `boolean` | `true for top/bottom` | Grab handle. With 2+ snap points it is a button: press cycles sizes, arrow keys / Home / End pick one. |
36
+ | `DrawerHeader / DrawerBody / DrawerFooter` | `div` | | Layout: title block, scrollable middle (drag starts there only when scrolled to the top), equal-width action row. |
37
+ | `DrawerTitle / DrawerDescription / DrawerClose` | `parts` | | Same as Dialog’s. |
38
+
39
+ ## Examples
40
+
41
+ ### Bottom sheet
42
+
43
+ ```tsx
44
+ <Drawer>
45
+ <DrawerTrigger>Run settings</DrawerTrigger>
46
+ <DrawerContent>
47
+ <DrawerHeader>
48
+ <DrawerTitle>Run settings</DrawerTitle>
49
+ <DrawerDescription>Applies to the next run only.</DrawerDescription>
50
+ </DrawerHeader>
51
+ <DrawerBody>
52
+ <Switch label="Stream tokens" checked={stream} onCheckedChange={setStream} />
53
+ </DrawerBody>
54
+ <DrawerFooter>
55
+ <DrawerClose>Cancel</DrawerClose>
56
+ <DrawerClose variant="primary" onClick={save}>Save</DrawerClose>
57
+ </DrawerFooter>
58
+ </DrawerContent>
59
+ </Drawer>
60
+ ```
61
+
62
+ ### Right panel
63
+
64
+ ```tsx
65
+ <Drawer side="right">
66
+ <DrawerTrigger>Trace</DrawerTrigger>
67
+ <DrawerContent>…</DrawerContent>
68
+ </Drawer>
69
+ ```
70
+
71
+ ### Snap points
72
+
73
+ ```tsx
74
+ <Drawer snapPoints={[0.35, 0.9]}>
75
+ <DrawerTrigger>Nearby agents</DrawerTrigger>
76
+ <DrawerContent>
77
+ <DrawerHeader><DrawerTitle>Nearby agents</DrawerTitle></DrawerHeader>
78
+ <DrawerBody>{/* list */}</DrawerBody>
79
+ </DrawerContent>
80
+ </Drawer>
81
+ ```
82
+
83
+ ## Rules
84
+ - 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="…"/>}`.
85
+ - Always include a DrawerTitle and a visible way to close (DrawerClose).
86
+ - Prefer bottom on phones, right for desktop side panels.
87
+
88
+ ## Accessibility
89
+ - role="dialog" + aria-modal, labelled and described; focus trapped and returned. Escape and the backdrop close it; dragging is never the only way.
90
+ - The snap handle is a button (aria-label "Resize drawer") operable with arrows, Home, End.
91
+
92
+ ## DOM contract (for agents operating the page)
93
+
94
+ - Selector: `[data-sw="drawer-trigger"], [data-sw="drawer-content"][role="dialog"]`
95
+ - `data-state`: open | closed
96
+ - `data-side`: bottom | top | left | right
97
+ - `data-snap`: current snap point
98
+ - `data-dragging`: present while dragged
99
+ - How to operate: Click the trigger; close with [data-sw="drawer-close"] or Escape; resize with [data-sw="drawer-handle"]. Agent bridge (kind "drawer"): state {open, side, snapPoint}; actions open(), close(), toggle().
100
+
101
+ Related: `dialog`, `popover`
@@ -0,0 +1,52 @@
1
+ # EmptyState
2
+
3
+ > A heading and optional action for a view with no content to display.
4
+
5
+ Category: display · Status: beta · Slug: `empty-state`
6
+
7
+ ```tsx
8
+ import { EmptyState } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A completed search with no results or a list with no items.
13
+
14
+ ## Avoid
15
+ - Content that is still loading or failed to load.
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ | --- | --- | --- | --- |
21
+ | `title` * | `string` | | Heading that describes the empty result. |
22
+ | `description` | `string` | | Optional context or a brief next step. |
23
+ | `icon` | `ReactNode` | | Optional decorative icon. |
24
+ | `action` | `ReactNode` | | One optional button or link. |
25
+ | `headingLevel` | `2 \| 3 \| 4` | `3` | Native heading level. Match the surrounding outline. |
26
+ | `…div attributes` | `HTMLAttributes<HTMLDivElement>` | | Attributes such as className, style, and id apply to the root. |
27
+
28
+ ## Examples
29
+
30
+ ### No matching road closures
31
+
32
+ ```tsx
33
+ <EmptyState
34
+ title="No matching road closures"
35
+ description="Clear the filters to see all reported closures."
36
+ action={<Button onClick={clearFilters}>Clear filters</Button>}
37
+ />
38
+ ```
39
+
40
+ ## Rules
41
+ - Use a specific heading. Offer one action when it helps the user continue.
42
+
43
+ ## Accessibility
44
+ - The icon is decorative. The optional button or link keeps native keyboard behavior.
45
+ - The empty state is static by default. The host manages announcements for dynamic updates.
46
+
47
+ ## DOM contract (for agents operating the page)
48
+
49
+ - Selector: `[data-sw="empty-state"]`
50
+ - How to operate: Read the heading and description. Use the button or link if an action is present.
51
+
52
+ Related: `skeleton`, `button`
@@ -0,0 +1,80 @@
1
+ # Field
2
+
3
+ > Connects one form control to its label, description and error (ids, for, aria-describedby, aria-invalid, required, disabled).
4
+
5
+ Category: inputs · Status: beta · Slug: `field`
6
+
7
+ ```tsx
8
+ import { Field, FieldLabel, FieldDescription, FieldError } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Any form control that needs a visible label, help text or validation message.
13
+ - Controls without their own `label` prop (Slider, Radio Group, OTP Input, Rating, Number Input in a form).
14
+ - Showing an error from your own validation or the server: pass `error`.
15
+
16
+ ## Avoid
17
+ - Two controls in one Field — each Field connects exactly one control. Use a CheckboxGroup / RadioGroup for sets.
18
+ - Passing `label` to both the Field and the Input inside it (double label).
19
+ - Hand-wiring ids and aria-describedby — the Field does it.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `label` | `ReactNode` | | Visible label (or put a `<FieldLabel>` in children). |
26
+ | `description` | `ReactNode` | | Help text under the control (or `<FieldDescription>`). |
27
+ | `error` | `ReactNode` | | Error message. Setting it marks the field invalid. |
28
+ | `invalid` | `boolean` | `!!error` | Invalid without a message, or `false` to hide the error. |
29
+ | `required` | `boolean` | `false` | Marks the control required and shows `*` after the label. |
30
+ | `disabled` | `boolean` | `false` | Disables the control. |
31
+ | `controlId` | `string` | | id for the control. Generated when omitted. |
32
+ | `children` * | `ReactNode` | | The control (Input, Textarea, Slider, RadioGroup…), plus optional parts. |
33
+ | `FieldError.forceShow` | `boolean` | `false` | Show the error part even when the field is valid. |
34
+
35
+ ## Examples
36
+
37
+ ### Shorthand
38
+
39
+ ```tsx
40
+ <Field label="Project name" description="Lowercase, no spaces." required>
41
+ <Input placeholder="my-agent" />
42
+ </Field>
43
+ ```
44
+
45
+ ### Parts + server error
46
+
47
+ ```tsx
48
+ <Field invalid={!!serverError}>
49
+ <FieldLabel>API key</FieldLabel>
50
+ <PasswordInput autoComplete="off" />
51
+ <FieldDescription>Find it in Settings → Keys.</FieldDescription>
52
+ <FieldError>{serverError}</FieldError>
53
+ </Field>
54
+ ```
55
+
56
+ ### Any control
57
+
58
+ ```tsx
59
+ <Field label="Temperature" description="Higher is more creative.">
60
+ <Slider defaultValue={0.7} min={0} max={2} step={0.1} />
61
+ </Field>
62
+ ```
63
+
64
+ ## Rules
65
+ - One Field per control. Keep descriptions to one short line; put errors in `error`, not in the description.
66
+ - Inside `<Field>` the control picks up the label, description, error, required and disabled automatically — do not repeat them on the control.
67
+
68
+ ## Accessibility
69
+ - Label uses <label for> for labelable controls and aria-labelledby for groups; pressing it focuses or checks the control.
70
+ - Description and error are linked with aria-describedby; the error has role="alert".
71
+
72
+ ## DOM contract (for agents operating the page)
73
+
74
+ - Selector: `[data-sw="field"]`
75
+ - `data-invalid`: present when invalid
76
+ - `data-disabled`: present when disabled
77
+ - `data-required`: present when required
78
+ - How to operate: Find the control inside it; its accessible name is the [data-sw="field-label"] text. Errors are in [data-sw="field-error"].
79
+
80
+ Related: `label`, `input`, `textarea`
@@ -0,0 +1,84 @@
1
+ # FileInput
2
+
3
+ > Choose, drop or paste files; validate type, size and count; list them with remove; submit them with a form through a real file input.
4
+
5
+ Category: inputs · Status: beta · Slug: `file-input`
6
+
7
+ ```tsx
8
+ import { FileInput, formatFileSize } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Attachments, imports and uploads in a form.
13
+ - Context files for an agent prompt (paste a screenshot, drop a CSV).
14
+
15
+ ## Avoid
16
+ - A bare `<input type="file">` — no drop, paste, validation or list.
17
+ - Uploading inside this component. It only holds files; upload in your submit handler or `onValueChange`, and validate again on the server.
18
+ - Only a drop zone with no button. Keep the built-in Browse button for keyboard and screen-reader users.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `accept` | `string \| string[]` | | Like the accept attribute: "image/*", ".pdf", "application/json". |
25
+ | `multiple` | `boolean` | `false` | Hold more than one file. Without it a new file replaces the current one. |
26
+ | `maxFiles` | `number` | | Most files held (counts files already held). Extra files are rejected with "too-many-files". |
27
+ | `maxSize / minSize` | `number` | | Bytes per file. Rejected with "file-too-large" / "file-too-small". |
28
+ | `validate` | `(file: File) => string \| null \| void` | | Your own check; return a reason to reject. Runs after the built-in checks. |
29
+ | `value / defaultValue` | `File[]` | | Files, controlled or initial. A form reset returns to defaultValue. |
30
+ | `onValueChange` | `(files: File[]) => void` | | Files added or removed. |
31
+ | `onReject` | `(rejected: { file: File; reasons: string[] }[]) => void` | | Files that failed the checks, with every reason. |
32
+ | `variant` | `'dropzone' \| 'button'` | `'dropzone'` | A drop area with a button, or just the button. |
33
+ | `title / hint / buttonLabel` | `ReactNode` | | Drop-zone text. The hint is built from accept/maxSize/maxFiles by default. |
34
+ | `showList` | `boolean` | `true` | Show the file list. |
35
+ | `renderItem` | `(file: File, index: number) => ReactNode` | | Custom row content (remove button is added). |
36
+ | `name / form / required / disabled` | `string / boolean` | | Native form behavior via a real <input type="file"> kept in sync. |
37
+ | `aria-label` | `string` | | Names the control when it is not in a <Field>. |
38
+
39
+ ## Examples
40
+
41
+ ### Attachments in a form
42
+
43
+ ```tsx
44
+ <form method="post" encType="multipart/form-data">
45
+ <FileInput name="attachments" aria-label="Attachments" multiple accept="image/*,.pdf" maxSize={5_000_000} maxFiles={4} />
46
+ <Button type="submit">Send</Button>
47
+ </form>
48
+ ```
49
+
50
+ ### One file, button only
51
+
52
+ ```tsx
53
+ <FileInput variant="button" aria-label="Avatar" accept="image/png,image/jpeg" buttonLabel="Choose image"
54
+ onValueChange={([file]) => setFile(file ?? null)} />
55
+ ```
56
+
57
+ ### Custom validation
58
+
59
+ ```tsx
60
+ <FileInput multiple accept=".csv" aria-label="Datasets"
61
+ validate={(f) => (f.name.includes(' ') ? 'no spaces in names' : null)}
62
+ onReject={(r) => console.warn(r)} />
63
+ ```
64
+
65
+ ## Rules
66
+ - Dropzone shows a bare 20px icon (the dashed zone is the frame). File rows are sm squircles with a 1px frame; thumb and remove button are concentric with them.
67
+ - Tell people the limits: keep the auto hint or write your own `hint`.
68
+ - Validate on the server too; `accept` and `validate` are a convenience.
69
+ - Rejected files are listed in red under the zone; do not add a second error message for them.
70
+
71
+ ## Accessibility
72
+ - The Browse button opens the picker; the drop zone also takes pastes while focus is inside it.
73
+ - The list is one tab stop: arrows move between files, Delete/Backspace removes the focused one. Changes are announced in a polite live region.
74
+
75
+ ## DOM contract (for agents operating the page)
76
+
77
+ - Selector: `[data-sw="file-input"]`
78
+ - `data-dragging`: files over the zone
79
+ - `data-drag-accept / data-drag-reject (on dropzone)`: whether the dragged files look acceptable
80
+ - `data-invalid`: some files were rejected
81
+ - `data-disabled`: disabled
82
+ - How to operate: Agent bridge: clear(), remove(fileName), add(files), open(); items = held files (name + size). DOM: set files on the inner input[type=file] and dispatch "change"; remove with [data-sw="file-input-item-remove"].
83
+
84
+ Related: `field`, `input`, `image-cropper`
@@ -0,0 +1,64 @@
1
+ # HoverCard
2
+
3
+ > A preview card for a link (person, repo, doc) on hover or keyboard focus; the link still navigates.
4
+
5
+ Category: overlays · Status: beta · Slug: `hover-card`
6
+
7
+ ```tsx
8
+ import { HoverCard, HoverCardTrigger, HoverCardContent } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Previewing where a link goes: a profile, a PR, a model card.
13
+
14
+ ## Avoid
15
+ - Content only available in the card — touch users never see it; it must exist on the linked page.
16
+ - Opening on click → use Popover.
17
+ - Plain hints on buttons → use Tooltip.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `open` | `boolean` | | Controlled open state of the card. |
24
+ | `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
25
+ | `onOpenChange` | `(open: boolean) => void` | | Called when it wants to open or close (trigger, Close part, Escape, outside press…). |
26
+ | `delay` | `number` | `600` | ms the pointer or keyboard focus rests on the link before opening. |
27
+ | `closeDelay` | `number` | `300` | ms before closing once the pointer leaves link and card. The pointer can cross the gap. |
28
+ | `disabled` | `boolean` | `false` | Never open; a plain link remains. |
29
+ | `HoverCardTrigger.href` * | `string` | | The trigger is an <a>; give it an href. |
30
+ | `HoverCardTrigger.render` | `ReactElement \| ((props, state) => ReactElement)` | | Render a different element instead of the default <a>. 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. |
31
+ | `HoverCardContent.side / align / sideOffset` | `Side / Align / number` | `'bottom' / 'center' / 8` | Placement. Width 19rem (--sw-hover-card-width). |
32
+
33
+ ## Examples
34
+
35
+ ### Author preview
36
+
37
+ ```tsx
38
+ <Text>
39
+ Reviewed by{' '}
40
+ <HoverCard>
41
+ <HoverCardTrigger href="/people/mara">@mara</HoverCardTrigger>
42
+ <HoverCardContent>
43
+ <Text size="sm"><strong>Mara Lind</strong> — infra lead, owns the eval pipeline.</Text>
44
+ <Caption>Joined March 2024</Caption>
45
+ </HoverCardContent>
46
+ </HoverCard>
47
+ </Text>
48
+ ```
49
+
50
+ ## Rules
51
+ - Keep it a preview: avatar, name, one line, a stat or two.
52
+ - Use inside running text or lists of links.
53
+
54
+ ## Accessibility
55
+ - The trigger stays a plain link (Enter follows it). Escape closes the card and leaves focus on the link.
56
+ - Focus via keyboard opens after `delay`; a click-focus does not.
57
+
58
+ ## DOM contract (for agents operating the page)
59
+
60
+ - Selector: `[data-sw="hover-card-trigger"], [data-sw="hover-card-content"]`
61
+ - `data-state`: open | closed
62
+ - How to operate: Hover or focus the link and wait `delay` ms; the card is [data-sw="hover-card-content"] at the end of <body>. Agent bridge (kind "hover-card"): state {open}; actions open(), close(), toggle().
63
+
64
+ Related: `tooltip`, `popover`