@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,778 @@
1
+ # SW3 UI SDK · Charts
2
+
3
+ > @peerproblem/sw3-ui/charts: which chart answers which question, ChartCard, labeling, raw Unovis inside ChartSurface.
4
+
5
+ Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
6
+ Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
7
+ Index of all topics and components: llms.txt.
8
+
9
+ ---
10
+
11
+ # Charts
12
+
13
+ Import from `@peerproblem/sw3-ui/charts`. They're thin wrappers over [Unovis](https://unovis.dev) (`@unovis/react`). Unovis CSS variables are mapped to SW3 tokens in `charts.css`, so they follow light and dark automatically.
14
+
15
+ | Question | Chart |
16
+ | --- | --- |
17
+ | How does it change over time? | `LineChart` (or `AreaChart` for volume) |
18
+ | How do categories compare? | `BarChart` |
19
+ | What is it made of? | `AreaChart stacked`, `BarChart mode="stacked"`, or `DonutChart` (≤ 6 slices) |
20
+ | Do two measures move together? | `ScatterChart` |
21
+ | Which way is the KPI going? | `Sparkline` inside `Stat` |
22
+
23
+ ## Rules
24
+
25
+ 1. Every chart sits in a `ChartCard` with a title and (usually) a description of the unit or range.
26
+ 2. Every chart has `aria-label` stating the takeaway. Agents read this; they can't read SVG.
27
+ 3. Data shape is always an array of flat objects. `x` is a field name; `series` lists the numeric fields.
28
+ 4. ≤ 5 series. No dual axes. No 3D. No rainbow palettes; use the default order.
29
+ 5. Put range switches (`SegmentedControl size="sm"`) in `ChartCard actions`.
30
+
31
+ ## Need a chart we don't wrap yet?
32
+
33
+ Use Unovis directly inside `<ChartSurface aria-label="…">` (from `@peerproblem/sw3-ui/charts`), inside a `ChartCard`. Every `--vis-*`
34
+ variable — axes, legends, tooltips, crosshairs, brushes, annotations, plot bands, sankey, graph, timeline, chord, nested
35
+ donut, treemap, heatmap, radial/circular bars, TopoJSON and Leaflet maps — resolves to an SW3 token, in light and dark.
36
+
37
+ ```tsx
38
+ import { ChartCard, ChartSurface } from '@peerproblem/sw3-ui/charts'
39
+ import { VisSingleContainer, VisSankey } from '@unovis/react'
40
+
41
+ <ChartCard title="Energy flow" description="Quadrillion Btu, 2024">
42
+ <ChartSurface name="sankey" aria-label="Most U.S. energy is lost as heat before it reaches end use">
43
+ <VisSingleContainer data={{ nodes, links }} height={420}>
44
+ <VisSankey label={(n) => n.label} />
45
+ </VisSingleContainer>
46
+ </ChartSurface>
47
+ </ChartCard>
48
+ ```
49
+
50
+ Rules for raw Unovis charts:
51
+
52
+ - Colours come from tokens: `var(--sw-chart-1…8)` for categories (in order), `var(--sw-foreground)`,
53
+ `var(--sw-muted-foreground)`, `var(--sw-hairline)` for ink. No hex. Sequential scales: `color-mix()` of a chart token with `--sw-muted`.
54
+ - Controls around the chart (filters, toggles) are SW3 components with accessible names.
55
+ - Tooltip templates use the `.sw-tt` classes (`sw-tt__title`, `sw-tt__row`, `sw-tt__swatch`, `sw-tt__name`, `sw-tt__value`).
56
+ - Unovis cannot read `var()` where it computes colours itself (contrast checks on chord/nested-donut labels, colour
57
+ interpolation, canvas). There, resolve the token first — `getComputedStyle(el).getPropertyValue('--sw-chart-1')` — and
58
+ recompute when the theme changes.
59
+ - Leaflet maps use a keyless MapLibre style (e.g. OpenFreeMap `positron` / `dark`) that follows the theme.
60
+
61
+ ## Chart gallery
62
+
63
+ Every example from the Unovis gallery (https://unovis.dev/gallery) is ported to SW3 in the playground at `#/charts`
64
+ (source: `apps/playground/src/gallery/<slug>/index.tsx`). The docs site also serves `/chart-gallery.json`, which lists each one
65
+ with its collection, the Unovis components it uses and a build prompt. It is a reference, not part of the package: pick the
66
+ chart from the question below, then open the example if you need a starting point.
67
+
68
+ | Question | Unovis components | Gallery examples |
69
+ | --- | --- | --- |
70
+ | How does it change over time? | `VisLine`, `VisArea` | multi-line-chart, data-gap-line-chart, non-stacked-area-chart |
71
+ | What is it made of, over time? | `VisArea` (stacked), `VisStackedBar` | stacked-area-chart, crosshair-stacked-bar |
72
+ | How do categories compare? | `VisGroupedBar`, `VisStackedBar` (horizontal) | basic-grouped-bar, horizontal-stacked-bar-chart, state-migration-balance |
73
+ | How does a total build up? | `VisStackedBar` as a waterfall | waterfall-chart |
74
+ | How is a measure distributed? | `VisBoxplot`, `VisStackedBar` histogram | penguin-distributions, bike-trip-distributions |
75
+ | Do two measures move together? | `VisScatter` (+ `VisFreeBrush`) | basic-scatter-plot, sized-scatter-plot, free-brush-scatters |
76
+ | When did things start and end? | `VisTimeline` | basic-timeline, python-release-timeline |
77
+ | Where does it flow? | `VisSankey`, `VisChordDiagram` | energy-flow-sankey, expandable-sankey, state-migration-chord |
78
+ | How is it connected? | `VisGraph` (force, dagre, elk, parallel) | force-graph, dagre-graph, elk-layered-graph, dependency-explorer |
79
+ | What share is it (hierarchy)? | `VisDonut`, `VisNestedDonut`, `VisTreemap` | basic-donut-chart, sunburst-nested-donut, treemap |
80
+ | How close to a goal? | `VisRadialBar`, `VisCircularBar` | basic-radial-bar-chart, basic-circular-bar-chart |
81
+ | When is it busy? | `VisHeatmap` | bike-demand-heatmap, github-style-heatmap |
82
+ | Where is it? | `VisTopoJSONMap`, `VisLeafletMap`, `VisLeafletFlowMap` | topojson-map, airport-passenger-flows, basic-leaflet-map |
83
+ | What should the reader notice? | `VisAnnotations`, `VisPlotband`, `VisPlotline`, `VisCrosshair`, `VisBrush` | basic-annotations, plotband-plotline, synced-crosshairs, brush-grouped-bar |
84
+
85
+ ---
86
+
87
+ # Components
88
+
89
+ # TrendChart
90
+
91
+ > A small time-series chart for dashboard tiles and KPI cells. The fill fades to nothing, the line is 2px, the latest value gets a dot, a crosshair scrubs, and there are options for a previous period, a threshold, event markers and an unfinished last bucket.
92
+
93
+ Category: charts · Status: beta · Slug: `trend-chart`
94
+
95
+ ```tsx
96
+ import { TrendChart } from '@peerproblem/sw3-ui/charts'
97
+ ```
98
+
99
+ ## When to use
100
+ - One metric over time in a DashboardTile or a Card with a title: requests per hour, latency per day.
101
+ - The panel of `<Tabs variant="metric">`, plotting the selected KPI.
102
+ - Counts per bucket (`variant="bars"`), with a threshold line for an SLO.
103
+
104
+ ## Avoid
105
+ - More than one main series, or several metrics with different units. Use LineChart/AreaChart from @peerproblem/sw3-ui/charts.
106
+ - Showing the previous period in a second color. `compare` draws it as a paler tint of the same hue.
107
+ - Flat fills with a hard bottom edge, default axes, or long draw-in animations. These are what make charts look generic.
108
+
109
+ ## Props
110
+
111
+ | Prop | Type | Default | Description |
112
+ | --- | --- | --- | --- |
113
+ | `values` * | `number[]` | | The series, oldest first. |
114
+ | `labels` | `string[]` | | Label per value. The x axis shows the first, the last and up to three between. |
115
+ | `compare` | `number[]` | | Previous period, drawn as a pale tint of the same hue. |
116
+ | `seriesLabels` | `[string, string]` | `['Now', 'Previous']` | Names in the tooltip. |
117
+ | `variant` | `'area' \| 'line' \| 'bars'` | `'area'` | Area: a fill that fades to 0. Bars: counts per bucket, with the latest bar at full strength. |
118
+ | `tone` | `'chart' \| 'neutral' \| 'success' \| 'warning' \| 'danger'` | `'chart'` | Color source. Use neutral ink for quiet tiles and status colors only for status. |
119
+ | `height` | `number` | `180 (spark 36)` | Keep tiles in a row the same height. |
120
+ | `spark` | `boolean` | `false` | No axes, grid or padding. The shape runs to the edges. |
121
+ | `incomplete` | `boolean` | `false` | The last bucket is still filling. Its segment is dashed so it does not read as a drop. |
122
+ | `threshold` | `{ value: number; label?: string }` | | Target or limit, drawn as a dashed warning line. With bars, bars above it take the warning color. |
123
+ | `markers` | `{ index: number; label: string }[]` | | Events (deploys, incidents) as ticks on the baseline, named in the tooltip. |
124
+ | `format` | `(n) => string` | `compact (1.2k)` | Value format for labels and the tooltip. |
125
+ | `onScrub` | `(index \| null) => void` | | Fires while scrubbing. Use it to rewrite the header number, Stripe style. |
126
+ | `live` | `boolean` | `false` | The latest dot pulses. For streaming data only. |
127
+ | `aria-label` * | `string` | | The takeaway in one sentence. |
128
+
129
+ ## Examples
130
+
131
+ ### Tile with the previous period, deploys and an unfinished hour
132
+
133
+ ```tsx
134
+ <DashboardTile id="requests" span={8} title="Requests" count="24h">
135
+ <TrendChart
136
+ aria-label="Requests peaked near 75k at 15:00, above yesterday"
137
+ values={today} compare={yesterday} seriesLabels={['Today', 'Yesterday']}
138
+ labels={hours} incomplete
139
+ markers={[{ index: 10, label: 'Deploy api@4.12.0' }]}
140
+ />
141
+ </DashboardTile>
142
+ ```
143
+
144
+ ### Scrub the header number
145
+
146
+ ```tsx
147
+ const [i, setI] = useState<number | null>(null)
148
+ <Card title="Requests" actions={<span>{fmt(values[i ?? values.length - 1])}</span>}>
149
+ <TrendChart aria-label="…" values={values} labels={hours} onScrub={setI} />
150
+ </Card>
151
+ ```
152
+
153
+ ## Rules
154
+ - One question per chart. The tile title says what it measures.
155
+ - Area and bars start at 0. Line and spark zoom to the data.
156
+ - Animation runs once, on first mount, for about 500ms. Hover feedback stays at 100ms or less.
157
+ - Label the axis sparsely: at most 5 x labels, and 2–3 y values inside the plot.
158
+
159
+ ## Accessibility
160
+ - role="img" named by aria-label. It is focusable: ←/→ step through points, Home/End jump, and each value is announced in a polite live region.
161
+
162
+ ## DOM contract (for agents operating the page)
163
+
164
+ - Selector: `[data-sw="trend-chart"]`
165
+ - `data-variant`: area | line | bars
166
+ - `data-scrubbing`: present while a point is active
167
+
168
+ Related: `tabs`, `stat`, `dashboard-grid`, `bar-list`, `tracker`, `line-chart`
169
+
170
+ ---
171
+
172
+ # BarList
173
+
174
+ > Ranked rows with a bar behind each label: top endpoints, traffic by country, spend by team. The bar is the row background.
175
+
176
+ Category: charts · Status: beta · Slug: `bar-list`
177
+
178
+ ```tsx
179
+ import { BarList } from '@peerproblem/sw3-ui/charts'
180
+ ```
181
+
182
+ ## When to use
183
+ - Top-N rankings in a tile.
184
+ - Share of a total where reading the label matters more than the shape.
185
+
186
+ ## Avoid
187
+ - Values over time. Use TrendChart.
188
+ - More than about 10 rows. Page them with `Pagination variant="compact"` and a Carousel, or link to a full table.
189
+ - Negative values.
190
+
191
+ ## Props
192
+
193
+ | Prop | Type | Default | Description |
194
+ | --- | --- | --- | --- |
195
+ | `items` * | `{ id; label; value; icon?; meta?; href? }[]` | | Rows. `meta` is a quieter second value, such as a share. |
196
+ | `format` | `(n) => string` | `compact` | Value column format. |
197
+ | `max` | `number` | | Scale against this instead of the largest value (a quota, or the first page when paging). |
198
+ | `sorted` | `boolean` | `true` | Largest first. |
199
+ | `onItemAction` | `(id) => void` | | Rows become buttons for drilling in. Rows with `href` are links. |
200
+ | `aria-label` * | `string` | | Name of the list. |
201
+
202
+ ## Examples
203
+
204
+ ### Top endpoints
205
+
206
+ ```tsx
207
+ <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%' }]} />
208
+ ```
209
+
210
+ ## Rules
211
+ - Bars are a 15% tint of --sw-chart-1. The value sits outside the bar, right-aligned in tabular figures.
212
+ - When paging, pass `max` from the first page so bars stay comparable across pages.
213
+
214
+ ## DOM contract (for agents operating the page)
215
+
216
+ - Selector: `[data-sw="bar-list"]`
217
+ - `data-rank`: on each [data-sw="bar-list-row"]
218
+ - How to operate: Agent bridge: open(id) when rows are actions. state = { items }.
219
+
220
+ Related: `trend-chart`, `listbox`, `pagination`
221
+
222
+ ---
223
+
224
+ # Tracker
225
+
226
+ > Status ticks over time, one per day or run (uptime, checks, job runs). Hover or use ←/→ to read a tick.
227
+
228
+ Category: charts · Status: beta · Slug: `tracker`
229
+
230
+ ```tsx
231
+ import { Tracker } from '@peerproblem/sw3-ui/charts'
232
+ ```
233
+
234
+ ## When to use
235
+ - Uptime or check history on a service tile.
236
+ - The outcome of each recent run of a job.
237
+
238
+ ## Avoid
239
+ - Continuous values. Use TrendChart.
240
+ - Fewer than about 14 ticks. A short list says it better.
241
+
242
+ ## Props
243
+
244
+ | Prop | Type | Default | Description |
245
+ | --- | --- | --- | --- |
246
+ | `items` * | `{ status: 'ok' \| 'degraded' \| 'down' \| 'none'; label: string }[]` | | One tick per period, oldest first. 30–90 read best. |
247
+ | `height` | `number` | `24` | Tick height in px. |
248
+ | `aria-label` * | `string` | | The summary, e.g. "API uptime, last 60 days: 99.94%". |
249
+
250
+ ## Examples
251
+
252
+ ### Uptime
253
+
254
+ ```tsx
255
+ <Tracker aria-label="API uptime, 60 days: 99.94%" items={days.map((d) => ({ status: d.ok ? 'ok' : 'down', label: `${d.date} · ${d.uptime}` }))} />
256
+ ```
257
+
258
+ ## Rules
259
+ - Status colors only: success, warning, danger, and muted for no data.
260
+ - Put the summary number (99.94%) in the tile header, not over the ticks.
261
+
262
+ ## Accessibility
263
+ - role="img" named by the summary. It is focusable, ←/→ read ticks, and the active tick is announced.
264
+
265
+ ## DOM contract (for agents operating the page)
266
+
267
+ - Selector: `[data-sw="tracker"]`
268
+ - `data-status`: on each tick
269
+
270
+ Related: `trend-chart`, `badge`
271
+
272
+ ---
273
+
274
+ # ChartCard
275
+
276
+ > A Card laid out for a chart: title, description, headline value, actions, chart, legend.
277
+
278
+ Category: charts · Status: beta · Slug: `chart-card`
279
+
280
+ ```tsx
281
+ import { ChartCard, BarChart } from '@peerproblem/sw3-ui/charts'
282
+ import { SegmentedControl } from '@peerproblem/sw3-ui'
283
+ ```
284
+
285
+ ## When to use
286
+ - Every chart on a dashboard.
287
+
288
+ ## Avoid
289
+ - Putting two charts in one ChartCard.
290
+
291
+ ## Props
292
+
293
+ | Prop | Type | Default | Description |
294
+ | --- | --- | --- | --- |
295
+ | `title` * | `ReactNode` | | |
296
+ | `description` | `ReactNode` | | Time range or unit. |
297
+ | `value` | `ReactNode` | | Headline number, top right. |
298
+ | `actions` | `ReactNode` | | e.g. a SegmentedControl for the range. |
299
+ | `legend` | `Array<{ key; label?; color? }>` | | Legend under the chart, same order as series. |
300
+ | `...Card props` | `CardProps` | | variant, pattern, radius… |
301
+
302
+ ## Examples
303
+
304
+ ### With range switch
305
+
306
+ ```tsx
307
+ <ChartCard title="Revenue" description="USD" actions={<SegmentedControl size="sm" aria-label="Range" value={r} onValueChange={setR} options={ranges} />}>
308
+ <BarChart aria-label="Revenue by month" data={rows} x="month" series={[{ key: 'revenue' }]} />
309
+ </ChartCard>
310
+ ```
311
+
312
+ ## DOM contract (for agents operating the page)
313
+
314
+ - Selector: `[data-sw="chart-card"]`
315
+
316
+ ---
317
+
318
+ # ChartSurface
319
+
320
+ > Themes any raw @unovis/react chart with SW3 tokens — for Sankey, Graph, Timeline, Chord, Heatmap, maps and every other Unovis type.
321
+
322
+ Category: charts · Status: beta · Slug: `chart-surface`
323
+
324
+ ```tsx
325
+ import { ChartSurface, ChartCard } from '@peerproblem/sw3-ui/charts'
326
+ import { VisSingleContainer, VisSankey } from '@unovis/react'
327
+ ```
328
+
329
+ ## When to use
330
+ - A chart type without an SW3 wrapper (see the chart gallery on the docs site, #/charts).
331
+ - Composing several Unovis components (crosshair, brush, annotations, plot bands) in one container.
332
+
333
+ ## Avoid
334
+ - Line, area, bar, scatter, donut, sparkline or treemap charts — use the wrappers.
335
+ - Hex colours inside the chart — use var(--sw-chart-1…8).
336
+
337
+ ## Props
338
+
339
+ | Prop | Type | Default | Description |
340
+ | --- | --- | --- | --- |
341
+ | `aria-label` * | `string` | | The takeaway in one sentence. Agents and screen readers cannot read SVG. |
342
+ | `name` | `string` | `'custom'` | Rendered as data-chart, e.g. "sankey" or a gallery slug. |
343
+ | `role` | `'figure' \| 'img'` | `'figure'` | figure keeps legends, buttons and brushes inside operable; img for a static picture. |
344
+ | `children` * | `ReactNode` | | Unovis containers and components. |
345
+
346
+ ## Examples
347
+
348
+ ### Sankey
349
+
350
+ ```tsx
351
+ <ChartCard title="Energy flow" description="Quadrillion Btu">
352
+ <ChartSurface name="sankey" aria-label="Most energy is lost as heat before end use">
353
+ <VisSingleContainer data={{ nodes, links }} height={420}>
354
+ <VisSankey label={(n) => n.label} />
355
+ </VisSingleContainer>
356
+ </ChartSurface>
357
+ </ChartCard>
358
+ ```
359
+
360
+ ## Rules
361
+ - Wrap the chart in <ChartCard> and give the card a title.
362
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
363
+ - Use the default palette order; color 1 (blue) is the primary series.
364
+ - Max 5 series per chart. Do not use dual y-axes.
365
+ - When you adapt a chart gallery example, keep its interactions.
366
+ - Tooltip templates use the .sw-tt classes.
367
+
368
+ ## DOM contract (for agents operating the page)
369
+
370
+ - Selector: `[data-sw="chart"]`
371
+ - `data-chart`: the name prop
372
+ - `aria-label`: the summary
373
+ - How to operate: Read aria-label for the meaning; legends and controls inside are regular buttons.
374
+
375
+ ---
376
+
377
+ # LineChart
378
+
379
+ > Trends over time for 1–5 series. Built on Unovis VisLine.
380
+
381
+ Category: charts · Status: beta · Slug: `line-chart`
382
+
383
+ ```tsx
384
+ import { LineChart, ChartCard } from '@peerproblem/sw3-ui/charts'
385
+ ```
386
+
387
+ ## When to use
388
+ - A value changing over time.
389
+ - Comparing a few trends.
390
+
391
+ ## Avoid
392
+ - Categories with no order — use BarChart.
393
+ - More than 5 lines.
394
+
395
+ ## Props
396
+
397
+ | Prop | Type | Default | Description |
398
+ | --- | --- | --- | --- |
399
+ | `data` * | `D[]` | | Array of rows. |
400
+ | `x` * | `keyof D \| (d, i) => number \| Date \| string` | | X field. Numbers/Dates use a scale; strings become ordered categories. |
401
+ | `series` * | `Array<{ key: keyof D; label?: string; color?: string }>` | | One entry per plotted field. Colors default to --sw-chart-1..8 in order. |
402
+ | `height` | `number` | `240` | Pixels. Width fills the parent. |
403
+ | `xFormat / yFormat` | `(v) => string` | | Tick and tooltip formatting. y defaults to compact (12.4k). |
404
+ | `showXAxis / showYAxis / showGrid` | `boolean` | `true` | Axes and horizontal grid. |
405
+ | `tooltip` | `boolean` | `true` | Crosshair + tooltip on hover. |
406
+ | `yDomain` | `[min?, max?]` | | Fix the y range, e.g. [0, undefined]. |
407
+ | `aria-label` | `string` | | Text summary of the chart. Always set it — agents and screen readers cannot read SVG. |
408
+ | `curve` | `'smooth' \| 'linear' \| 'step'` | `'smooth'` | |
409
+ | `lineWidth` | `number` | `2` | |
410
+
411
+ ## Examples
412
+
413
+ ### Traffic
414
+
415
+ ```tsx
416
+ const data = [{ day: 'Mon', visits: 120, signups: 12 }, { day: 'Tue', visits: 180, signups: 20 } /* … */]
417
+
418
+ <ChartCard title="Traffic" description="Last 7 days" value="12.4k" legend={[{ key: 'visits', label: 'Visits' }, { key: 'signups', label: 'Sign-ups' }]}>
419
+ <LineChart aria-label="Visits rose all week" data={data} x="day" series={[{ key: 'visits', label: 'Visits' }, { key: 'signups', label: 'Sign-ups' }]} />
420
+ </ChartCard>
421
+ ```
422
+
423
+ ## Rules
424
+ - Wrap the chart in <ChartCard> and give the card a title.
425
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
426
+ - Use the default palette order; color 1 (blue) is the primary series.
427
+ - Max 5 series per chart. Do not use dual y-axes.
428
+
429
+ ## DOM contract (for agents operating the page)
430
+
431
+ - Selector: `[data-sw="chart"]`
432
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
433
+ - `aria-label`: the summary
434
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
435
+
436
+ Related: `area-chart`, `chart-card`
437
+
438
+ ---
439
+
440
+ # AreaChart
441
+
442
+ > Volume over time; overlapping translucent areas or stacked part-to-whole. Built on Unovis VisArea.
443
+
444
+ Category: charts · Status: beta · Slug: `area-chart`
445
+
446
+ ```tsx
447
+ import { AreaChart, ChartCard } from '@peerproblem/sw3-ui/charts'
448
+ ```
449
+
450
+ ## When to use
451
+ - Totals over time.
452
+ - Stacked composition over time (`stacked`).
453
+
454
+ ## Avoid
455
+ - Overlapping more than 3 unstacked areas.
456
+
457
+ ## Props
458
+
459
+ | Prop | Type | Default | Description |
460
+ | --- | --- | --- | --- |
461
+ | `data` * | `D[]` | | Array of rows. |
462
+ | `x` * | `keyof D \| (d, i) => number \| Date \| string` | | X field. Numbers/Dates use a scale; strings become ordered categories. |
463
+ | `series` * | `Array<{ key: keyof D; label?: string; color?: string }>` | | One entry per plotted field. Colors default to --sw-chart-1..8 in order. |
464
+ | `height` | `number` | `240` | Pixels. Width fills the parent. |
465
+ | `xFormat / yFormat` | `(v) => string` | | Tick and tooltip formatting. y defaults to compact (12.4k). |
466
+ | `showXAxis / showYAxis / showGrid` | `boolean` | `true` | Axes and horizontal grid. |
467
+ | `tooltip` | `boolean` | `true` | Crosshair + tooltip on hover. |
468
+ | `yDomain` | `[min?, max?]` | | Fix the y range, e.g. [0, undefined]. |
469
+ | `aria-label` | `string` | | Text summary of the chart. Always set it — agents and screen readers cannot read SVG. |
470
+ | `stacked` | `boolean` | `false` | Stack series. |
471
+ | `line` | `boolean` | `true` | Stroke on top (unstacked only). |
472
+ | `curve` | `'smooth' \| 'linear' \| 'step'` | `'smooth'` | |
473
+
474
+ ## Examples
475
+
476
+ ### Stacked
477
+
478
+ ```tsx
479
+ <ChartCard title="Usage by plan">
480
+ <AreaChart aria-label="Usage by plan" stacked data={data} x="month" series={[{ key: 'free' }, { key: 'pro' }, { key: 'team' }]} />
481
+ </ChartCard>
482
+ ```
483
+
484
+ ## Rules
485
+ - Wrap the chart in <ChartCard> and give the card a title.
486
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
487
+ - Use the default palette order; color 1 (blue) is the primary series.
488
+ - Max 5 series per chart. Do not use dual y-axes.
489
+
490
+ ## DOM contract (for agents operating the page)
491
+
492
+ - Selector: `[data-sw="chart"]`
493
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
494
+ - `aria-label`: the summary
495
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
496
+
497
+ ---
498
+
499
+ # BarChart
500
+
501
+ > Compare categories, grouped or stacked, vertical or horizontal. Built on Unovis VisGroupedBar / VisStackedBar.
502
+
503
+ Category: charts · Status: beta · Slug: `bar-chart`
504
+
505
+ ```tsx
506
+ import { BarChart, ChartCard } from '@peerproblem/sw3-ui/charts'
507
+ ```
508
+
509
+ ## When to use
510
+ - Comparing discrete categories.
511
+ - Composition per category (`mode="stacked"`).
512
+
513
+ ## Avoid
514
+ - Time series with many points — use LineChart.
515
+
516
+ ## Props
517
+
518
+ | Prop | Type | Default | Description |
519
+ | --- | --- | --- | --- |
520
+ | `data` * | `D[]` | | Array of rows. |
521
+ | `x` * | `keyof D \| (d, i) => number \| Date \| string` | | X field. Numbers/Dates use a scale; strings become ordered categories. |
522
+ | `series` * | `Array<{ key: keyof D; label?: string; color?: string }>` | | One entry per plotted field. Colors default to --sw-chart-1..8 in order. |
523
+ | `height` | `number` | `240` | Pixels. Width fills the parent. |
524
+ | `xFormat / yFormat` | `(v) => string` | | Tick and tooltip formatting. y defaults to compact (12.4k). |
525
+ | `showXAxis / showYAxis / showGrid` | `boolean` | `true` | Axes and horizontal grid. |
526
+ | `tooltip` | `boolean` | `true` | Crosshair + tooltip on hover. |
527
+ | `yDomain` | `[min?, max?]` | | Fix the y range, e.g. [0, undefined]. |
528
+ | `aria-label` | `string` | | Text summary of the chart. Always set it — agents and screen readers cannot read SVG. |
529
+ | `mode` | `'grouped' \| 'stacked'` | `'grouped'` | |
530
+ | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | |
531
+ | `barRadius` | `number` | `4` | Bar corner radius in px. |
532
+
533
+ ## Examples
534
+
535
+ ### Grouped
536
+
537
+ ```tsx
538
+ <ChartCard title="Regional performance">
539
+ <BarChart aria-label="Q3 beat Q2 in every region" data={regions} x="region" series={[{ key: 'q2', label: 'Q2' }, { key: 'q3', label: 'Q3' }]} />
540
+ </ChartCard>
541
+ ```
542
+
543
+ ## Rules
544
+ - Wrap the chart in <ChartCard> and give the card a title.
545
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
546
+ - Use the default palette order; color 1 (blue) is the primary series.
547
+ - Max 5 series per chart. Do not use dual y-axes.
548
+
549
+ ## DOM contract (for agents operating the page)
550
+
551
+ - Selector: `[data-sw="chart"]`
552
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
553
+ - `aria-label`: the summary
554
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
555
+
556
+ ---
557
+
558
+ # ScatterChart
559
+
560
+ > Correlation between two numeric fields, optional size field. Built on Unovis VisScatter.
561
+
562
+ Category: charts · Status: beta · Slug: `scatter-chart`
563
+
564
+ ```tsx
565
+ import { ScatterChart, ChartCard } from '@peerproblem/sw3-ui/charts'
566
+ ```
567
+
568
+ ## When to use
569
+ - Relationship between two measures.
570
+
571
+ ## Avoid
572
+ - Fewer than ~10 points — use a table.
573
+
574
+ ## Props
575
+
576
+ | Prop | Type | Default | Description |
577
+ | --- | --- | --- | --- |
578
+ | `data` * | `D[]` | | |
579
+ | `x` * | `keyof D` | | Numeric x field. |
580
+ | `y` * | `keyof D` | | Numeric y field. |
581
+ | `size` | `keyof D` | | Numeric field for point size. |
582
+ | `color` | `string` | | Point color. Default --sw-chart-1. |
583
+ | `height` | `number` | `240` | |
584
+
585
+ ## Examples
586
+
587
+ ### Latency vs cost
588
+
589
+ ```tsx
590
+ <ChartCard title="Latency vs cost">
591
+ <ScatterChart aria-label="Faster models cost more" data={models} x="latency" y="cost" size="calls" />
592
+ </ChartCard>
593
+ ```
594
+
595
+ ## Rules
596
+ - Wrap the chart in <ChartCard> and give the card a title.
597
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
598
+ - Use the default palette order; color 1 (blue) is the primary series.
599
+ - Max 5 series per chart. Do not use dual y-axes.
600
+
601
+ ## DOM contract (for agents operating the page)
602
+
603
+ - Selector: `[data-sw="chart"]`
604
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
605
+ - `aria-label`: the summary
606
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
607
+
608
+ ---
609
+
610
+ # DonutChart
611
+
612
+ > Part-to-whole for 2–6 slices with a central label. Built on Unovis VisDonut.
613
+
614
+ Category: charts · Status: beta · Slug: `donut-chart`
615
+
616
+ ```tsx
617
+ import { DonutChart, ChartCard } from '@peerproblem/sw3-ui/charts'
618
+ ```
619
+
620
+ ## When to use
621
+ - Share of a total with few slices.
622
+
623
+ ## Avoid
624
+ - More than 6 slices or slices that are close in size — use BarChart.
625
+
626
+ ## Props
627
+
628
+ | Prop | Type | Default | Description |
629
+ | --- | --- | --- | --- |
630
+ | `data` * | `Array<{ label: string; value: number; color?: string }>` | | |
631
+ | `centralLabel` | `string` | | Short value at the center, typically the total. |
632
+ | `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. |
633
+ | `arcWidth` | `number` | `18` | Ring thickness px. |
634
+ | `height` | `number` | `200` | |
635
+
636
+ ## Examples
637
+
638
+ ### Traffic sources
639
+
640
+ ```tsx
641
+ const sources = [{ label: 'Search', value: 52 }, { label: 'Direct', value: 28 }, { label: 'Social', value: 20 }]
642
+
643
+ <ChartCard title="Traffic sources" legend={sources.map((s) => ({ key: s.label }))}>
644
+ <DonutChart aria-label="12,400 visits. Search accounts for 52%." data={sources} centralLabel="12.4k" centralSubLabel="Visits" />
645
+ </ChartCard>
646
+ ```
647
+
648
+ ## Rules
649
+ - Wrap the chart in <ChartCard> and give the card a title.
650
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
651
+ - Use the default palette order; color 1 (blue) is the primary series.
652
+ - Max 5 series per chart. Do not use dual y-axes.
653
+
654
+ ## DOM contract (for agents operating the page)
655
+
656
+ - Selector: `[data-sw="chart"]`
657
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
658
+ - `aria-label`: the summary
659
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
660
+
661
+ ---
662
+
663
+ # Sparkline
664
+
665
+ > A tiny axis-less trend line for Stats and table cells.
666
+
667
+ Category: charts · Status: beta · Slug: `sparkline`
668
+
669
+ ```tsx
670
+ import { Sparkline } from '@peerproblem/sw3-ui/charts'
671
+ ```
672
+
673
+ ## When to use
674
+ - Inside <Stat> or a table cell to show direction.
675
+
676
+ ## Avoid
677
+ - As the main chart — it has no axes.
678
+
679
+ ## Props
680
+
681
+ | Prop | Type | Default | Description |
682
+ | --- | --- | --- | --- |
683
+ | `data` * | `number[]` | | |
684
+ | `color` | `string` | | Default --sw-chart-1. |
685
+ | `height` | `number` | `36` | |
686
+ | `area` | `boolean` | `true` | Soft fill under the line. |
687
+
688
+ ## Examples
689
+
690
+ ### In a Stat
691
+
692
+ ```tsx
693
+ <Stat label="Visitors" value="12.4k" delta="+8%"><Sparkline data={[4, 8, 6, 9, 12]} /></Stat>
694
+ ```
695
+
696
+ ## DOM contract (for agents operating the page)
697
+
698
+ - Selector: `[data-sw="chart"]`
699
+ - `data-chart`: line | area | bar | scatter | donut | sparkline | treemap | <ChartSurface name>
700
+ - `aria-label`: the summary
701
+ - How to operate: Read aria-label for the meaning; charts are not interactive controls.
702
+
703
+ ---
704
+
705
+ # Treemap
706
+
707
+ > Part-to-whole for many items, optionally grouped one level deep. Squircle tiles with concentric inner corners and HTML labels that fit the tile.
708
+
709
+ Category: charts · Status: beta · Slug: `treemap`
710
+
711
+ ```tsx
712
+ import { Treemap, ChartCard } from '@peerproblem/sw3-ui/charts'
713
+ ```
714
+
715
+ ## When to use
716
+ - Comparing the size of many items (10–200) against a total.
717
+ - Showing which group holds most of a total, and what is inside each group.
718
+
719
+ ## Avoid
720
+ - Fewer than 6 items — use DonutChart or BarChart.
721
+ - Values that can be negative.
722
+ - Change over time — use LineChart or AreaChart.
723
+ - More than one level of nesting.
724
+
725
+ ## Props
726
+
727
+ | Prop | Type | Default | Description |
728
+ | --- | --- | --- | --- |
729
+ | `data` * | `D[]` | | One row per leaf tile. |
730
+ | `value` * | `keyof D \| (d) => number` | | Tile size. Negative values count as 0. |
731
+ | `label` * | `keyof D \| (d) => string` | | Tile name. |
732
+ | `groupBy` | `keyof D \| (d) => string` | | Nests tiles into labelled, colored groups. Leave out for a flat treemap. |
733
+ | `groups` | `Array<{ key: string; label?: string; color?: string }>` | | Group order, labels and colors. Pass the same array to <ChartCard legend> so the legend matches. |
734
+ | `height` | `number` | `320` | Pixels. Width fills the parent. |
735
+ | `valueFormat` | `(v: number) => string` | `compact` | Formats tile, group and tooltip values. |
736
+ | `radius` | `RadiusToken \| number` | `'sm'` | Group corner radius. Tiles inside a group get radius − gap so the corners nest. |
737
+ | `gap` | `number` | `4` | Space between tiles and the group inset, px. |
738
+ | `tooltip` | `boolean` | `true` | Tooltip with value and share of total on hover and focus. |
739
+ | `onTileClick` | `(datum: D) => void` | | Makes leaf tiles buttons (keyboard operable). |
740
+ | `aria-label` | `string` | | The takeaway in one sentence. Always set it. |
741
+
742
+ ## Examples
743
+
744
+ ### Grouped
745
+
746
+ ```tsx
747
+ const groups = [{ key: 'losing', label: 'Losing' }, { key: 'fighting', label: 'Fighting' }, { key: 'earning', label: 'Earning' }]
748
+
749
+ <ChartCard title="Putting billions in perspective" description="USD billions" legend={groups}>
750
+ <Treemap
751
+ aria-label="The financial crisis and COVID cost more than everything else combined"
752
+ data={rows}
753
+ value="billions"
754
+ label="name"
755
+ groupBy="category"
756
+ groups={groups}
757
+ valueFormat={(v) => `$${v.toLocaleString('en-US')}B`}
758
+ />
759
+ </ChartCard>
760
+ ```
761
+
762
+ ## Rules
763
+ - Wrap the chart in <ChartCard> and give the card a title.
764
+ - Always pass aria-label with the takeaway, e.g. "Visitors up 8% this week".
765
+ - Use the default palette order; color 1 (blue) is the primary series.
766
+ - Max 5 series per chart. Do not use dual y-axes.
767
+ - Sort is automatic (largest top-left). Do not pre-sort or colour tiles by hand.
768
+ - Keep group labels short; tiles too small for a label still show it in the tooltip.
769
+
770
+ ## DOM contract (for agents operating the page)
771
+
772
+ - Selector: `[data-sw="chart"][data-chart="treemap"]`
773
+ - `data-total`: sum of all values
774
+ - `aria-label`: the summary
775
+ - `data-tile / data-group / data-value`: on each leaf (.sw-treemap__leaf)
776
+ - How to operate: Read aria-label for the meaning and data-tile / data-value on leaves for the numbers. With onTileClick, leaves are buttons named "<name>, <value>, <group>".
777
+
778
+ ---