@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.
- package/LICENSE +21 -0
- package/README.md +109 -2
- package/agent/components/accordion.md +95 -0
- package/agent/components/action-square.md +106 -0
- package/agent/components/agent-bridge.md +87 -0
- package/agent/components/agent-console.md +123 -0
- package/agent/components/alert-dialog.md +82 -0
- package/agent/components/app-shell.md +105 -0
- package/agent/components/area-chart.md +56 -0
- package/agent/components/async-options.md +47 -0
- package/agent/components/autocomplete.md +69 -0
- package/agent/components/avatar.md +88 -0
- package/agent/components/badge.md +51 -0
- package/agent/components/bar-chart.md +56 -0
- package/agent/components/bar-list.md +49 -0
- package/agent/components/breadcrumbs.md +43 -0
- package/agent/components/button.md +109 -0
- package/agent/components/calendar.md +114 -0
- package/agent/components/canvas.md +105 -0
- package/agent/components/card.md +78 -0
- package/agent/components/carousel.md +113 -0
- package/agent/components/chart-card.md +41 -0
- package/agent/components/chart-surface.md +56 -0
- package/agent/components/checkbox.md +88 -0
- package/agent/components/citation-chip.md +61 -0
- package/agent/components/collapsible.md +69 -0
- package/agent/components/color-picker.md +82 -0
- package/agent/components/combobox.md +104 -0
- package/agent/components/command.md +92 -0
- package/agent/components/dashboard-grid.md +73 -0
- package/agent/components/date-input.md +87 -0
- package/agent/components/date-picker.md +122 -0
- package/agent/components/dialog.md +97 -0
- package/agent/components/donut-chart.md +50 -0
- package/agent/components/drawer.md +101 -0
- package/agent/components/empty-state.md +52 -0
- package/agent/components/field.md +80 -0
- package/agent/components/file-input.md +84 -0
- package/agent/components/hover-card.md +64 -0
- package/agent/components/image-cropper.md +77 -0
- package/agent/components/input.md +49 -0
- package/agent/components/label.md +53 -0
- package/agent/components/line-chart.md +60 -0
- package/agent/components/listbox.md +84 -0
- package/agent/components/map-view.md +104 -0
- package/agent/components/menu.md +117 -0
- package/agent/components/menubar.md +67 -0
- package/agent/components/meter.md +59 -0
- package/agent/components/navigation-menu.md +98 -0
- package/agent/components/number-input.md +81 -0
- package/agent/components/otp-input.md +67 -0
- package/agent/components/pagination.md +80 -0
- package/agent/components/password-input.md +67 -0
- package/agent/components/pill-button.md +116 -0
- package/agent/components/popover.md +85 -0
- package/agent/components/poster-card.md +61 -0
- package/agent/components/preferences.md +92 -0
- package/agent/components/progress.md +63 -0
- package/agent/components/provider.md +47 -0
- package/agent/components/radio.md +91 -0
- package/agent/components/rating.md +66 -0
- package/agent/components/reorder.md +61 -0
- package/agent/components/resizable.md +87 -0
- package/agent/components/scatter-chart.md +49 -0
- package/agent/components/scroll-area.md +81 -0
- package/agent/components/segmented-control.md +56 -0
- package/agent/components/select.md +130 -0
- package/agent/components/separator.md +60 -0
- package/agent/components/shortcuts.md +50 -0
- package/agent/components/sidebar-nav.md +68 -0
- package/agent/components/skeleton.md +58 -0
- package/agent/components/slider.md +79 -0
- package/agent/components/sparkline.md +39 -0
- package/agent/components/squircle.md +58 -0
- package/agent/components/stat.md +58 -0
- package/agent/components/switch.md +48 -0
- package/agent/components/table.md +58 -0
- package/agent/components/tabs.md +108 -0
- package/agent/components/textarea.md +68 -0
- package/agent/components/time-input.md +84 -0
- package/agent/components/timeline.md +91 -0
- package/agent/components/toast.md +85 -0
- package/agent/components/toggle.md +76 -0
- package/agent/components/token-input.md +66 -0
- package/agent/components/toolbar.md +76 -0
- package/agent/components/tooltip.md +83 -0
- package/agent/components/tracker.md +47 -0
- package/agent/components/tree.md +87 -0
- package/agent/components/treemap.md +72 -0
- package/agent/components/trend-chart.md +80 -0
- package/agent/components/trigger-menu.md +67 -0
- package/agent/components/typography.md +51 -0
- package/agent/components/waterfall.md +78 -0
- package/agent/components/week-schedule.md +113 -0
- package/agent/llms/actions-and-layout.txt +1749 -0
- package/agent/llms/agents.txt +505 -0
- package/agent/llms/charts.txt +778 -0
- package/agent/llms/dashboards.txt +457 -0
- package/agent/llms/extend.txt +132 -0
- package/agent/llms/extras.txt +527 -0
- package/agent/llms/forms.txt +2152 -0
- package/agent/llms/foundations.txt +674 -0
- package/agent/llms/hooks.txt +178 -0
- package/agent/llms/maps.txt +229 -0
- package/agent/llms/overlays-and-navigation.txt +1167 -0
- package/agent/llms-full.txt +8717 -0
- package/agent/llms.txt +145 -0
- package/agent/registry.json +11289 -0
- package/agent/tokens.md +66 -0
- package/dist/agent/index.d.ts +235 -0
- package/dist/agent/index.js +21 -0
- package/dist/card-Ipm-Cj5f.d.ts +490 -0
- package/dist/charts/index.d.ts +289 -0
- package/dist/charts/index.js +815 -0
- package/dist/check/cli.d.ts +1 -0
- package/dist/check/cli.js +48 -0
- package/dist/check/rendered.d.ts +11 -0
- package/dist/check/rendered.js +77 -0
- package/dist/check/source.d.ts +13 -0
- package/dist/check/source.js +182 -0
- package/dist/chunk-3DXBM65D.js +65 -0
- package/dist/chunk-3H5X4ZP6.js +55 -0
- package/dist/chunk-6XC4BC5C.js +92 -0
- package/dist/chunk-7H6TEAWD.js +507 -0
- package/dist/chunk-I63ZTJOI.js +1089 -0
- package/dist/chunk-JCIRUM4W.js +33 -0
- package/dist/chunk-LTBEHZ3P.js +25 -0
- package/dist/chunk-QDPPLO4U.js +60 -0
- package/dist/chunk-U2XFBPU4.js +56 -0
- package/dist/chunk-UY2WH5AY.js +681 -0
- package/dist/extras.d.ts +203 -0
- package/dist/extras.js +904 -0
- package/dist/icons-BJiGEAnU.d.ts +68 -0
- package/dist/index.d.ts +3737 -0
- package/dist/index.js +14477 -0
- package/dist/map/index.d.ts +115 -0
- package/dist/map/index.js +394 -0
- package/dist/meta/index.d.ts +3314 -0
- package/dist/meta/index.js +5106 -0
- package/dist/rules-1RIZ_JZr.d.ts +38 -0
- package/dist/styles.css +4037 -0
- package/dist/themes/calm.css +42 -0
- package/dist/themes/frost.css +40 -0
- 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
|
+
---
|