@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,105 @@
1
+ # AppShell
2
+
3
+ > The frame of a dashboard: a header, a sidebar that folds to a rail, a main region and an inspector, all joined by 1px lines.
4
+
5
+ Category: layout · Status: beta · Slug: `app-shell`
6
+
7
+ ```tsx
8
+ import { AppShell, AppShellHeader, AppShellSidebar, AppShellMain, AppShellInspector, ShellToggle, useAppShell } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - The outer layout of an app or dashboard with persistent navigation.
13
+ - A master–detail view where a trailing inspector shows the selection.
14
+
15
+ ## Avoid
16
+ - Marketing or document pages — use the normal page layout (guides/05-layout).
17
+ - Spacing regions apart with gutters or giving each region its own card and shadow. Regions meet at hairlines.
18
+ - Nesting a second AppShell. Use Resizable or an Accordion inside AppShellMain.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `layout` | `'header-first' \| 'sidebar-first'` | `'header-first'` | header-first: the header spans the full width. sidebar-first: the sidebar runs the full height beside the header. |
25
+ | `sidebarOpen / defaultSidebarOpen / onSidebarOpenChange` | `boolean` | `true` | Sidebar expanded on wide layouts. Folded, it becomes a 48px rail or disappears. |
26
+ | `inspectorOpen / defaultInspectorOpen / onInspectorOpenChange` | `boolean` | `true` | Inspector open on wide layouts. |
27
+ | `collapseBelow` | `number` | `768` | Container width (px) below which the sidebar and inspector become sheets over the content. |
28
+ | `sidebarShortcut` | `string \| null` | `'mod+b'` | Keyboard toggle for the sidebar. |
29
+ | `inspectorShortcut` | `string \| null` | `'mod+alt+b'` | Keyboard toggle for the inspector. |
30
+ | `autoSaveId` | `string` | | Save open state and widths in localStorage under this key. |
31
+ | `height` | `CSS height` | `'100dvh'` | Shell height. Use '100%' inside a sized container. |
32
+ | `AppShellHeader.start / center / end` | `ReactNode` | | Put the linked logo and dashboard title in start, an optional search in center, and compact dashboard, site and account controls in end. |
33
+ | `AppShellSidebar.collapsible` | `'rail' \| 'offcanvas' \| 'none'` | `'rail'` | How the sidebar folds. |
34
+ | `AppShellSidebar / AppShellInspector .label` * | `string` | | Accessible name of the region. |
35
+ | `AppShellSidebar / AppShellInspector .header / footer` | `ReactNode` | | Pinned rows. The header matches the shell header height (44px). |
36
+ | `AppShellSidebar / AppShellInspector .defaultWidth / minWidth / maxWidth` | `number` | | Sidebar 248 (200–400). Inspector 320 (260–480). |
37
+ | `AppShellSidebar / AppShellInspector .resizable` | `boolean` | `true` | Resize from the inner edge. Drag past half the minimum width to fold it. Double-click or Enter toggles it. |
38
+ | `AppShellMain.header` | `ReactNode` | | Optional 44px content toolbar for a separate view title, tabs or filters. Omit it when the shell header holds the dashboard title and controls. |
39
+ | `AppShellMain.padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Padding of the scrolling content. Use 'none' for an edge-to-edge DashboardGrid. |
40
+ | `ShellToggle.side` | `'sidebar' \| 'inspector'` | `'sidebar'` | 28px icon button that toggles a region. Its tooltip shows the shortcut. |
41
+
42
+ ## Examples
43
+
44
+ ### Dashboard frame with one header
45
+
46
+ ```tsx
47
+ <AppShell autoSaveId="acme">
48
+ <AppShellHeader
49
+ start={
50
+ <>
51
+ <ShellToggle />
52
+ <Button href="/" size="xs" variant="ghost" iconOnly aria-label="Acme home" leading={<Icon name="activity" />} />
53
+ <Heading as="h1" size="sm" style={{ minWidth: 0, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>
54
+ Incident overview
55
+ </Heading>
56
+ </>
57
+ }
58
+ end={
59
+ <>
60
+ <ShellToggle side="inspector" />
61
+ <nav aria-label="Site" style={{ display: 'flex', gap: 'var(--sw-space-1)' }}>
62
+ <Button href="/projects" size="xs" variant="ghost">Projects</Button>
63
+ <Button href="/login" size="xs" variant="outline">Sign in</Button>
64
+ </nav>
65
+ </>
66
+ }
67
+ />
68
+ <AppShellSidebar label="Workspace">
69
+ <SidebarNav>
70
+ <SidebarItem icon={<Icon name="home" />} label="Overview" active href="#/" />
71
+ <SidebarItem icon={<Icon name="alert" />} label="Incidents" count={3} href="#/incidents" />
72
+ </SidebarNav>
73
+ </AppShellSidebar>
74
+ <AppShellMain padding="none">
75
+ <DashboardGrid aria-label="Overview">…</DashboardGrid>
76
+ </AppShellMain>
77
+ <AppShellInspector label="Details">
78
+ <Accordion size="sm" variant="plain" multiple fill defaultValue={['details', 'activity']}>…</Accordion>
79
+ </AppShellInspector>
80
+ </AppShell>
81
+ ```
82
+
83
+ ## Rules
84
+ - Regions meet at 1px lines. Never put gutters, shadows or separate cards between them.
85
+ - All headers share one height (44px), so the lines across columns align.
86
+ - Use one shell header for the dashboard logo, title, dashboard controls and site navigation. Omit the main header unless a view needs a separate content toolbar.
87
+ - Let the title truncate and move secondary controls into a labeled Menu or Popover when space is tight.
88
+ - Keep workspace navigation in the sidebar with at most two levels. Use trailing header links for site destinations.
89
+ - Do not hide the sidebar by default on wide screens. Let people fold it (⌘B) and remember the choice with autoSaveId.
90
+ - Do not put critical actions at the bottom of the sidebar.
91
+
92
+ ## Accessibility
93
+ - The sidebar and inspector are <aside> landmarks named by `label`. The main region is <main>.
94
+ - Resizers are role="separator" with aria-valuenow and keyboard control: ←/→ by 16px, Shift for 64px, Home/End, Enter folds.
95
+ - A folded region is inert. Sheets close with Escape or by clicking the scrim.
96
+ - ShellToggle has aria-expanded and aria-keyshortcuts.
97
+
98
+ ## DOM contract (for agents operating the page)
99
+
100
+ - Selector: `[data-sw="app-shell"]`
101
+ - `data-narrow`: present when the regions are sheets
102
+ - `data-state`: open | rail | closed on [data-sw="app-shell-sidebar"] and [data-sw="app-shell-inspector"]
103
+ - How to operate: Click [data-sw="shell-toggle"][data-side="sidebar|inspector"], or press ⌘B / ⌘⌥B. Agent bridge: toggleSidebar(), toggleInspector(), setSidebarOpen(bool), setInspectorOpen(bool). state = { narrow, sidebarOpen, inspectorOpen }.
104
+
105
+ Related: `sidebar-nav`, `card`, `dashboard-grid`, `accordion`, `breadcrumbs`, `resizable`
@@ -0,0 +1,56 @@
1
+ # AreaChart
2
+
3
+ > Volume over time; overlapping translucent areas or stacked part-to-whole. Built on Unovis VisArea.
4
+
5
+ Category: charts · Status: beta · Slug: `area-chart`
6
+
7
+ ```tsx
8
+ import { AreaChart, ChartCard } from '@peerproblem/sw3-ui/charts'
9
+ ```
10
+
11
+ ## When to use
12
+ - Totals over time.
13
+ - Stacked composition over time (`stacked`).
14
+
15
+ ## Avoid
16
+ - Overlapping more than 3 unstacked areas.
17
+
18
+ ## Props
19
+
20
+ | Prop | Type | Default | Description |
21
+ | --- | --- | --- | --- |
22
+ | `data` * | `D[]` | | Array of rows. |
23
+ | `x` * | `keyof D \| (d, i) => number \| Date \| string` | | X field. Numbers/Dates use a scale; strings become ordered categories. |
24
+ | `series` * | `Array<{ key: keyof D; label?: string; color?: string }>` | | One entry per plotted field. Colors default to --sw-chart-1..8 in order. |
25
+ | `height` | `number` | `240` | Pixels. Width fills the parent. |
26
+ | `xFormat / yFormat` | `(v) => string` | | Tick and tooltip formatting. y defaults to compact (12.4k). |
27
+ | `showXAxis / showYAxis / showGrid` | `boolean` | `true` | Axes and horizontal grid. |
28
+ | `tooltip` | `boolean` | `true` | Crosshair + tooltip on hover. |
29
+ | `yDomain` | `[min?, max?]` | | Fix the y range, e.g. [0, undefined]. |
30
+ | `aria-label` | `string` | | Text summary of the chart. Always set it — agents and screen readers cannot read SVG. |
31
+ | `stacked` | `boolean` | `false` | Stack series. |
32
+ | `line` | `boolean` | `true` | Stroke on top (unstacked only). |
33
+ | `curve` | `'smooth' \| 'linear' \| 'step'` | `'smooth'` | |
34
+
35
+ ## Examples
36
+
37
+ ### Stacked
38
+
39
+ ```tsx
40
+ <ChartCard title="Usage by plan">
41
+ <AreaChart aria-label="Usage by plan" stacked data={data} x="month" series={[{ key: 'free' }, { key: 'pro' }, { key: 'team' }]} />
42
+ </ChartCard>
43
+ ```
44
+
45
+ ## Rules
46
+ - Wrap the chart in <ChartCard> and give the card a title.
47
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
48
+ - Use the default palette order; color 1 (blue) is the primary series.
49
+ - Max 5 series per chart. Do not use dual y-axes.
50
+
51
+ ## DOM contract (for agents operating the page)
52
+
53
+ - Selector: `[data-sw="chart"]`
54
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
55
+ - `aria-label`: the summary
56
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
@@ -0,0 +1,47 @@
1
+ # useAsyncOptions
2
+
3
+ > Hook that loads list items as someone types: debounced, cancels stale requests, keeps old results while loading, pages with loadMore.
4
+
5
+ Category: hooks · Status: beta · Slug: `async-options`
6
+
7
+ ```tsx
8
+ import { useAsyncOptions } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Server-side search for Combobox, Select, Autocomplete or Command.
13
+ - Paged results that load as the list scrolls.
14
+
15
+ ## Avoid
16
+ - Fetching in an effect on every keystroke. Use this hook instead.
17
+ - Client-side filtering on top of server results. Turn the component filter off.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `loader` * | `(query, { signal, page }) => Promise<T[] \| { items: T[]; hasMore: boolean }>` | | Pass `signal` to fetch so replaced requests cancel. |
24
+ | `options.debounce` | `number` | `200` | Pause in ms before loading. |
25
+ | `options.query` | `string` | `''` | Starting search text. |
26
+ | `options.immediate` | `boolean` | `false` | Load the starting query on mount. |
27
+ | `returns` | `{ query, setQuery, items, status, error, hasMore, loadMore, reload }` | | `status` is 'idle' | 'loading' | 'error'. |
28
+
29
+ ## Examples
30
+
31
+ ### Search as you type
32
+
33
+ ```tsx
34
+ const repos = useAsyncOptions<{ value: string; label: string }>(async (q, { signal }) => {
35
+ const res = await fetch(`/api/repos?q=${encodeURIComponent(q)}`, { signal })
36
+ if (!res.ok) throw new Error('Could not load repos')
37
+ return res.json()
38
+ }, { immediate: true })
39
+
40
+ // <Combobox items={repos.items} onInputChange={repos.setQuery} loading={repos.status === 'loading'} />
41
+ ```
42
+
43
+ ## DOM contract (for agents operating the page)
44
+
45
+ - Selector: `(hook, no DOM)`
46
+
47
+ Related: `combobox`, `select`, `autocomplete`, `command`
@@ -0,0 +1,69 @@
1
+ # Autocomplete
2
+
3
+ > A text field with suggestions: the value is whatever is typed, and picking a suggestion fills it in.
4
+
5
+ Category: selection · Status: beta · Slug: `autocomplete`
6
+
7
+ ```tsx
8
+ import { Autocomplete, AutocompleteItem } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Search boxes with suggested queries.
13
+ - Free-text fields with common answers (city, tag, branch name).
14
+
15
+ ## Avoid
16
+ - The value must be one of the options — use Combobox or Select.
17
+ - Many actions — use Command.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `items` | `Array<{ value: string; label: string; keywords?: string[]; disabled?: boolean; icon?: ReactNode; description?: ReactNode } \| { type: 'group'; label: string; items: [...] } \| { type: 'separator' }>` | | Options as data — the one-line way. Or pass `<AutocompleteItem>` children instead. |
24
+ | `value / defaultValue / onValueChange` | `string / (text) => void` | | The text. |
25
+ | `onItemSelect` | `(item) => void` | | Runs when a suggestion is chosen (after the text becomes its label). |
26
+ | `filter` | `'contains' \| 'startsWith' \| false \| fn` | `'contains'` | How the text narrows suggestions. `false` for server results. |
27
+ | `autoHighlight` | `boolean` | `false` | Highlight the first suggestion so Enter takes it. Off: Enter keeps the typed text. |
28
+ | `openOnFocus` | `boolean` | `false` | Show suggestions on focus. |
29
+ | `loading / emptyMessage` | `boolean / ReactNode` | | Loading row; message when nothing matches (omit to just hide the list). |
30
+ | `clearable / label / icon / placeholder` | `boolean / ReactNode / ReactNode / string` | | Clear button, visible label, leading icon, placeholder. |
31
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field heights 32 / 40 / 52px, like Input. |
32
+ | `...input props` | `InputHTMLAttributes` | | `name`, `required`, `disabled`, `aria-label`… go to the native input. |
33
+
34
+ ## Examples
35
+
36
+ ### Search with suggestions
37
+
38
+ ```tsx
39
+ <Autocomplete aria-label="Search docs" icon={<Icon name="search" />} placeholder="Search docs…" items={[
40
+ { value: 'streaming', label: 'Streaming responses' },
41
+ { value: 'tools', label: 'Tool use' },
42
+ { value: 'caching', label: 'Prompt caching' },
43
+ ]} />
44
+ ```
45
+
46
+ ### Children
47
+
48
+ ```tsx
49
+ <Autocomplete label="Branch" name="branch" defaultValue="main">
50
+ <AutocompleteItem value="main">main</AutocompleteItem>
51
+ <AutocompleteItem value="dev">dev</AutocompleteItem>
52
+ </Autocomplete>
53
+ ```
54
+
55
+ ## Rules
56
+ - Inside `<Field>` the control picks up label, description, error, required and disabled automatically; do not repeat them.
57
+ - Suggestions help but never restrict: any typed text is a valid value.
58
+
59
+ ## Accessibility
60
+ - Input role="combobox", aria-autocomplete="list", aria-activedescendant; ArrowDown opens/moves, Enter takes the highlighted suggestion, Escape closes (again: clears).
61
+
62
+ ## DOM contract (for agents operating the page)
63
+
64
+ - Selector: `[data-sw="autocomplete"]`
65
+ - `aria-expanded`: on the input while suggestions show
66
+ - `data-value`: on each [role=option]
67
+ - How to operate: Type into [data-sw="autocomplete-input"]; optionally click a [role=option]. Agent bridge: setValue(text), select(valueOrLabel), clear(), open(), close(); items = current suggestions.
68
+
69
+ Related: `combobox`, `input`, `command`
@@ -0,0 +1,88 @@
1
+ # Avatar
2
+
3
+ > A person or team picture that shows initials (or an icon) while the image loads and if it fails; AvatarGroup overlaps several with a "+N" count.
4
+
5
+ Category: display · Status: beta · Slug: `avatar`
6
+
7
+ ```tsx
8
+ import { Avatar, AvatarGroup, AvatarImage, AvatarFallback } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - A person, team, workspace or bot next to their content: comments, member lists, account menus, activity feeds.
13
+ - A stack of collaborators or reviewers: `<AvatarGroup max={4}>`.
14
+
15
+ ## Avoid
16
+ - Hand-rolled `<img>` circles — they flash a broken image on error. Use Avatar with `name` so initials take over.
17
+ - Circle for non-people. Use `shape="squircle"` for teams, workspaces, apps and bots.
18
+ - A missing name. Without `name` (or `alt`) screen readers announce nothing; pass `alt=""` only when a visible name sits beside it.
19
+ - Using it as a button by itself. Wrap it in a Button or link with an accessible name instead.
20
+
21
+ ## Props
22
+
23
+ | Prop | Type | Default | Description |
24
+ | --- | --- | --- | --- |
25
+ | `src` | `string` | | Image URL. Shorthand that renders AvatarImage + AvatarFallback for you. |
26
+ | `name` | `string` | | Person or team name. Gives the fallback initials and the accessible name. |
27
+ | `alt` | `string` | `name` | Image alt text. `""` when a visible name already identifies the person. |
28
+ | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | `'md' (group: the group's size)` | 20 / 28 / 36 / 48 / 64px, or px. |
29
+ | `shape` | `'circle' \| 'squircle'` | `'circle'` | circle for people, squircle for teams, workspaces and bots. |
30
+ | `presence` | `'online' \| 'away' \| 'busy' \| 'offline'` | | Status dot in the corner. |
31
+ | `delay` | `number` | | ms before the fallback shows, so a fast image does not flash initials. |
32
+ | `onLoadingStatusChange` | `(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void` | | Runs when the image status changes. |
33
+ | `children` | `ReactNode` | | Compound use: <AvatarImage src alt/> + <AvatarFallback>…</AvatarFallback>. Overrides the shorthand. |
34
+ | `AvatarImage.src / alt` * | `string` | | A real <img>, hidden until it loads. |
35
+ | `AvatarFallback.delay` | `number` | | Wait before showing the fallback. |
36
+ | `AvatarGroup.max` | `number` | | Show at most this many, then a "+N" bubble. |
37
+ | `AvatarGroup.size / shape` | `AvatarSize \| number / AvatarShape` | `'sm'` | Applied to every avatar inside. |
38
+ | `AvatarGroup.overlap` | `number` | `0.28` | Overlap as a share of the avatar size. |
39
+ | `AvatarGroup.aria-label` | `string` | | Names the group, e.g. "Reviewers". |
40
+
41
+ ## Examples
42
+
43
+ ### With fallback
44
+
45
+ ```tsx
46
+ <Avatar src="/ada.png" name="Ada Lovelace" />
47
+ <Avatar name="Grace Hopper" presence="online" />
48
+ <Avatar name="Deploy Bot" shape="squircle" size="lg" />
49
+ ```
50
+
51
+ ### Group
52
+
53
+ ```tsx
54
+ <AvatarGroup aria-label="Reviewers" max={3} size="sm">
55
+ <Avatar name="Ada Lovelace" src="/ada.png" />
56
+ <Avatar name="Grace Hopper" src="/grace.png" />
57
+ <Avatar name="Alan Turing" />
58
+ <Avatar name="Linus Torvalds" />
59
+ </AvatarGroup>
60
+ ```
61
+
62
+ ### Compound parts
63
+
64
+ ```tsx
65
+ <Avatar size="lg">
66
+ <AvatarImage src="/team.png" alt="Platform team" />
67
+ <AvatarFallback delay={300}>PT</AvatarFallback>
68
+ </Avatar>
69
+ ```
70
+
71
+ ## Rules
72
+ - Always pass `name` (or alt) so the fallback has initials and screen readers a name.
73
+ - One size per row or group. Use `xs`/`sm` in dense lists, `md` in comments, `lg`/`xl` on profile headers.
74
+ - Avatars never carry the accent color; presence dots use success / orange / danger tokens.
75
+
76
+ ## Accessibility
77
+ - The image has alt text (the name by default); the fallback includes the name as visually hidden text.
78
+ - AvatarGroup is role="group"; the "+N" bubble reads "N more".
79
+
80
+ ## DOM contract (for agents operating the page)
81
+
82
+ - Selector: `[data-sw="avatar"]`
83
+ - `data-loading-status`: 'idle' | 'loading' | 'loaded' | 'error'
84
+ - `data-shape`: 'circle' | 'squircle'
85
+ - `data-presence`: 'online' | 'away' | 'busy' | 'offline'
86
+ - How to operate: Display only. Read the person from the img alt or the visually hidden name; groups are [data-sw="avatar-group"] with a [data-sw="avatar-group-more"] count.
87
+
88
+ Related: `badge`, `timeline`
@@ -0,0 +1,51 @@
1
+ # Badge
2
+
3
+ > A small pill label for status, counts and tags.
4
+
5
+ Category: display · Status: stable · Slug: `badge`
6
+
7
+ ```tsx
8
+ import { Badge } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - Status (Live, Advisory, Draft, Failed).
13
+ - Version and release labels.
14
+
15
+ ## Avoid
16
+ - Using badges as buttons.
17
+ - Sentences inside badges.
18
+
19
+ ## Props
20
+
21
+ | Prop | Type | Default | Description |
22
+ | --- | --- | --- | --- |
23
+ | `variant` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'outline' \| 'inverse'` | `'neutral'` | Color. Use warning for a status that needs attention. |
24
+ | `leading` | `ReactNode` | | Optional decorative icon before the label. |
25
+ | `pulse` | `boolean` | `false` | Decorative status dot. Static when reduced motion is enabled. |
26
+ | `dot` | `boolean` | `false` | Deprecated. Use leading. Existing success, warning and danger badges use a corresponding status icon. |
27
+ | `mono` | `boolean` | `false` | Opt in to uppercase monospace lettering. Standard badges preserve the original text case. |
28
+
29
+ ## Examples
30
+
31
+ ### Status
32
+
33
+ ```tsx
34
+ import { Badge, Icon } from '@peerproblem/sw3-ui'
35
+
36
+ <Badge variant="success" leading={<Icon name="check" weight={2} />}>Live</Badge>
37
+ <Badge variant="warning" leading={<Icon name="alert" weight={2} />}>Advisory</Badge>
38
+ <Badge variant="outline">Draft</Badge>
39
+ <Badge variant="inverse">v0.1</Badge>
40
+ ```
41
+
42
+ ## Rules
43
+ - Use a leading icon when it helps identify the status. Leave simple labels and version numbers as text.
44
+
45
+ ## Accessibility
46
+ - Use visible child text to communicate the status. The optional decorative icon is hidden from screen readers.
47
+
48
+ ## DOM contract (for agents operating the page)
49
+
50
+ - Selector: `[data-sw="badge"]`
51
+ - `data-variant`: variant
@@ -0,0 +1,56 @@
1
+ # BarChart
2
+
3
+ > Compare categories, grouped or stacked, vertical or horizontal. Built on Unovis VisGroupedBar / VisStackedBar.
4
+
5
+ Category: charts · Status: beta · Slug: `bar-chart`
6
+
7
+ ```tsx
8
+ import { BarChart, ChartCard } from '@peerproblem/sw3-ui/charts'
9
+ ```
10
+
11
+ ## When to use
12
+ - Comparing discrete categories.
13
+ - Composition per category (`mode="stacked"`).
14
+
15
+ ## Avoid
16
+ - Time series with many points — use LineChart.
17
+
18
+ ## Props
19
+
20
+ | Prop | Type | Default | Description |
21
+ | --- | --- | --- | --- |
22
+ | `data` * | `D[]` | | Array of rows. |
23
+ | `x` * | `keyof D \| (d, i) => number \| Date \| string` | | X field. Numbers/Dates use a scale; strings become ordered categories. |
24
+ | `series` * | `Array<{ key: keyof D; label?: string; color?: string }>` | | One entry per plotted field. Colors default to --sw-chart-1..8 in order. |
25
+ | `height` | `number` | `240` | Pixels. Width fills the parent. |
26
+ | `xFormat / yFormat` | `(v) => string` | | Tick and tooltip formatting. y defaults to compact (12.4k). |
27
+ | `showXAxis / showYAxis / showGrid` | `boolean` | `true` | Axes and horizontal grid. |
28
+ | `tooltip` | `boolean` | `true` | Crosshair + tooltip on hover. |
29
+ | `yDomain` | `[min?, max?]` | | Fix the y range, e.g. [0, undefined]. |
30
+ | `aria-label` | `string` | | Text summary of the chart. Always set it — agents and screen readers cannot read SVG. |
31
+ | `mode` | `'grouped' \| 'stacked'` | `'grouped'` | |
32
+ | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | |
33
+ | `barRadius` | `number` | `4` | Bar corner radius in px. |
34
+
35
+ ## Examples
36
+
37
+ ### Grouped
38
+
39
+ ```tsx
40
+ <ChartCard title="Regional performance">
41
+ <BarChart aria-label="Q3 beat Q2 in every region" data={regions} x="region" series={[{ key: 'q2', label: 'Q2' }, { key: 'q3', label: 'Q3' }]} />
42
+ </ChartCard>
43
+ ```
44
+
45
+ ## Rules
46
+ - Wrap the chart in <ChartCard> and give the card a title.
47
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
48
+ - Use the default palette order; color 1 (blue) is the primary series.
49
+ - Max 5 series per chart. Do not use dual y-axes.
50
+
51
+ ## DOM contract (for agents operating the page)
52
+
53
+ - Selector: `[data-sw="chart"]`
54
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
55
+ - `aria-label`: the summary
56
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
@@ -0,0 +1,49 @@
1
+ # BarList
2
+
3
+ > Ranked rows with a bar behind each label: top endpoints, traffic by country, spend by team. The bar is the row background.
4
+
5
+ Category: charts · Status: beta · Slug: `bar-list`
6
+
7
+ ```tsx
8
+ import { BarList } from '@peerproblem/sw3-ui/charts'
9
+ ```
10
+
11
+ ## When to use
12
+ - Top-N rankings in a tile.
13
+ - Share of a total where reading the label matters more than the shape.
14
+
15
+ ## Avoid
16
+ - Values over time. Use TrendChart.
17
+ - More than about 10 rows. Page them with `Pagination variant="compact"` and a Carousel, or link to a full table.
18
+ - Negative values.
19
+
20
+ ## Props
21
+
22
+ | Prop | Type | Default | Description |
23
+ | --- | --- | --- | --- |
24
+ | `items` * | `{ id; label; value; icon?; meta?; href? }[]` | | Rows. `meta` is a quieter second value, such as a share. |
25
+ | `format` | `(n) => string` | `compact` | Value column format. |
26
+ | `max` | `number` | | Scale against this instead of the largest value (a quota, or the first page when paging). |
27
+ | `sorted` | `boolean` | `true` | Largest first. |
28
+ | `onItemAction` | `(id) => void` | | Rows become buttons for drilling in. Rows with `href` are links. |
29
+ | `aria-label` * | `string` | | Name of the list. |
30
+
31
+ ## Examples
32
+
33
+ ### Top endpoints
34
+
35
+ ```tsx
36
+ <BarList aria-label="Top endpoints" items={[{ id: 'a', label: 'GET /v1/charges', value: 412000, meta: '38%' }, { id: 'b', label: 'POST /v1/charges', value: 188000, meta: '17%' }]} />
37
+ ```
38
+
39
+ ## Rules
40
+ - Bars are a 15% tint of --sw-chart-1. The value sits outside the bar, right-aligned in tabular figures.
41
+ - When paging, pass `max` from the first page so bars stay comparable across pages.
42
+
43
+ ## DOM contract (for agents operating the page)
44
+
45
+ - Selector: `[data-sw="bar-list"]`
46
+ - `data-rank`: on each [data-sw="bar-list-row"]
47
+ - How to operate: Agent bridge: open(id) when rows are actions. state = { items }.
48
+
49
+ Related: `trend-chart`, `listbox`, `pagination`
@@ -0,0 +1,43 @@
1
+ # Breadcrumbs
2
+
3
+ > Where you are in the hierarchy ("Acme / API / Incidents") for the shell header. Middle items shrink first.
4
+
5
+ Category: navigation · Status: beta · Slug: `breadcrumbs`
6
+
7
+ ```tsx
8
+ import { Breadcrumbs } from '@peerproblem/sw3-ui'
9
+ ```
10
+
11
+ ## When to use
12
+ - The leading slot of AppShellHeader, in apps with workspace → project → page levels.
13
+
14
+ ## Avoid
15
+ - Repeating the sidebar. Show the levels the sidebar doesn't.
16
+ - Navigation between sibling pages. Use the sidebar or Tabs.
17
+
18
+ ## Props
19
+
20
+ | Prop | Type | Default | Description |
21
+ | --- | --- | --- | --- |
22
+ | `items` * | `{ label; href?; onClick?; icon? }[]` | | From the root to the current page. The last item is the current page. |
23
+
24
+ ## Examples
25
+
26
+ ### Header path
27
+
28
+ ```tsx
29
+ <Breadcrumbs items={[{ label: 'Acme', href: '#/' }, { label: 'API', href: '#/api' }, { label: 'Incidents' }]} />
30
+ ```
31
+
32
+ ## Rules
33
+ - Keep it to 2–4 levels.
34
+
35
+ ## Accessibility
36
+ - <nav aria-label="Breadcrumb"> with an ordered list. The last item has aria-current="page".
37
+
38
+ ## DOM contract (for agents operating the page)
39
+
40
+ - Selector: `[data-sw="breadcrumbs"]`
41
+ - How to operate: Click a link in the list.
42
+
43
+ Related: `app-shell`