@acronis-platform/ui-react 2.0.0 → 4.0.0

package/dist/llms/category-bar.md

@@ -0,0 +1,193 @@
+# CategoryBar
+
+> A single horizontal bar split into proportional colored segments — one part-to-whole across a handful of categories in one row (onboarding stages, certification status, a pass/fail split). Each segment's width is its value over the sum of all values; segment colors are caller-supplied via `config`. A plain flex composition (not a recharts chart) with one CVA axis (`size`), an optional count/% legend, and per-segment hover tooltips. Design-pending v1 — no chart token tier exists yet.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.60.0
+
+## Import
+
+```tsx
+import { CategoryBar } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<CategoryBar
+  config={config}
+  data={[
+    { key: 'passed', value: 68 },
+    { key: 'warnings', value: 22 },
+    { key: 'failed', value: 10 },
+  ]}
+  showLegend
+/>
+```
+
+A single horizontal bar split into proportional colored segments — a
+part-to-whole across a handful of categories, in one row. Give it a `data` array
+(`key` + `value`) and a per-segment `config`; each segment's width is its value
+over the total.
+
+Segment colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`.
+
+> **Design-pending v1.** A plain flex composition (no recharts, no demo
+> playground). Chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- A single-level part-to-whole where the **relative size** of each category
+  matters and you want it in one compact row (onboarding stages, certification
+  status, a pass/warn/fail split).
+- As a header/summary widget above a table or in a dashboard card.
+
+## When not to use
+
+- Ranked single values that each need their own labelled row — use `Meter`
+  stacked into a bar list.
+- Precise value comparison across many categories — a bar chart reads better.
+- A flow across two or more levels — use `SankeyChart`.
+- More than ~6 segments, or very uneven values — thin slivers become unreadable;
+  lean on the legend or a different chart.
+
+## Variants
+
+One CVA axis: `size` (`sm` / `md` / `lg`) sets the track height. Everything else
+is plain props: `showLegend`, `showTooltip`, `valueFormatter`, `defaultOpenIndex`.
+
+## Example
+
+```tsx
+import { CategoryBar } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const config = {
+  passed: {
+    label: 'Passed',
+    color: 'var(--ui-background-status-strong-success)',
+  },
+  warnings: {
+    label: 'Warnings',
+    color: 'var(--ui-background-status-strong-warning)',
+  },
+  failed: {
+    label: 'Failed',
+    color: 'var(--ui-background-status-strong-danger)',
+  },
+} satisfies ChartConfig;
+
+<CategoryBar
+  config={config}
+  data={[
+    { key: 'passed', value: 68 },
+    { key: 'warnings', value: 22 },
+    { key: 'failed', value: 10 },
+  ]}
+  showLegend
+/>;
+```
+
+`showLegend` renders a color dot + label per segment plus each segment's value
+and share of the total. Segment `key`s must be unique and CSS-safe;
+`config[key].label` carries the human-readable text.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `data` | `ReadonlyArray<{ key: string; value: number }>` | — | yes | Ordered segments (left → right). Each `key` indexes `config` for the segment's label and color; each segment's width is its `value` over the sum of all values. |
+| `config` | `ChartConfig` | — | yes | Segments take their colour from the container's `palette`; each entry, keyed by the segment's `key`, maps that segment to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the segments fill from. |
+| `size` | `'sm' | 'md' | 'lg'` | `'md'` | no | Track height. |
+| `showLegend` | `boolean` | `false` | no | Render a legend below the bar — a color dot + label per segment, its value, and its share of the total as a percentage. |
+| `showTooltip` | `boolean` | `true` | no | Wrap each segment in a hover tooltip (dot + label + value + %). |
+| `tooltipContent` | `(segment: { key; value; label; percent; color }) => ReactNode` | — | no | Custom tooltip content per segment — replaces the default (dot + label + `value · %`) inside the same card. Ignored when showTooltip is false. `label` is the resolved config label (any node, not just a string) and `color` is the segment's `var(--color-<key>)` reference, so it follows whichever palette colour the container resolved for that segment. |
+| `valueFormatter` | `(value: number) => string` | `toLocaleString()` | no | Format the numeric value shown in the legend and tooltip. |
+| `defaultOpenIndex` | `number` | — | no | Render the tooltip for this segment index initially open (for visual regression / testing; the tooltip is otherwise hover-only). |
+| `aria-label` | `string` | — | no | Accessible summary of the whole bar. Defaults to a locale-neutral `label value` list built from the data; pass a fuller sentence if you have one. |
+
+## Behavior
+
+`CategoryBar` renders a single bar split into proportional colored segments from
+a `data` array and a per-segment `config`. It is a plain flex composition, not a
+recharts chart.
+
+```gherkin
+Scenario: Render segments proportional to value
+  Given data with segments (each a key + value) and a config mapping each key to a label and color
+  Then one segment renders per datum, its width its value over the sum of all values
+  And each segment is filled from its config color
+```
+
+```gherkin
+Scenario: Size variant
+  Given size is sm, md (default), or lg
+  Then the track renders at the corresponding height
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a legend renders below the bar with a color dot + label per segment
+  And each segment's value plus its share of the total as a percentage
+  And when showLegend is false no legend renders
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a segment
+  Then a card shows a color dot, the segment's label, and its value + percentage
+  And defaultOpenIndex renders that segment's tooltip initially open
+  And tooltipContent replaces the default card body with a per-segment render
+```
+
+```gherkin
+Scenario: Value formatting
+  Given a valueFormatter
+  Then the legend and tooltip show the formatted value
+```
+
+```gherkin
+Scenario: Accessible summary
+  Given no aria-label
+  Then the bar exposes a role="img" with a generated "<label> <value>" summary
+  Given an aria-label
+  Then that string is used instead
+```
+
+```gherkin
+Scenario: All-zero data
+  Given every segment value is 0
+  Then no segment takes width, each share reads 0%, and nothing divides by zero
+```
+
+## Accessibility
+
+`CategoryBar` is a data visualization: a single bar of proportional segments.
+
+## Text alternative
+
+- The track carries `role="img"` with an `aria-label`. By default the label is a
+  locale-neutral `"<label> <value>"` list built from the data (e.g. `"Registered
+42, Trained 32, Certified 26"`); pass a fuller `aria-label` sentence when you
+  have one. This is the screen-reader equivalent of the bar.
+- **Do not rely on color alone.** The legend (`showLegend`) and the per-segment
+  tooltip both carry the text label, so the meaning survives without color
+  perception.
+
+## Tooltip
+
+- The per-segment tooltip is a **hover/pointer** affordance layered on the
+  `role="img"` bar; the `aria-label` already conveys the same information to
+  assistive tech, so the tooltip is supplementary rather than the sole source.
+- Because the segments sit inside a `role="img"`, their tooltip triggers are not
+  exposed as separate focusable controls — keeping a single, coherent image
+  semantic instead of a row of unlabeled controls.
+
+## Contrast
+
+- Segment fills are caller-supplied tokens; pick colors that stay distinguishable
+  from each other and from the track background in both light and dark themes.
+  Adjacent segments should not read as one block — the legend disambiguates when
+  hues are close.

package/dist/llms/chart-state.md

@@ -0,0 +1,190 @@
+# ChartState
+
+> A shared loading / empty / error placeholder for the chart types, rendered in place of the chart inside the same sized slot. A compact status block — a leading glyph over a centered label, with an optional retry action for the error state. The `empty` state draws the silhouette the design defines for each chart type (`variant`), plus an optional "Widget description" line; `loading` and `error` share one treatment. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a widget that isn't a chart — see behavior.md.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { ChartState } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ChartState state="loading" />
+<ChartState state="empty" variant="bar" description="No results for the selected range" />
+<ChartState
+  state="error"
+  action={<Button variant="ghost" onClick={refetch}>Try again</Button>}
+/>
+```
+
+A shared loading / empty / error placeholder for the chart types. Render it in
+place of a chart — inside the same sized slot — while data is loading, when
+there is nothing to plot, or when the fetch failed.
+
+> **Design-pending v1.** Ported from the Figma InputSelect dropdown states (the
+> reference node for this task) and kept visually in step with the shipped
+> `InputSelectStatus`. There is no `--ui-chart-*` token tier yet, so it themes
+> from existing semantic tokens directly.
+
+## When to use
+
+- A chart cannot render yet (data in flight), has no data to plot, or failed to
+  load — swap the chart for the matching `ChartState`.
+- You want the same placeholder across every chart type, rather than each chart
+  hand-rolling its own.
+
+## When not to use
+
+- A full-page empty state (illustration, title, description, primary action) —
+  use the larger `Empty` component instead.
+- A bare loading indicator with no surrounding message — use `Spinner` directly.
+
+## Example
+
+```tsx
+import { ChartState, ChartContainer, Button } from '@acronis-platform/ui-react';
+
+function Sales({ status, data, config, refetch }) {
+  if (status === 'loading') return <ChartState state="loading" />;
+  if (status === 'error')
+    return (
+      <ChartState
+        state="error"
+        action={
+          <Button variant="ghost" onClick={refetch}>
+            Try again
+          </Button>
+        }
+      />
+    );
+  if (!data.length) return <ChartState state="empty" />;
+
+  return (
+    <ChartContainer config={config} className="h-[300px] w-[500px]">
+      {/* …the chart… */}
+    </ChartContainer>
+  );
+}
+```
+
+The three states share one compact layout: a leading glyph (spinner / inbox /
+warning) over a centered label. Pass `message` to override a state's default
+label, and `action` to add a retry affordance to the error state.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `state` | `'loading' | 'empty' | 'error'` | — | yes | Which placeholder to show. Drives the leading artwork and the default label (loading → spinner + "Data is loading…"; empty → variant silhouette or no artwork + "No data found"; error → warning glyph + "Something went wrong"). |
+| `variant` | `'area' | 'bar' | 'line' | 'donut' | 'radial' | 'funnel' | 'radar' | 'sankey' | 'scatter' | 'treemap' | 'table' | 'text'` | — | no | Which chart the slot holds. The `empty` state then draws that type's silhouette instead of the generic inbox glyph — the design defines one per chart type. `donut` and `radial` share a ring. Ignored by `loading` and `error`, which share one treatment. |
+| `description` | `ReactNode` | — | no | Text shown below the illustration or glyph. Defaults to `"Data is loading…"` / `"No data found"` / `"Something went wrong"` based on `state`. Pass a value to override for any state. |
+| `action` | `ReactNode` | — | no | Trailing action rendered for the `error` state only (e.g. a "Try again" button). |
+
+## Behavior
+
+### Rendering per state
+
+- **Given** `state="loading"`, **when** rendered, **then** it shows the shared
+  `Spinner` (lg) above the label "Data is loading…" and announces the label via
+  its `role="status"` live region (no `aria-busy`, which could defer that
+  announcement).
+- **Given** `state="empty"`, **when** rendered, **then** it shows the label
+  "No data found" (no artwork unless a `variant` is passed).
+- **Given** `state="error"`, **when** rendered, **then** it shows the warning
+  glyph above the label "Something went wrong" and announces as an alert.
+
+### Label override
+
+- **Given** a `description` prop, **when** rendered in any state, **then** the
+  supplied text replaces that state's default label.
+
+### Action
+
+- **Given** an `action` node, **when** `state="error"`, **then** the action is
+  rendered after the label (e.g. a "Try again" button).
+- **Given** an `action` node, **when** `state` is `loading` or `empty`, **then**
+  the action is **not** rendered.
+
+### Layout
+
+- **Given** any state, **when** placed in a sized slot (the same box a chart
+  would occupy), **then** the block fills it (`size-full`) and centers its
+  content, with a `min-h-32` floor so it stays legible in an unsized parent.
+
+### Per-type empty states
+
+`empty` is the one state the design draws per chart type: an area silhouette for
+an area chart, a ring for a donut, a funnel for a funnel. An empty widget then
+still says what it _would_ have shown, which a single generic glyph can't.
+
+`variant` selects it. `donut` and `radial` share one ring — a radial-bar widget
+with no data has nothing to tell it apart. Without a `variant` the empty state
+shows no artwork — just the text.
+
+The geometry is exported from the Figma instances rather than redrawn, and every
+path is `currentColor`: the tone is set once on the container, so brand and theme
+overrides reach the artwork. Two of the eleven silhouettes use a second, fainter
+tone (the table and metric-list ones tint their header row darker than the body
+rows); that hierarchy is kept as `fill-opacity` on the same colour rather than a
+second token.
+
+The caption is **one line, in one style**. Figma styles it `body/default` on
+`text/onSurface/primary` — 14/24, centred, _not_ muted — which is what the root
+already applies, so the description and the fallback status label read
+identically. For a per-type empty state that line is the `description`: the mockups draw the silhouette over "Widget description" with no
+status label, because the artwork already says "no data" and the sentence worth
+the space is what the widget _would_ show. With no `description` it falls back to
+the status label, so a caller that only sets `variant` still reads sensibly.
+
+`loading` and `error` deliberately keep one shared treatment — the design only
+redesigned `empty`.
+
+### Not `WidgetPlaceholder`
+
+Two components, two jobs, and they are not interchangeable:
+
+- **`ChartState`** is the placeholder _inside_ a chart's slot. It fills whatever
+  gives the slot its height, renders one of three states, and is what a chart
+  widget swaps in for its plot.
+- **`WidgetPlaceholder`** is a composable skeleton with its own header, footer
+  and action parts, plus an `interactive` affordance — for a dashboard widget
+  that isn't a chart, or a whole tile that is still being set up.
+
+`WidgetPlaceholder` predates the per-type empty states and is used by consuming
+MFEs, so it stays.
+
+## Accessibility
+
+- The root is a **live region** so a screen reader announces the state change
+  when a chart swaps its content in:
+  - `loading` / `empty` → `role="status"` with `aria-live="polite"`.
+  - `error` → `role="alert"` with `aria-live="assertive"`.
+- On `loading` the shared `Spinner` is rendered `aria-hidden` so the root's own
+  live region (with the label) announces once, rather than the Spinner's
+  `role="status"` + sr-only "Loading…" nesting inside it and double-announcing.
+- The root does **not** carry `aria-busy`. It is itself the live region, and some
+  screen readers defer announcing a busy region's content until `aria-busy`
+  clears; because this placeholder is unmounted (swapped for the chart) rather
+  than un-busied, a busy flag would risk swallowing the "Data is loading…"
+  announcement. Put `aria-busy` on the chart-slot **container** instead if a busy
+  signal is needed (same guidance as `Skeleton`).
+- The live-region attributes (`role` / `aria-live`) are applied after the prop
+  spread, so the state's a11y contract is not clobbered by a consumer-passed
+  attribute.
+- The label text is a real `<p>`, so the state message is always in the
+  accessible tree — the glyph is decorative and does not need its own label.
+- **Do not rely on the glyph color alone** to convey the state — the label
+  carries the meaning. Icon colors (`--ui-glyph-on-status-info` /
+  `--ui-glyph-on-status-warning`) and the label (`--ui-text-on-surface-primary`)
+  resolve to semantic tokens that meet contrast in both themes.
+- If the error state offers a retry, pass an actual interactive control as
+  `action` (a `Button`) so it is focusable and keyboard-operable.
+
+## Contrast
+
+Label and glyph colors resolve to semantic `--ui-*` tokens that meet contrast on
+the surface in both light and dark themes.

package/dist/llms/chart-widget.md

@@ -0,0 +1,209 @@
+# ChartWidget
+
+> The dashboard card a chart sits in: a `Card` with the standard widget header (title, optional filter chip and the ⋯ actions menu) and an optional metric readout above the plot. Adds the one thing a `Card` doesn't know about — the body's loading / empty / error placeholder — and re-implements nothing else: its `header` is `CardHeaderProps`, spread. It declares no size: the grid sizes the card and the widget passes that height down, so a `size-full` chart fills whatever the header leaves. The per-type chart components stay card-less, so a chart is still usable outside a widget.
+
+**Status:** draft · **Category:** data-display · **Since:** v2.1.0
+
+## Import
+
+```tsx
+import { ChartWidget } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ChartWidget
+  header={{
+    title: 'Active alerts by severity',
+    extras: <Tag variant="info">Last 6 months</Tag>,
+    actions: <ButtonIcon aria-label="Widget actions"><EllipsisIcon size={16} /></ButtonIcon>,
+  }}
+  className="h-[300px] w-[592px]"
+>
+  <AreaChart config={config} data={data} dataKeys={['sessions']} xKey="month" className="size-full" />
+</ChartWidget>
+
+<ChartWidget header={{ title: 'Severity' }} state="empty" bodyClassName="h-[252px]" />
+```
+
+The dashboard card a chart sits in.
+
+Every chart in the Figma library is drawn inside the same card: a header with a
+title, an optional filter chip and the ⋯ actions menu, then an optional metric
+readout, then the plot. `ChartWidget` is that composition — and only that.
+
+## What it adds
+
+One thing a `Card` legitimately doesn't know about: **what the body shows while
+there is no plot.** `state="loading" | "empty" | "error"` renders `ChartState` in
+place of the chart, and `error` also gives the Card its error border — one prop,
+not two.
+
+## What it doesn't add
+
+A header. `header` is typed `CardHeaderProps` and spread onto `CardHeader`, so
+the whole header surface — including the parts this component never mentions
+(`isDraggable`, `hasRename`, `isCollapsible`, …) — comes from `Card` and stays
+in sync with it.
+
+Nor a chart. The per-type chart components stay card-less, which keeps them
+usable outside a widget.
+
+## Why it takes no `size`
+
+The Figma sets carry `size` = `sm` / `md` / `lg`, but it only changes the frame
+width (288 / 592 / 896). The height is the dashboard grid's, and the widget
+passes it down: the header takes what it needs, and a `size-full` chart fills
+the rest of the card. See `behavior.md`.
+
+## Files
+
+| File               | What's in it                                                       |
+| ------------------ | ------------------------------------------------------------------ |
+| `index.yaml`       | Identity, category, status, `since`.                               |
+| `api.yaml`         | The prop contract and the per-framework adapters.                  |
+| `anatomy.yaml`     | Parts, the schematic, and the four body states.                    |
+| `behavior.md`      | Composition, how the height reaches the plot, state, localization. |
+| `accessibility.md` | Roles, the placeholder's live region, header controls.             |
+| `tokens.yaml`      | The `--ui-*` tokens the widget references.                         |
+
+## No Figma Code Connect
+
+Deliberately absent. `ChartWidget` has no node of its own: in Figma the shape
+lives inside each chart's own component set (ChartArea `8174:22232`, ChartBar
+`8700:55606`, …), which wrap the `_CardLegacy` instance — and that maps to
+`Card`, which is already connected.
+
+So the connection belongs on the per-type chart components, whose examples
+should show `<ChartWidget>` wrapping their plot. A `.figma.tsx` here would have
+to point at one arbitrary chart set and would read as if the widget were that
+chart.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `header` | `CardHeaderProps` | — | no | The card header, forwarded verbatim to `CardHeader` — `title`, `description`, `extras` (a filter chip), `actions` (the ⋯ menu), `isDraggable`, `isSwitchable`, `hasAvatar`, `hasRename`, `isCollapsible`. Omit for a header-less widget. |
+| `orientation` | `'vertical' | 'horizontal'` | `vertical` | no | How the `metric` and plot are arranged inside the card body. `vertical` (default) — metric above the plot, full width; the metric takes its natural height and the plot fills the rest. `horizontal` — metric and plot side by side, each `flex-1`; use for compact (sm/288px) widgets where vertical space is at a premium. |
+| `metric` | `ReactNode` | — | no | The readout beside or above the plot (depending on `orientation`), typically a `Metric`. |
+| `variant` | `'area' | 'bar' | 'line' | 'donut' | 'radial' | 'funnel' | 'radar' | 'sankey' | 'scatter' | 'treemap' | 'table' | 'text'` | — | no | Which chart the widget holds. Only used while `state="empty"`, to pick the silhouette for that chart type. Forwarded to `ChartState`. |
+| `state` | `'loading' | 'empty' | 'error'` | — | no | Renders `ChartState` in place of the plot, keeping the header. `error` additionally gives the Card its error border. |
+| `stateDescription` | `ReactNode` | — | no | Text below the placeholder illustration or glyph. Forwarded to `ChartState` as `description`. Defaults to the per-state built-in ("Data is loading…" / "No data found" / "Something went wrong"). |
+| `stateAction` | `ReactNode` | — | no | Trailing action on the `error` placeholder — e.g. a retry button. |
+| `bodyClassName` | `string` | — | no | Class for the card body. Rarely needed — the body already fills the card. For the case where neither the grid nor the content gives a height, e.g. a placeholder-only widget outside a sized cell. |
+| `children` | `ReactNode` | — | no | The chart. Replaced by the placeholder while `state` is set. |
+| `render` | `useRender.RenderProp` | — | no | Replace the rendered `<div>` with another element or component (Base UI composition), forwarded to `Card`. How a dashboard gives each widget a landmark role — `render={<section aria-label="Sessions" />}` — which is the one thing the widget can't infer for itself. |
+
+## Behavior
+
+### Composition, not a container
+
+`ChartWidget` is a `Card` plus two things a card doesn't know about: what the
+body shows while there's no plot, and how much height to reserve for it.
+Everything else is `Card`'s.
+
+The `header` prop is typed `CardHeaderProps` and spread onto `CardHeader`. That
+is the whole header contract — title, description, the `extras` filter chip, the
+`actions` ⋯ menu, the drag handle, the switch, the avatar, rename, and the
+collapse trigger. None of it is re-declared here, so a header feature added to
+`Card` reaches this component without a change, and can't drift out of sync.
+
+The per-type chart components stay **card-less**. They are the plot; the card is
+composition. That keeps `<AreaChart>` usable inside a table cell, a popover or a
+`Metric`'s sparkline slot, where a card would be wrong.
+
+### No size of its own
+
+The Figma sets carry a `size` axis of `sm` / `md` / `lg`, but measuring all eight
+shows it only changes the frame **width** — 288 / 592 / 896. And every card, and
+every card body, is `HUG` vertically: the height is whatever the content adds up
+to.
+
+So the widget declares no size — it _passes one down_. The dashboard grid gives
+the card a height; the card is a full-height flex column; the header is
+`shrink-0`; the body takes the rest; and the plot slot takes what the metric row
+leaves. A chart given `size-full` therefore occupies the whole remaining card.
+
+`min-h-0` appears at every step of that chain, and it is load-bearing: without
+it a flex child refuses to shrink below its content's height, so a tall chart
+would push the card past the height the grid gave it instead of fitting inside.
+
+Dropped into a parent with no definite height, `h-full` resolves to `auto` and
+the card hugs its content instead — so a standalone widget still works, with the
+chart bringing its own height. `bodyClassName` covers the remaining gap: a
+placeholder-only widget outside a sized cell, where neither the grid nor the
+content can give a height.
+
+An earlier draft of this component reserved a fixed body height per chart type,
+reverse-engineered from the mockup frames (252 for area, 205 for funnel, …).
+That was wrong: those numbers are what a hug layout happened to produce, not a
+design constraint, and hard-coding them would have fought the grid.
+
+### State
+
+`state` renders `ChartState` **instead of** `children`. The header stays.
+
+`state="error"` also maps to `Card`'s `hasError`, so the error border and the
+error placeholder come from one prop. A caller can't get one without the other,
+which is what the mockups draw.
+
+`ChartState` owns the live-region contract (`role="status"` for loading/empty,
+`role="alert"` for error), so the announcement follows the placeholder rather
+than being re-declared on the widget.
+
+### Localization
+
+Every string is the caller's: the header's `title` / `description`, the metric's
+own labels, `stateDescription`, and the label inside `stateAction`. The only
+literals are `ChartState`'s per-state defaults, which `stateDescription` overrides.
+
+## Accessibility
+
+## Roles and structure
+
+The widget itself is a plain `div` (a `Card`) and adds no role: it is a grouping
+surface, and the meaning lives in what it holds.
+
+A dashboard that wants each widget to be a landmark uses `render`, which the
+widget forwards to `Card`:
+
+```tsx
+<ChartWidget
+  render={<section aria-label="Sessions" />}
+  header={{ title: 'Sessions' }}
+>
+  {chart}
+</ChartWidget>
+```
+
+The accessible name has to come from the caller: the header's `title` is visible
+text inside the region, not a name for it, so a landmark without an
+`aria-label` (or `aria-labelledby` pointing at the title) is an unnamed region.
+
+The heading text comes from `CardHeader`'s `title`. It is the widget's visible
+name, so a chart inside should not repeat it in its own accessible name.
+
+## The placeholder is the live region
+
+While `state` is set, `ChartState` is the live region — `role="status"`
+(`aria-live="polite"`) for loading and empty, `role="alert"`
+(`aria-live="assertive"`) for error. The widget deliberately does **not** add
+`aria-busy` around it: the placeholder is unmounted and replaced by the plot
+rather than un-busied, and some assistive tech defers announcing a busy region's
+content, which would swallow the loading announcement.
+
+A consumer that wants a busy signal sets `aria-busy` on the element it controls
+— the widget accepts it as a passthrough prop.
+
+## Header controls
+
+The header's affordances are `Card`'s and carry its labelling: the drag handle,
+switch, rename button and collapse trigger each take a label prop with a
+default, and the `actions` slot is the caller's own control (an icon button
+needs its own `aria-label` — the mockups' ⋯ menu has no visible text).
+
+## Colour is not the only signal
+
+`state="error"` changes the card's border colour, but the placeholder also
+carries an icon and a message, so the error is not conveyed by colour alone.