@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/combobox.md

@@ -0,0 +1,164 @@
+# Combobox
+
+> A searchable select built on Base UI's Combobox primitive — a typeable input that filters a list of items in a dropdown. Reuses the InputSelect token tier so it matches the non-searchable select. The legacy shadcn-uikit `combobox` was only a hardcoded Popover + cmdk demo; this is a real, reusable component.
+
+**Status:** draft · **Category:** forms · **Since:** v0.49.0
+
+## Import
+
+```tsx
+import { Combobox, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem, ComboboxEmpty } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Combobox items={frameworks}>
+  <ComboboxInput placeholder="Search…" />
+  <ComboboxContent>
+    <ComboboxEmpty>No results.</ComboboxEmpty>
+    <ComboboxList>
+      {(item) => <ComboboxItem key={item.value} value={item}>{item.label}</ComboboxItem>}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+A searchable select: a typeable input that filters a list of items in a dropdown.
+Built on Base UI's Combobox primitive and themed with the `--ui-input-select-*`
+tokens, so it matches `InputSelect` (the non-searchable sibling).
+
+> **Design-pending v1.** The legacy shadcn-uikit `combobox` was only a hardcoded
+> Popover + cmdk demo; this is a real, reusable component built on Base UI. There
+> is no `--ui-combobox-*` tier yet — it borrows InputSelect's.
+
+## When to use
+
+- Choosing one (or more) options from a list long enough to need filtering.
+
+## When not to use
+
+- A short, fixed option set with no need to search — use `InputSelect`.
+- Free-text entry with optional suggestions — use an autocomplete (future).
+
+## Parts
+
+| Export               | Purpose                                                          |
+| -------------------- | ---------------------------------------------------------------- |
+| `Combobox`           | Root — holds `items` + value; filters by the input.              |
+| `ComboboxInput`      | The field box — typeable input + clear (✕) + chevron trigger.    |
+| `ComboboxContent`    | The portaled dropdown surface.                                   |
+| `ComboboxList`       | The list; children may be a function mapped over filtered items. |
+| `ComboboxItem`       | One option (trailing check when selected).                       |
+| `ComboboxEmpty`      | The "no results" message.                                        |
+| `ComboboxGroup`      | An optional group of items.                                      |
+| `ComboboxGroupLabel` | A group heading.                                                 |
+
+## Example
+
+```tsx
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxList,
+  ComboboxItem,
+} from '@acronis-platform/ui-react';
+
+const frameworks = [
+  { value: 'next', label: 'Next.js' },
+  { value: 'astro', label: 'Astro' },
+];
+
+<Combobox items={frameworks}>
+  <ComboboxInput placeholder="Search framework…" clearable />
+  <ComboboxContent>
+    <ComboboxEmpty>No framework found.</ComboboxEmpty>
+    <ComboboxList>
+      {(item) => (
+        <ComboboxItem key={item.value} value={item}>
+          {item.label}
+        </ComboboxItem>
+      )}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `items` | `readonly Value[]` | — | no | The options. When items are `{ value, label }` objects, the label/value are extracted automatically for display, filtering, and form submission. |
+| `value` | `Value | Value[] | null` | — | no | The selected value (controlled). Use defaultValue for uncontrolled. |
+| `defaultValue` | `Value | Value[] | null` | — | no | The initial selected value (uncontrolled). |
+| `multiple` | `boolean` | `false` | no | Whether multiple items can be selected. |
+| `open` | `boolean` | — | no | Whether the dropdown is open (controlled). |
+| `defaultOpen` | `boolean` | `false` | no | Whether the dropdown is initially open (uncontrolled). |
+| `disabled` | `boolean` | `false` | no | Disables the combobox. |
+| `name` | `string` | — | no | Identifies the field when a form is submitted. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onValueChange` | `(value: Value | Value[] | null, eventDetails) => void` | Fired when the selected value changes. |
+
+## Behavior
+
+Combobox is built on Base UI's Combobox. The root holds the `items` and the
+selected value and filters the items by the input text. The list children may be a
+function `(item) => …` mapped over the filtered items.
+
+```gherkin
+Scenario: Open and list
+  Given a Combobox with items
+  When the user focuses the input (or clicks the chevron)
+  Then the dropdown opens and lists the items as options
+```
+
+```gherkin
+Scenario: Filter by typing
+  Given the dropdown is open
+  When the user types into the input
+  Then only items matching the text remain
+```
+
+```gherkin
+Scenario: Empty
+  Given the typed text matches no items
+  Then the ComboboxEmpty message is shown
+```
+
+```gherkin
+Scenario: Select
+  Given the dropdown is open
+  When the user clicks an item (or presses Enter on the highlighted one)
+  Then onValueChange fires with that item's value
+  And the input shows the item's label and the dropdown closes
+```
+
+```gherkin
+Scenario: Clear
+  Given a clearable input with a value
+  When the user activates the clear (✕) button
+  Then the value is cleared
+```
+
+## Accessibility
+
+- Built on Base UI's Combobox, which implements the WAI-ARIA combobox pattern:
+  the input has `role="combobox"` with `aria-expanded` / `aria-controls`, the list
+  is a `listbox`, and items are `option`s. Keyboard support (↑/↓ to move, Enter to
+  select, Esc to close, typeahead) and focus management come from the primitive.
+- Pair the field with a label — wrap it in a `Field` with a `FieldLabel`, or set
+  `aria-label` on the `ComboboxInput`.
+- The clear and chevron controls have accessible labels ("Clear" / "Toggle").
+- Don't rely on the highlight color alone — the selected item also shows a check.
+
+## Contrast
+
+Combobox reuses the `--ui-input-select-*` tokens, which meet contrast in light and
+dark for the field box, dropdown surface, item text, and the highlighted/selected
+item backgrounds.

package/dist/llms/composed-chart.md

@@ -0,0 +1,508 @@
+# ComposedChart
+
+> A typed composed (mixed) chart over the shared `Chart` primitives. Plots a `series` list over one shared category axis, where each entry picks its own render `type` (bar / line / area), inside a `ChartContainer` with tooltip and legend chrome. No variant axes — the mix is data-driven via `series[].type`. Series render in the caller's `series` order (later entries paint on top). Ported from the apps/demo `ComposedChartPlayground`.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { ComposedChart } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ComposedChart
+  config={config}
+  data={data}
+  series={[
+    { key: 'revenue', type: 'bar', stackId: 'total' },
+    { key: 'forecast', type: 'bar', stackId: 'total' },
+    { key: 'profit', type: 'line', showDots: true },
+  ]}
+  xKey="month"
+  className="h-[320px] w-[560px]"
+/>
+```
+
+A typed composed (mixed) chart built on the shared `Chart` primitives. Give it
+`data`, a per-series `config`, and a `series` list where each entry picks its own
+render `type` (bar / line / area); it renders a themed recharts `ComposedChart` —
+tooltip, legend, axes, and grid included — so you don't hand-compose recharts
+children.
+
+Series colors come from the `palette` prop — a dataviz palette resolving to the
+`--ui-dataviz-*` tokens, `categorical` by default — not from `config`.
+
+> **Design-pending v1.** Ported from the apps/demo `ComposedChartPlayground`. The
+> chrome is reconciled with Figma later; Code Connect is deferred.
+
+## When to use
+
+- Overlaying related measures with different shapes — e.g. revenue **bars** with
+  a profit-margin **line**, or volume **bars** behind a trend **area**.
+- Emphasizing one series (line on top) against a backdrop of others (bars/areas).
+- Two measures whose **units or magnitudes** differ (a count and a rate) — put one
+  on the secondary value axis so neither flattens the other.
+
+## When not to use
+
+- All series are the same kind — use `BarChart`, `LineChart`, or `AreaChart`.
+- Part-to-whole — use a pie/donut chart.
+- Two measures a reader would want to compare **directly**, value against value —
+  two scales make any crossing point an artifact of the domains, not a fact about
+  the data. Split into separate charts (or share one axis) instead.
+
+## Two value axes
+
+A series opts in with `yAxis: 'secondary'`, and the second axis appears on the
+side opposite the primary one:
+
+```tsx
+<ComposedChart
+  config={config}
+  data={data}
+  series={[
+    { key: 'revenue', type: 'bar' },
+    { key: 'conversion', type: 'line', yAxis: 'secondary' },
+  ]}
+  xKey="month"
+  secondaryYUnit="%"
+/>
+```
+
+Each axis takes its own unit, tick formatter, tick count, and domain
+(`secondaryYUnit`, `secondaryYTickFormatter`, `secondaryYAxisTickCount`,
+`secondaryYAxisDomain`, `secondaryYAxisLabel`). `yAxisOrientation` moves the
+primary axis to the right and mirrors the pair; `showSecondaryYAxis: false` keeps
+the second scale but drops its chrome. The grid's horizontal lines follow the
+primary axis only — a second set from a different domain would cross the first at
+meaningless heights. If every series opts in, the primary axis has nothing measured
+against it: it isn't rendered, and the grid follows the secondary axis instead.
+
+Give the two axes matching domain presets when you want their tick rows to line
+up; a tightly fitted (`auto`) secondary domain will otherwise place its ticks
+between the primary axis's gridlines.
+
+## Per-series styling and stacking
+
+Every styling prop on the chart is the **default a series can override**, keyed by
+the same name on its `series[]` entry — `color`, `curve`, `strokeWidth`,
+`strokeDasharray`, `showDots`, `showActiveDots`, `connectNulls`, `barRadius`,
+`barSize`, `showActiveBar`, `showBackground`, `fillOpacity`, `legendType`:
+
+```tsx
+<ComposedChart
+  config={config}
+  data={data}
+  strokeWidth={3}
+  series={[
+    { key: 'revenue', type: 'bar', stackId: 'total' },
+    { key: 'forecast', type: 'bar', stackId: 'total' },
+    // Reads as a projection: dashed, thinner than the chart default, no dots.
+    {
+      key: 'projection',
+      type: 'line',
+      strokeDasharray: '5 5',
+      strokeWidth: 1.5,
+    },
+  ]}
+  xKey="month"
+/>
+```
+
+Series sharing a `stackId` stack — **bars with bars, areas with areas**. The ids
+are namespaced per mark type, so reusing one id across types can't merge a bar
+into an area's stack, and a line ignores it (recharts does not stack lines). Only
+the segment at the top of a stack rounds its corners, and its data labels centre
+in their own segment (a stacked segment has no free space at its growing end).
+
+`legendType: 'none'` keeps a series off the legend; `line` / `rect` pick its
+marker. The wider recharts icon set is deliberately not exposed — the legend draws
+its own marker and reads only those cases.
+
+## References
+
+`referenceLine` draws dashed rules: a fixed `value`, the `average` of one/every
+series, or — with `category` — a rule _across_ the categories at one of them, the
+hand-off between actuals and forecast. `referenceArea` shades a band behind a
+range of categories (`from`/`to`, inclusive, each a category value or a row
+index). Both take an array to draw several.
+
+A rule belongs to **one scale**. On a chart carrying two value axes, `yAxis` picks
+which — defaulting to the axis of the series named by `average`, and to `primary`
+otherwise — and `average: true` pools only the series measured against that axis.
+Averaging a count and a rate together, or plotting a rate's mean against a count's
+scale, would put the rule somewhere meaningless; neither can happen by accident.
+
+## Variants
+
+`orientation` (`vertical` — the default — / `horizontal`) is the one CVA variant
+axis: it is the direction the marks grow, and it re-roles both axes. Horizontal
+puts the categories on the y-axis and the values on x, turns the grid lines
+vertical, rounds each bar's right end instead of its top, and renders a secondary
+value axis as a second x-axis along the top edge. `yAxisOrientation` goes inert
+there — the value axis is X, so the primary sits along the bottom and the
+secondary along the top, and neither has a left/right side to pick.
+
+The mark mix is _not_ a variant — it is data-driven via each `series[].type`
+(`bar` / `line` / `area`). Series render in the order you list them (later entries
+sit on top, whatever their mark type) — order them so a thin line comes after the
+bars/areas it should overlay.
+
+## Example
+
+```tsx
+import { ComposedChart } from '@acronis-platform/ui-react';
+import type { ChartConfig } from '@acronis-platform/ui-react';
+
+const data = [
+  { month: 'Jan', revenue: 2400, profit: 1600 },
+  { month: 'Feb', revenue: 1398, profit: 1200 },
+  { month: 'Mar', revenue: 9800, profit: 4800 },
+];
+
+const config = {
+  revenue: { label: 'Revenue', color: 'var(--ui-background-brand-secondary)' },
+  profit: {
+    label: 'Profit',
+    color: 'var(--ui-background-status-strong-success)',
+  },
+} satisfies ChartConfig;
+
+<ComposedChart
+  config={config}
+  data={data}
+  series={[
+    { key: 'revenue', type: 'bar' },
+    { key: 'profit', type: 'line' },
+  ]}
+  xKey="month"
+  className="h-[320px] w-[560px]"
+/>;
+```
+
+Series colors reference existing semantic `--ui-*` tokens. `--ui-background-status-strong-*`
+is chromatic in every brand; `--ui-background-brand-secondary` is brand-dependent
+(blue in `default`, neutral in some white-label brands), so it is not color-stable
+across brands until the real data-viz palette lands.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `orientation` | `'vertical' | 'horizontal'` | `'vertical'` | no | Direction the marks grow. `vertical` = bars rise and the categories sit on the x-axis; `horizontal` = bars extend rightward, the categories move to the y-axis and the values to x (where a secondary value axis becomes a second x-axis along the top edge). |
+| `data` | `ReadonlyArray<Record<string, string | number | null>>` | — | yes | Row-per-category data — each row holds `xKey` plus one numeric field per series. A null value breaks the line/area at that point unless `connectNulls` is set. |
+| `config` | `ChartConfig` | — | yes | Series take their colour from the container's `palette`; each entry, keyed by a `series[].key`, maps that series to a `label` and an optional `tone`. Resolved into the `--color-<key>` custom properties the marks paint from. |
+| `series` | `ComposedSeries[]` | — | yes | Series to plot, each `{ key, type }` plus any per-series override. `type` is `bar` / `line` / `area`. Rendered in array order — later entries sit on top, whatever their mark type; order them so a thin line comes after the bars/areas it should overlay. Each key must exist in `config` and every data row. Per-series keys, each overriding the chart-level default of the same name where one exists — `yAxis` (`primary` / `secondary`, which value axis the series is measured against), `color`, `stackId` (stacks with the series of the same mark type carrying that id; ignored on a line), `curve`, `strokeWidth`, `strokeDasharray`, `showDots`, `showActiveDots`, `connectNulls`, `barRadius`, `barSize`, `showActiveBar`, `showBackground`, `fillOpacity`, and `legendType` (`line` / `rect` / `none`, where `none` keeps the series off the legend). |
+| `xKey` | `string` | — | yes | The category dimension key shared across rows. |
+| `xAxisLabel` | `string` | — | no | Title rendered beneath the horizontal (X) axis. |
+| `yAxisLabel` | `string` | — | no | Title rendered beside the vertical (Y) axis (rotated). |
+| `yUnit` | `string` | — | no | Unit suffix appended to Y-axis tick values (recharts `unit`). Applies while the values are on Y, which is the default orientation; with `orientation="horizontal"` they move to X and `xUnit` takes over. |
+| `referenceLine` | `ComposedChartReferenceLine | ComposedChartReferenceLine[]` | — | no | One or more dashed rules. A `value` (or an `average` of one/every series) places the rule on a value axis; a `category` places it across the category axis at that category — the hand-off into a forecast. Each takes an optional `label`; a value position wins when both are given, and a category that is not in the data draws nothing. On a chart with two value axes, `yAxis` picks the scale the rule is measured against — defaulting to the axis of the series named by `average`, and to `primary` otherwise — and `average: true` pools only the series on that axis, so two scales are never averaged together. `labelPosition` moves the caption off its default (the top of the rule) when the rule lands where the series already is. |
+| `referenceArea` | `ComposedChartReferenceArea | ComposedChartReferenceArea[]` | — | no | One or more shaded bands behind a range of categories (`from` / `to`, inclusive, each a category value or a row index, either omittable) with an optional `label`. |
+| `curve` | `'linear' | 'monotone' | 'step'` | `'monotone'` | no | Interpolation for the line and area series. Per-series `curve` overrides it. |
+| `xUnit` | `string` | — | no | Unit suffix on the value-axis tick values when the values are on X (`orientation="horizontal"`). |
+| `strokeWidth` | `number` | `2 (line series)` | no | Stroke width for the line series. Area series keep the thinner outline unless this is set explicitly. |
+| `showDots` | `boolean` | `false` | no | Render a dot at each point of the line and area series. |
+| `showActiveDots` | `boolean` | — | no | Render the hover dot on the line and area series. Unset, the renderer's own default applies. |
+| `connectNulls` | `boolean` | `false` | no | Bridge null gaps in the data instead of breaking the line/area. |
+| `barSize` | `number` | — | no | Fixed bar thickness in px. Unset, bars are sized from the available width. |
+| `barGap` | `number | string` | — | no | Gap between bars of the same category, in px or a percentage string. |
+| `barCategoryGap` | `number | string` | — | no | Gap between category groups, in px or a percentage string. |
+| `showBackground` | `boolean` | `false` | no | Draw a full-height track behind every bar. |
+| `backgroundFill` | `string` | `the secondary surface token` | no | Fill for the track background. |
+| `showActiveBar` | `boolean` | `false` | no | Highlight the hovered bar. |
+| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area inset. Any side left out keeps the chart's own default (which is already widened when `showLabels` is on, and when a labelled reference rule stands vertical, so neither caption can be clipped at the plot edge). |
+| `tooltipCursor` | `boolean` | `true` | no | Draw the hover cursor (the band/rule under the tooltip). |
+| `legendPosition` | `'top' | 'bottom'` | `'bottom'` | no | Which edge the legend sits on. |
+| `barRadius` | `number` | `4` | no | Corner radius on the growing end of bar series (0 for square corners). In a stack only the segment at the top of the stack is rounded. |
+| `fillOpacity` | `number` | `0.3` | no | Flat-fill opacity for area series. Per-series `fillOpacity` overrides it. |
+| `showGrid` | `boolean` | `true` | no | Render the CartesianGrid. |
+| `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
+| `showLegend` | `boolean` | `true` | no | Render the legend. |
+| `tooltipContent` | `ReactElement | ((props) => ReactNode)` | — | no | Replace the default tooltip. Pass a configured ChartTooltipContent (from this library) — e.g. with a formatter / labelFormatter — to customize the tooltip content without composing recharts. Ignored when showTooltip is false. |
+| `showXAxis` | `boolean` | `true` | no | Render the X axis (its ticks and title). Set false to hide it. |
+| `showYAxis` | `boolean` | `true` | no | Render the Y axis (its ticks and title). Set false to hide it. |
+| `xTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each X-axis tick value. Unlike the `unit` suffix (append-only), a formatter transforms the value — abbreviate, prefix a symbol, or map to a label. Use formatCompactNumber / formatPercent / createTickFormatter from the shared Chart primitives, or any function. |
+| `yTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each Y-axis tick value (see xTickFormatter). |
+| `xAxisAngle` | `number` | — | no | Rotate the X-axis tick labels by this many degrees (a negative angle tilts them up toward the right); the tick anchor + axis height adjust. |
+| `xAxisInterval` | `number | 'preserveStart' | 'preserveEnd' | 'preserveStartEnd' | 'equidistantPreserveStart'` | — | no | X-axis tick density — a recharts placement strategy, or a fixed number of ticks to skip between two rendered ones (recharts interval: 0 shows every tick, 1 every other one, 2 every third). |
+| `yAxisTickCount` | `number` | — | no | Desired number of ticks on the value axis (recharts tickCount; a hint, not exact). Applies to whichever axis holds the values — Y by default, X with orientation="horizontal". |
+| `yAxisDomain` | `'auto' | 'dataMin-dataMax' | 'zero'` | — | no | Value-axis domain preset — auto (fit the data at both ends; the axis need not include 0), zero (anchor the axis at 0, which is also recharts' behaviour when the prop is omitted), or dataMin-dataMax (tight to the data, no padding). Applies to whichever axis holds the values — Y by default, X with orientation="horizontal". |
+| `yAxisOrientation` | `'left' | 'right'` | `'left'` | no | Which side the primary value axis sits on. The secondary axis always takes the opposite side, so the pair mirrors as a whole. Inert with orientation="horizontal": the value axis is X there, so the primary sits along the bottom edge and the secondary along the top, and neither has a left/right side to pick. |
+| `showSecondaryYAxis` | `boolean` | `true` | no | Render the secondary axis's ticks and title. Setting it false keeps the second scale — series measured against it stay scaled that way — and drops only its chrome, the meaning showYAxis has for the primary axis. Inert unless a series selects the secondary axis. |
+| `secondaryYAxisLabel` | `string` | — | no | Title rendered beside the secondary value axis (rotated). |
+| `secondaryYUnit` | `string` | — | no | Unit suffix appended to the secondary axis's tick values. |
+| `secondaryYTickFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each secondary-axis tick value — the counterpart of yTickFormatter. |
+| `secondaryYAxisTickCount` | `number` | — | no | Desired number of ticks on the secondary axis (recharts tickCount; a hint, not exact). |
+| `secondaryYAxisDomain` | `'auto' | 'dataMin-dataMax' | 'zero'` | — | no | Domain preset for the secondary axis — the same presets as yAxisDomain, resolved independently of it. |
+| `gridDashed` | `boolean` | — | no | Draw grid lines dashed instead of solid. |
+| `gridHorizontal` | `boolean` | — | no | Show horizontal grid lines (defaults to the chart's own default when unset). |
+| `gridVertical` | `boolean` | — | no | Show vertical grid lines (defaults to the chart's own default when unset). |
+| `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |
+| `animationDuration` | `number` | — | no | Animation duration in ms. |
+| `animationBegin` | `number` | — | no | Delay before the animation starts, in ms. |
+| `animationEasing` | `'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'` | — | no | Easing curve. |
+| `showLabels` | `boolean` | `false` | no | Render a value label on each data point/segment. |
+| `labelPosition` | `'top' | 'bottom' | 'left' | 'right' | 'center' | 'insideTop' | 'insideBottom' | 'insideLeft' | 'insideRight' | 'insideStart' | 'insideEnd'` | — | no | Where the value labels sit. |
+| `labelFormatter` | `(value) => string` | — | no | Format each label value (reuses the tick formatters). |
+| `showBrush` | `boolean` | `false` | no | Render a range brush beneath the chart — drag a handle (or the selected window) to zoom the series into a slice of the data. |
+| `brushHeight` | `number` | `28` | no | Height of the brush strip in px. A non-positive value falls back to the default rather than erasing the brush. |
+| `brushAriaLabel` | `string` | `'Chart range selector'` | no | Accessible name for the brush's two range handles, which are focusable `role="slider"` elements. Consumers localize by passing their own. |
+
+## Behavior
+
+`ComposedChart` is a typed [recharts](https://recharts.org) composition over the
+shared `Chart` primitives. It plots a `series` list over one shared category axis
+(`xKey`), where each entry picks its own render `type` (bar / line / area).
+
+```gherkin
+Scenario: Render mixed series from data and config
+  Given data rows and a config mapping each series key to a label and color
+  And series [{ key: "revenue", type: "bar" }, { key: "profit", type: "line" }]
+  Then a <Bar> renders for revenue and a <Line> for profit
+  And each paints from its injected --color-<key> custom property
+```
+
+```gherkin
+Scenario: Paint order follows the series array
+  Given series lists a bar then a line
+  Then the bar paints first and the line paints on top of it
+  And reordering the series entries reorders the painted layers
+  And the order holds across mark types — an area listed after a bar covers that bar
+```
+
+```gherkin
+Scenario: Curve interpolation (default monotone)
+  Given curve is "linear", "monotone", or "step"
+  Then the line and area series use that recharts `type`
+```
+
+```gherkin
+Scenario: Bar corner radius
+  Given barRadius is greater than 0
+  Then each bar series rounds its growing end by that radius
+  And in a stack only the segment at the top of the stack is rounded
+```
+
+```gherkin
+Scenario: Orientation re-roles both axes
+  Given orientation is "horizontal"
+  Then the marks grow rightward with the categories on the y-axis and the values on x
+  And the grid lines run vertically
+  And each bar rounds its right end instead of its top
+  And a secondary value axis renders as a second x-axis along the top edge
+  And yAxisOrientation is inert, leaving the category axis where it is
+```
+
+```gherkin
+Scenario: A series overrides a chart-level default
+  Given the chart sets strokeWidth
+  And one series entry sets its own strokeWidth
+  Then that series uses its own value and every other series uses the chart's
+  And the same holds for color, curve, strokeDasharray, showDots, showActiveDots,
+      connectNulls, barRadius, barSize, showActiveBar, showBackground and fillOpacity
+```
+
+```gherkin
+Scenario: Series stack by shared id, within a mark type
+  Given two bar series and two area series, each pair sharing a stackId
+  Then each pair is summed into one stack
+  And a bar and an area sharing the same id are not merged into one stack
+  And a line series ignores stackId
+```
+
+```gherkin
+Scenario: Null values break a series unless bridged
+  Given a data row whose series value is null
+  Then the line/area breaks at that point
+  And with connectNulls the gap is bridged into one continuous mark
+```
+
+```gherkin
+Scenario: Reference rules and bands
+  Given a referenceLine with a value or an average of a series
+  Then a dashed rule renders at that position on the value axis
+  And a referenceLine with a category renders a rule across the categories at it
+  And a category that is not in the data renders no rule
+  And a referenceArea shades the band spanning its from/to categories
+  And each renders its label when one is given
+  And with orientation "horizontal" a value rule stands vertical, a category rule
+      lies flat, and the band runs down the category axis
+  And a labelled vertical rule reserves plot headroom for the caption it hangs
+      above the plot, so it is not clipped
+```
+
+```gherkin
+Scenario: A reference rule belongs to one value axis
+  Given a chart with a primary and a secondary value axis
+  When a referenceLine averages a series measured against the secondary axis
+  Then the rule is drawn against that axis, not the primary one
+  And "average: true" pools only the series on the axis the rule is drawn against
+  And an explicit yAxis on the rule overrides both
+  And a secondary yAxis is ignored while no series has brought that axis into being
+```
+
+```gherkin
+Scenario: A series is kept off the legend
+  Given a series entry sets legendType to "none"
+  Then the legend renders every other series and omits that one
+  And the series itself still renders and appears in the tooltip
+```
+
+```gherkin
+Scenario: Area fill
+  Given an area series and a fillOpacity
+  Then the area fills at that opacity below its line
+```
+
+```gherkin
+Scenario: Tooltip on hover
+  Given showTooltip is true
+  When the user hovers a category
+  Then a card shows the category label and one row per series (indicator + value)
+```
+
+```gherkin
+Scenario: Legend
+  Given showLegend is true
+  Then a swatch + label renders for each series
+  And legendPosition places it above or below the plot (default below)
+```
+
+```gherkin
+Scenario: A series opts in to a second value axis
+  Given series [{ key: "revenue", type: "bar" }, { key: "conversion", type: "line", yAxis: "secondary" }]
+  Then a second value axis renders on the side opposite the primary one
+  And the bar is scaled against the primary axis and the line against the secondary
+  And each axis resolves its own unit, tick formatter, tick count, and domain
+```
+
+```gherkin
+Scenario: The second axis exists only when a series asks for it
+  Given no series entry sets yAxis to "secondary"
+  Then no second axis renders
+  And the secondary-axis props have no effect
+  And the chart's output is unchanged from before the prop existed
+```
+
+```gherkin
+Scenario: Hiding the second axis keeps its scale
+  Given a series measured against the secondary axis
+  And showSecondaryYAxis is false
+  Then the second axis's ticks and title are not rendered
+  And that series stays scaled against it rather than falling back to the primary
+```
+
+```gherkin
+Scenario: Flipping the primary axis mirrors the pair
+  Given yAxisOrientation is "right"
+  Then the primary axis renders on the right
+  And a secondary axis, if present, renders on the left
+```
+
+```gherkin
+Scenario: Grid lines follow the primary axis
+  Given two value axes with different domains
+  Then the horizontal grid lines are drawn at the primary axis's ticks only
+  And the secondary axis does not add a second set of grid lines
+```
+
+```gherkin
+Scenario: Every series opts in, leaving the primary axis empty
+  Given every series entry sets yAxis to "secondary"
+  Then the primary axis is not rendered and gives up its gutter
+  And the horizontal grid lines follow the secondary axis instead
+```
+
+```gherkin
+Scenario: Empty data
+  Given data is an empty array
+  Then the chart renders its axes and grid with no series marks and does not throw
+```
+
+```gherkin
+Scenario: Entrance animation is opt-in
+  Given animate is unset
+  Then the series render at their final geometry with no entrance animation
+  And the committed visual baselines are unaffected
+```
+
+```gherkin
+Scenario: Reduced motion
+  Given animate is true
+  And a user with prefers-reduced-motion
+  Then the entrance animation does not play and the series render at their final geometry
+  And the same applies when rendering on the server
+```
+
+```gherkin
+Scenario: Range brush
+  Given showBrush is true
+  Then a brush strip renders beneath the plot with a handle at each end
+  And dragging a handle (or the selected window) zooms the series to that slice
+  And the category axis and tooltip follow the selected range
+  And the brush renders whether or not the category axis is shown
+  And unset renders no brush
+```
+
+```gherkin
+Scenario: Range brush keyboard and accessible name
+  Given showBrush is true
+  Then each of the two handles is reachable by Tab
+  And the focused handle moves one row per left/right arrow key press
+  And each handle exposes brushAriaLabel as its accessible name
+```
+
+## Accessibility
+
+- recharts' `accessibilityLayer` is **on by default** (recharts v3), giving the
+  chart keyboard focus and an accessible description of the plotted points.
+- The **range brush** (`showBrush`) is the only interactive control these charts
+  render. It adds two focusable `role="slider"` handles: Tab reaches each one and
+  the left/right arrow keys move the selection a row at a time, so the whole
+  feature is operable without a pointer.
+  - Both handles take their accessible name from `brushAriaLabel` (default
+    `'Chart range selector'`); pass your own to localize it. Never leave it to
+    recharts' fallback, which names the handles from a `name` field on the data
+    row and otherwise announces "Min value: undefined, Max value: undefined".
+  - The handles keep a visible focus indicator: the shared `ChartContainer`
+    suppresses outlines on recharts layers, so it re-enables one for
+    `.recharts-brush-traveller` specifically (an `outline`, since `box-shadow`
+    does not paint on SVG children).
+  - The two range captions only appear while a handle is hovered, dragged, or
+    focused — they are a supplement to the category axis, not a replacement for
+    it. Zooming changes which rows are plotted, so **pair the brush with a text
+    alternative that reflects the current range** rather than the full series.
+- A composed chart is inherently visual. **Pair it with a text alternative** — a
+  caption, a summary sentence, or an adjacent data table carrying the same
+  numbers — and give the chart an accessible name (`aria-label` /
+  `aria-labelledby` referencing a visible heading) when it is meaningful on its
+  own. The wrapper forwards native `div` attributes, so `aria-*` pass through.
+- Do **not** rely on color alone to distinguish series. Keep `showLegend` (or the
+  tooltip) visible so each color is paired with a text label; the differing
+  render types (bar vs line vs area) add a second, non-color channel.
+- Mixed series can share one value axis even when their magnitudes differ wildly
+  (e.g. revenue vs order-count) — call out the scale in the caption so a small
+  bar next to a tall line isn't misread.
+- With **two value axes** (`yAxis: 'secondary'`), which series is measured against
+  which scale is conveyed by position alone: nothing in the legend, the tooltip,
+  or the accessible description names an axis, and the tooltip renders the two
+  values without their units. Say it in the text alternative — "revenue in $ on
+  the left, conversion in % on the right" — and prefer a `secondaryYAxisLabel` +
+  `yAxisLabel` pair so the mapping is at least visible to a sighted reader.
+- The chrome (tooltip, legend, axis ticks, grid) resolves to semantic `--ui-*`
+  tokens that meet contrast in light and dark. **Series colors are
+  caller-supplied** via `config` — pick values that meet 3:1 against the surface
+  and are distinguishable for color-vision deficiencies. The borrowed semantic
+  tokens are a design-pending stopgap until the `--ui-chart-*` palette lands.
+- Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
+  on the a11y layer for heavily-customized charts.
+
+## Contrast
+
+Chart chrome meets contrast in both themes via the semantic tokens. Series fills
+and strokes come from `config` and are the caller's responsibility — note that an
+area's translucent `fillOpacity` lowers its effective contrast against the surface.