prime-ui-kit 0.9.3 → 0.11.0

package/src/components/card/COMPONENT.md

@@ -10,6 +10,7 @@
 - A chart or text widget with a header and controls (`panel`).
 - A settings or profile form grouped on its own surface (`panel` + `Body` + `Footer`).
 - An activity list (`list`), a call to action (`cta`), a tile with an image on top (`cover`).
+- A tile that is itself the way to its details — a KPI that opens its report, a project tile (`asChild` with a link or a button).
 
 ## When not to use
 - A whole page region with a title and description → [PageContent](../page-content/COMPONENT.md) sections; do not wrap every section in a card.
@@ -24,14 +25,15 @@ import { Card } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Card.Root variant="panel"        Header(Title, …trailing) · Body · Media · Footer
-Card.Root variant="mini"         Icon · Label · Value · Media?
-Card.Root variant="stat-trend"   Label · Value · Delta
+Card.Root variant="panel"        Header(Title, Description?, …trailing) · Body · Media · Footer
+Card.Root variant="mini"         Icon · Label · Value · Meta? · Media?
+Card.Root variant="stat-trend"   Label · Value · Delta · Meta?
                                  or Header(Badge or Icon, Value) · Description
 Card.Root variant="split"        Body(cell × 2: any element, e.g. <div> with Icon · Label · Value)
 Card.Root variant="cta"          Title · Description · Footer
 Card.Root variant="list"         Header(Title, …trailing) · List(ListItem …)
 Card.Root variant="cover"        Media · Body(Title, Description) · Footer
+Card.Root asChild                <a> or <button> (the only child) holding the parts of any template
 ```
 
 ## API
@@ -39,16 +41,17 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Card.Root
-`ref` → `HTMLDivElement`. A layer of the surface ladder (`data-depth` one above the surface around it: white on the light page, the next layer when nested; radius 12, the raised whisper only on the page, no border) and a size container; `variant` picks the template layout of its parts.
+`ref` → `HTMLDivElement` (the `asChild` element). A surface one layer above the one around it, no border, and a size container; `variant` picks the template layout of its parts.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `variant` | `"panel" \| "mini" \| "stat-trend" \| "split" \| "cta" \| "list" \| "cover"` | `"panel"` | Structural template: titled block with zones (`panel`), KPI tiles, a call to action, a list or a cover tile. |
 | `flat` | `boolean` | `false` | No raised shadow: a flat tile for dense grids. |
+| `asChild` | `boolean` | `false` | The whole card is one link or button: pass that element as the only child with the parts inside it; it gets hover, press and the focus ring. Nothing interactive may sit inside it. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` + `aria-labelledby` for a landmark block, and the other div attributes. |
 
 ### Card.Header
-`ref` → `HTMLDivElement`. The top row: `Card.Title` first, anything after it (a control, a quiet caption) at the end. In `panel` and `list` it is a padded zone with a faint hairline below; in `stat-trend` it can pair a leading badge or icon with a compact `Card.Value`. Wraps below 22rem.
+`ref` → `HTMLDivElement`. The top row: `Card.Title` first, anything after it (a control, a quiet caption) at the end. Wraps below 22rem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -63,7 +66,7 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
 ### Card.Description
-`ref` → `HTMLParagraphElement`. Secondary text (`<p>`, body-s, wraps): under the title of `cta` and `cover`, under the header of `stat-trend`.
+`ref` → `HTMLParagraphElement`. Secondary text (`<p>`, body-s): under the title of `cta` and `cover`, under the header of `stat-trend`; inside `Card.Header` it stacks under the title.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -105,6 +108,13 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 | `tone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Delta: color by meaning, not by sign (churn up is `danger`). |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
+### Card.Meta
+`ref` → `HTMLSpanElement`. The reference line of a KPI («Лидов 120 · сделок 18»): caption, muted, tabular; under the value.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
+
 ### Card.List · Card.ListItem
 `ref` → `HTMLUListElement` / `HTMLLIElement`. The `list` template: a `<ul>` of `<li>` rows with faint hairlines between them; head it with `Card.Header`.
 
@@ -137,6 +147,7 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `flat` | same fill, no shadow | dense grids of tiles | `false` |
+| `asChild` | the card is the link or button it wraps: lifts on hover (raised → overlay shadow), presses, focus ring | the whole tile opens its details | `false` |
 
 ## States
 | State | Driven by | DOM |
@@ -144,23 +155,32 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 | template | `variant` | `data-variant` |
 | flat | `flat` | `data-flat` |
 | depth | nesting: one above the nearest surface (the page and the AppShell panel are 0) | `data-depth` (`1`–`4`, `floating-1`/`floating-2` inside a floating layer); the fill is `--prime-color-layer-current`, the shadow only at depth 1 |
-| card width | container queries | `split` stacks below 22rem, `Header` wraps below 22rem, the `stat-trend` value changes at 20rem / 36rem |
+| card width | container queries | `split` stacks below 22rem, `Header` wraps below 22rem (a header control under its description), the `stat-trend` value changes at 20rem / 36rem |
+| hover | `asChild`, a fine pointer | the fill stays (a whole surface never changes its fill, foundation §8); the shadow lifts to `--prime-shadow-overlay` over `fast` |
+| press | `asChild`, `:active` | `scale(--prime-motion-press-scale)` over `fast`; reduced motion keeps it still |
+| focus | `asChild`, `:focus-visible` | the focus ring outside the card |
 
-Card is static: no hover, focus or press of its own.
+Without `asChild` a card is static: no hover, focus or press of its own. With it: `data-interactive` on the element.
 
 ## Layout & spacing
 - Grid of cards: `repeat(auto-fit, minmax(min(100%, 14rem), 1fr))`, gap `--prime-space-4`.
+- Radius `--prime-card-radius`, no border. In `panel` and `list` the `Header` is a padded zone with a faint inset hairline below; in `stat-trend` it can pair a leading Badge or icon with a compact `Card.Value`.
 - Padding `--prime-card-padding-m` (20); `Body` gap `--prime-card-gap` (16); fields inside `Body` 20 apart, one ladder step off the card.
 - Depth comes from nesting (foundation §4): on the page — the AppShell panel is the page — a card is layer 1 (white in light) with the raised whisper; inside another card it is the next layer, a flat tile. The ladder stops at layer 4.
 - Long values wrap, labels truncate; a chart SVG needs a CSS height.
-- In a `Header` the title takes the free width; a control or a caption after it sits at the end without a wrapper.
+- In a `Header` the title takes the free width; a control or a caption after it sits at the end without a wrapper. A `Card.Description` in the header stacks under the title, 4 apart; the control stays at the end, centred on both lines.
+- `Card.Meta` in `stat-trend` takes the bottom of the tile (`margin-top: auto`), so tiles of one row line their meta up; in `mini` and a `split` cell it sits in the text column under the value.
 
 ## Accessibility
 
 ### Keyboard
-No keyboard interaction.
+| Key | Action |
+|---|---|
+| `Tab` | A card with `asChild` is one stop: focus lands on the whole link or button. |
+| `Enter` | Opens the link or presses the button of a card with `asChild`. |
 
 ### ARIA
+- With `asChild` the card is the link or button itself; its name is the text of its parts. Nothing interactive may sit inside it — put row actions next to the card instead.
 - `Card.Root` is a plain `<div>`; give it `role="region"` + `aria-labelledby` only when it is a landmark-worthy block.
 - `Card.Title` renders `<h3>`; directly under the page title pass `as="h2"`.
 - Decorative icons in `Card.Icon` and cover images in `Card.Media` get `aria-hidden`; controls in `Card.Header` need their own names.
@@ -174,9 +194,10 @@ No `labels`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A company settings panel: a header, fields on the surface fill and buttons in the footer — `Card.Header`, `Card.Body`, `Card.Footer`. |
-| [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change — `variant`, `Card.Delta`. |
+| [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change and a reference line — `variant`, `Card.Delta`, `Card.Meta`. |
 | [kpi-media.tsx](examples/kpi-media.tsx) | A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. |
-| [panel-chart.tsx](examples/panel-chart.tsx) | A chart widget: a header with a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Media`. |
+| [panel-chart.tsx](examples/panel-chart.tsx) | A chart widget: a header with a short description and a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Description`, `Card.Media`. |
+| [interactive.tsx](examples/interactive.tsx) | Whole cards as links to their reports: one tab stop each, a lift on hover, a press and the focus ring — `asChild`. |
 | [content-templates.tsx](examples/content-templates.tsx) | Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. |
 | [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
 | [narrow.tsx](examples/narrow.tsx) | The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem. |
@@ -188,7 +209,10 @@ No `labels`.
 - Custom padding on a `panel` root → padding belongs to `Header` / `Body` / `Footer`.
 - A wrapper `<div>` around the label and the value of `mini` → put `Icon`, `Label`, `Value` straight into the root (or into a `split` cell); the template lays them out.
 - A chart SVG with only a `viewBox` → give it a CSS height.
+- A clickable `<div>` card with `onClick` → `asChild` with a real `<a href>` (Cmd-click, a new tab) or a `<button>`.
+- Buttons or links inside an `asChild` card → nested interactive elements; move them out of the card.
+- The reference figures written into `Card.Delta` or `Card.Label` → `Card.Meta`.
 
 ## Related
 - **Built from:** —
-- **See also:** [PageContent](../page-content/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)
+- **See also:** [PageContent](../page-content/COMPONENT.md), [DescriptionList](../description-list/COMPONENT.md) (record details inside a `Card.Body`), [Fieldset](../fieldset/COMPONENT.md) (groups of fields inside a settings card), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/card/examples/interactive.tsx

@@ -0,0 +1,28 @@
+/** Whole cards as links to their reports: one tab stop each, a lift on hover, a press and the focus ring — `asChild`. */
+import { Card, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const REPORTS = [
+  { href: "#orders", icon: "object.package", label: "Заказы за неделю", value: "1 248" },
+  { href: "#invoices", icon: "object.receipt", label: "Счета к оплате", value: "37" },
+  { href: "#team", icon: "object.users", label: "Активные менеджеры", value: "18" },
+] as const;
+
+export default function CardInteractiveExample() {
+  return (
+    <div className={styles.grid}>
+      {REPORTS.map((report) => (
+        <Card.Root key={report.href} variant="mini" asChild>
+          <a href={report.href}>
+            <Card.Icon>
+              <Icon name={report.icon} />
+            </Card.Icon>
+            <Card.Label>{report.label}</Card.Label>
+            <Card.Value>{report.value}</Card.Value>
+          </a>
+        </Card.Root>
+      ))}
+    </div>
+  );
+}

package/src/components/card/examples/panel-chart.tsx

@@ -1,4 +1,4 @@
-/** A chart widget: a header with a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Media`. */
+/** A chart widget: a header with a short description and a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Description`, `Card.Media`. */
 import { Card, SegmentedControl, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -16,6 +16,7 @@ export default function CardPanelChartExample() {
       <Card.Root variant="panel">
         <Card.Header>
           <Card.Title>Выручка</Card.Title>
+          <Card.Description>Оплаченные счета, без возвратов</Card.Description>
           <SegmentedControl.Root size="xs" defaultValue="month" aria-label="Период">
             <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
             <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>

package/src/components/card/examples/variants.tsx

@@ -1,4 +1,4 @@
-/** KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change — `variant`, `Card.Delta`. */
+/** KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change and a reference line — `variant`, `Card.Delta`, `Card.Meta`. */
 import { Badge, Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -26,12 +26,14 @@ export default function CardVariantsExample() {
         <Card.Label>Выручка за месяц</Card.Label>
         <Card.Value>4,2 млн ₽</Card.Value>
         <Card.Delta tone="success">+18% к сентябрю</Card.Delta>
+        <Card.Meta>Лидов 1 240 · сделок 186</Card.Meta>
       </Card.Root>
 
       <Card.Root variant="stat-trend">
         <Card.Label>Отток</Card.Label>
         <Card.Value>3,1%</Card.Value>
         <Card.Delta tone="danger">+0,6 п. п. за неделю</Card.Delta>
+        <Card.Meta>Ушло 38 из 1 226 клиентов</Card.Meta>
       </Card.Root>
     </div>
   );

package/src/components/chart-frame/COMPONENT.md

@@ -0,0 +1,265 @@
+# ChartFrame
+
+**Category:** data-display
+**Kind:** composite
+
+> A dashboard panel around any chart — Recharts, ECharts, visx, Chart.js or a hand-drawn SVG — with the title, a headline value, a measured plot area, a series legend, a tooltip body and a data table for screen readers.
+
+## When to use
+- A chart with axes or several series on a dashboard or a report page: revenue by month, invoices by week, leads by source.
+- Any chart library that should look like the kit: the panel, the type of axis labels, the legend, the tooltip and the loading / empty / error states come from ChartFrame, the plot from the library.
+- A library that needs explicit `width` and `height` (Chart.js, visx, Recharts without `ResponsiveContainer`): `renderPlot` hands it the measured size.
+
+## When not to use
+- A single number with its trend in a tile → [Sparkline](../sparkline/COMPONENT.md) (in a `Card`).
+- Shares of a whole or a ranking → [ProgressBar](../progress-bar/COMPONENT.md) with `segments` or `layout="rows"`, [ProgressCircle](../progress-circle/COMPONENT.md).
+- Exact values to read, sort or compare row by row → [DataTable](../data-table/COMPONENT.md).
+- A KPI without a chart → [Card](../card/COMPONENT.md) `variant="stat-trend"`.
+
+## Import
+```tsx
+import { ChartFrame, type ChartFrameSeries, chartColors } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+ChartFrame.Root              <figure>; surface of the depth ladder; state, series, hidden series
+├─ ChartFrame.Header         <div>; title column · actions
+│  ├─ ChartFrame.Title       <h3>; names the figure and the table
+│  ├─ ChartFrame.Description <p>; describes the figure
+│  └─ ChartFrame.Actions     <div>; period switch, export
+├─ ChartFrame.Value          <div>; headline number (Skeleton while loading)
+│  └─ ChartFrame.Delta       <span>; change with a tone
+├─ ChartFrame.Plot           <div>; fixed height, measured; Crossfade of plot / Skeleton / empty / error
+├─ ChartFrame.Legend         <ul>; a toggle button per series: swatch · name · value
+├─ ChartFrame.Table          <table>; visually hidden data, ready state only
+└─ ChartFrame.Tooltip        <div>; rendered by the chart library's tooltip hook, inside the Root
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ChartFrame.Root
+`ref` → `HTMLElement` (`<figure>`). The panel: a surface of the depth ladder, a figure named by `ChartFrame.Title` and described by `ChartFrame.Description`, `aria-busy` while loading. Owns the state, the series and which of them are hidden; every part reads them.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `state` | `"ready" \| "loading" \| "empty" \| "error"` | `"ready"` | What the chart region shows: the plot, Skeletons while `loading`, the empty state, or the load error with a retry (`onRetry`). Changes cross-fade at the same height. |
+| `series` | `ChartFrameSeries[]` | `[]` | The series in drawing order, `{ id, label, color?, value? }`: legend entries, tooltip rows, table columns and `renderPlot` colors. `color` is a palette hue; `value` is the legend summary. |
+| `hiddenSeries` | `string[]` | — | Ids of the series turned off in the legend (controlled). |
+| `defaultHiddenSeries` | `string[]` | `[]` | Initially hidden series (uncontrolled). |
+| `onHiddenSeriesChange` | `(hiddenSeries: string[]) => void` | — | The legend turned a series on or off; gets the new list of hidden ids. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the legend, the tooltip and the table («8,4 млн ₽»). |
+| `onRetry` | `() => void \| Promise<void>` | — | Loads the data again from the `error` state and shows the retry button; a returned Promise keeps the button loading until it settles. |
+| `labels` | `Partial<ChartFrameLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other figure attributes. |
+
+### ChartFrame.Header
+`ref` → `HTMLDivElement`. The top zone: title and description in the first column, `ChartFrame.Actions` at the end, under them when the panel is narrower than 24rem.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
+
+### ChartFrame.Title
+`ref` → `HTMLHeadingElement`. The name of the chart; names the figure and the data table.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level that fits the page outline; the look does not change. |
+| `…rest` | `HTMLAttributes<HTMLHeadingElement>` | — | `className` and the other heading attributes. |
+
+### ChartFrame.Description
+`ref` → `HTMLParagraphElement`. What the chart measures and over which period; describes the figure.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `className` and the other p attributes. |
+
+### ChartFrame.Actions
+`ref` → `HTMLDivElement`. Controls of the chart in the header: a period switch, an export button.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
+
+### ChartFrame.Value
+`ref` → `HTMLDivElement`. The headline number (heading-m, tabular) with an optional `ChartFrame.Delta` beside it; a Skeleton of its geometry while loading, a muted dash after a load error (the number is unknown).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
+
+### ChartFrame.Delta
+`ref` → `HTMLSpanElement`. The change of the headline value («+12% к сентябрю»); the sign is in the text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Color of the change: `success` — good, `danger` — bad; independent of the sign. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
+### ChartFrame.Plot
+`ref` → `HTMLDivElement`. The plot area of a fixed height that measures itself (ResizeObserver). Loading, empty and error cross-fade in its place. SVG text inside takes the caption type in the muted color; a mark with `data-hidden="true"` fades out.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `height` | `number` | `240, 160 under 30rem` | Height of the plot area in px. |
+| `renderPlot` | `(area: ChartFramePlotArea) => ReactNode` | — | Renders the chart at the measured `{ width, height }` with every series `{ id, label, color, hidden }` — for libraries that need explicit sizes (Chart.js, visx). |
+| `children` | `ReactNode` | — | A chart that sizes itself to its container (an SVG with a `viewBox`, `ResponsiveContainer`); it fills the area. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
+
+### ChartFrame.Legend
+`ref` → `HTMLUListElement`. The root's series as entries — swatch, name, summary value — each a toggle button that shows or hides its series. Renders nothing without series.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `readOnly` | `boolean` | `false` | Entries only name the series and do not toggle them. |
+| `…rest` | `HTMLAttributes<HTMLUListElement>` | — | `className` and the other ul attributes. |
+
+### ChartFrame.Tooltip
+`ref` → `HTMLDivElement`. The kit's tooltip body for a chart library's custom tooltip (Recharts `content`, visx `TooltipWithBounds`). The library positions it; render it inside `ChartFrame.Root`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | The point the rows belong to («Неделя 41»). |
+| `items` | `ChartFrameTooltipItem[]` | — (required) | `{ id, value }` per series at that point; name and color come from the root's series, rows of hidden series are left out, values go through `formatValue`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
+
+### ChartFrame.Table
+`ref` → `HTMLTableElement`. The chart's data as a visually hidden table for screen readers, named by the title: a row per point, a column per shown series. Present only in the `ready` state. A visible table is a `DataTable`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `rows` | `ChartFrameTableRow[]` | — (required) | `{ label, values }` per point; `values` by series id, a missing one reads as «—». |
+| `…rest` | `HTMLAttributes<HTMLTableElement>` | — | `className` and the other table attributes. |
+
+## Variants
+
+### Delta tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | secondary text | no judgement (no change, a reference figure) | yes |
+| `success` | success text | the change is good (revenue up, overdue down) | |
+| `warning` | warning text | the change needs attention | |
+| `danger` | danger text | the change is bad | |
+
+### Plot
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `renderPlot` | the chart drawn at the measured `{ width, height }`, called once the area has a size | the library needs explicit sizes, or the drawing computes positions in px | |
+| `children` | the chart stretched to the area | the chart sizes itself (an SVG with a `viewBox`, `ResponsiveContainer`) | |
+| `height` | the area's height in px | the chart needs more or less room than 240 px | 240, 160 under 30rem |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `Legend readOnly` | entries without hover or press | the series cannot be turned off (a stacked total that must add up) | `false` |
+
+### Colors
+- A series without `color` takes `chartColors.series[index]` by its place in `series`; past the eighth it is `chartColors.other`. Hiding a series never shifts the colors of the others.
+- `color` (a palette hue) maps to the same chart step as everywhere in the kit (`blue` → `chart-1`, `orange` → `chart-2` …, `gray` → `chart-other`), so a category matches its ProgressBar share; `sky` has no chart step and keeps its palette solid (too close to blue).
+- `renderPlot` gets each series with its `color` as a CSS value (`var(--prime-color-chart-*)`): pass it to the library as is; the theme switches with no re-render. Gridlines are `chartColors.grid`, the axis line `chartColors.axis`.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| ready | `state="ready"` | `data-state="ready"` on the root; the plot; the legend values; `ChartFrame.Table` present |
+| loading | `state="loading"` | `data-state="loading"` and `aria-busy` on the root; Skeletons of the value, the plot and the legend values; the title, actions and legend names stay |
+| empty | `state="empty"` | `data-state="empty"` on the root; EmptyPage `compact` (`role="status"`, `labels.empty`) in the plot's place |
+| error | `state="error"` | `data-state="error"` on the root; the value is a muted dash; EmptyPage `compact` `tone="danger"` (`role="alert"`, `labels.error`) with the retry button when `onRetry` is set; it waits for a returned Promise |
+| swap | `state` changes | the plot region cross-fades (Crossfade, the height stays); the value and legend values fade in from their Skeletons |
+| series hidden | a legend toggle, `hiddenSeries` | `aria-pressed="false"`, `data-hidden` on the entry: it keeps its place and color, the swatch becomes a ring, the name quiet; `renderPlot` gets `hidden: true` — a mark with `data-hidden="true"` fades out, the axes keep their scale |
+| hover / press | pointer on a legend entry | hover fill (hover-capable pointers only), press scale |
+
+## Layout & spacing
+- The root takes its container's width, card padding and radius, zones 16 px apart; on the page it carries the raised whisper, nested in a surface it is a flat tile one step deeper.
+- The header puts the title and the description in the first column and the actions at the end; under 24rem of panel width the actions drop under the description.
+- The plot is 240 px high (160 px under 30rem of panel width) unless `height` is set; it never changes height between states.
+- Legend entries wrap onto more lines; each has a 44 px touch hit area on coarse pointers.
+- `ChartFrame.Tooltip` is a floating panel with the point's label over rows of swatch · series name · value; the chart library positions it (Recharts `content`, visx `TooltipWithBounds`, a hand-drawn overlay).
+- SVG `<text>` in the plot takes the caption type in `--prime-color-text-muted`; a class of your own still wins.
+- Works from 320 px; the container queries are on the panel's own width, so it adapts in a grid cell as on a phone.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | The header actions, then the legend as one stop (the entry focused last), then the chart's own focusable marks. |
+| `←` · `→` · `↑` · `↓` | Previous or next legend entry, wrapping. |
+| `Home` · `End` | First or last legend entry. |
+| `Enter` · `Space` | Shows or hides the entry's series. |
+
+### ARIA
+- The root is a `<figure>` named by `ChartFrame.Title` and described by `ChartFrame.Description`; `aria-busy` while loading.
+- A legend entry is a button with `aria-pressed` — pressed while its series is shown; the legend list is named by `labels.legend`. A hidden series differs by the swatch's shape (a ring) and a quiet name, never by color alone.
+- `ChartFrame.Table` is a visually hidden table with the chart's data, named by the title: a row header per point, a column per shown series, values through `formatValue`.
+- The empty state is `role="status"`, the error `role="alert"` with the retry button.
+- The drawing is the library's: hide a decorative SVG (`aria-hidden`) when `ChartFrame.Table` carries the data; marks you make focusable need their own `aria-label`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `empty` | `"Нет данных за период"` | Title of the empty state. |
+| `error` | `"Не удалось загрузить график"` | Title of the error state. |
+| `retry` | `"Повторить"` | Text of the retry button in the error state. |
+| `legend` | `"Ряды графика"` | Accessible name of the legend. |
+| `category` | `"Период"` | Header of the first column of `ChartFrame.Table` (what a row is). |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Revenue by month as a hand-drawn SVG line chart in a dashboard panel: the headline with its change, a period switch, a legend that turns series off and a table for screen readers — `series`, `formatValue`, `renderPlot`. |
+| [tooltip.tsx](examples/tooltip.tsx) | Invoices by week as grouped bars: pointing at a week or stepping with the arrows shows the kit tooltip body with a row per series — `ChartFrame.Tooltip`, `items`. |
+| [states.tsx](examples/states.tsx) | Loading, empty, error and data swap in the plot's place without moving the panel; the error retries — `state`, `onRetry`. |
+| [controlled.tsx](examples/controlled.tsx) | Lead sources with totals in the legend; the hidden series live in the page state and one button shows them all again — `hiddenSeries`, `onHiddenSeriesChange`. |
+| [narrow.tsx](examples/narrow.tsx) | A 320px column: the actions drop under the title, the plot gets lower and a self-sizing SVG stretches to it — `children`, `height`. |
+
+### With a chart library
+```tsx
+// Recharts: explicit sizes from renderPlot, the kit tooltip body in `content`.
+<ChartFrame.Root series={SERIES} formatValue={formatRubles}>
+  <ChartFrame.Header>
+    <ChartFrame.Title>Выручка</ChartFrame.Title>
+  </ChartFrame.Header>
+  <ChartFrame.Plot
+    renderPlot={({ width, height, series }) => (
+      <LineChart width={width} height={height} data={rows}>
+        <CartesianGrid stroke={chartColors.grid} vertical={false} />
+        <XAxis dataKey="month" stroke={chartColors.axis} />
+        <YAxis stroke={chartColors.axis} />
+        <Tooltip
+          content={({ label, payload }) => (
+            <ChartFrame.Tooltip
+              label={label}
+              items={(payload ?? []).map((p) => ({ id: String(p.dataKey), value: Number(p.value) }))}
+            />
+          )}
+        />
+        {series.map((s) => (
+          <Line key={s.id} dataKey={s.id} stroke={s.color} hide={s.hidden} dot={false} />
+        ))}
+      </LineChart>
+    )}
+  />
+  <ChartFrame.Legend />
+  <ChartFrame.Table rows={tableRows} />
+</ChartFrame.Root>
+```
+ECharts and Chart.js take the same `width`, `height` and `series[i].color`; their HTML tooltips are strings, so use their own tooltip there or a React overlay with `ChartFrame.Tooltip`.
+
+## Mistakes
+- Colors picked per chart (`#3b82f6`) → `series[i].color` from `renderPlot`, or `chartColors`; status tones (`success`, `danger`) never paint categories.
+- Unmounting a hidden series → the line disappears in one frame; keep it with `data-hidden={hidden}` so it fades, or let the library animate it (`hide`).
+- A spinner or a grey box while the data loads → `state="loading"`.
+- An empty chart with axes and no data → `state="empty"`.
+- A legend for a single series → the title already names it; leave `ChartFrame.Legend` out.
+- Two y-axes of different measures in one frame → two ChartFrames side by side.
+- The data only in the drawing → add `ChartFrame.Table`; screen readers cannot read a plot.
+
+## Related
+- **Built from:** [Crossfade](../crossfade/COMPONENT.md) (state swap), [Skeleton](../skeleton/COMPONENT.md) (loading), [EmptyPage](../empty-page/COMPONENT.md) (empty, error, retry), `Icon`, `chartColors`
+- **See also:** [Sparkline](../sparkline/COMPONENT.md), [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/chart-frame/examples/controlled.tsx

@@ -0,0 +1,92 @@
+/** Lead sources with totals in the legend; the hidden series live in the page state and one button shows them all again — `hiddenSeries`, `onHiddenSeriesChange`. */
+import { Button, ChartFrame, type ChartFrameSeries, chartColors } from "prime-ui-kit";
+import * as React from "react";
+
+const MONTHS = ["май", "июн", "июл", "авг", "сен", "окт"];
+
+const LEADS: Record<string, number[]> = {
+  site: [120, 134, 128, 151, 166, 172],
+  partners: [64, 70, 81, 77, 92, 98],
+  ads: [88, 79, 95, 102, 86, 110],
+};
+
+const SERIES: ChartFrameSeries[] = [
+  { id: "site", label: "Сайт", value: 871 },
+  { id: "partners", label: "Партнёры", value: 482 },
+  { id: "ads", label: "Реклама", value: 560 },
+];
+
+const MARGIN = { top: 8, right: 16, bottom: 24, left: 32 };
+const TOP = 200;
+
+export default function ChartFrameControlledExample() {
+  const [hidden, setHidden] = React.useState<string[]>(["ads"]);
+
+  return (
+    <ChartFrame.Root series={SERIES} hiddenSeries={hidden} onHiddenSeriesChange={setHidden}>
+      <ChartFrame.Header>
+        <ChartFrame.Title>Лиды по источникам</ChartFrame.Title>
+        <ChartFrame.Description>Май — октябрь</ChartFrame.Description>
+        <ChartFrame.Actions>
+          <Button.Root
+            variant="ghost"
+            tone="neutral"
+            disabled={hidden.length === 0}
+            onClick={() => setHidden([])}
+          >
+            Показать все
+          </Button.Root>
+        </ChartFrame.Actions>
+      </ChartFrame.Header>
+      <ChartFrame.Plot
+        renderPlot={({ width, height, series }) => {
+          const innerW = width - MARGIN.left - MARGIN.right;
+          const innerH = height - MARGIN.top - MARGIN.bottom;
+          const x = (i: number) => MARGIN.left + (innerW * i) / (MONTHS.length - 1);
+          const y = (v: number) => MARGIN.top + innerH * (1 - v / TOP);
+          return (
+            <svg width={width} height={height} aria-hidden="true">
+              {[0, 100, 200].map((tick) => (
+                <g key={tick}>
+                  <line
+                    x1={MARGIN.left}
+                    x2={width - MARGIN.right}
+                    y1={y(tick)}
+                    y2={y(tick)}
+                    stroke={tick === 0 ? chartColors.axis : chartColors.grid}
+                  />
+                  <text x={MARGIN.left - 8} y={y(tick)} textAnchor="end" dominantBaseline="middle">
+                    {tick}
+                  </text>
+                </g>
+              ))}
+              {MONTHS.map((month, i) => (
+                <text key={month} x={x(i)} y={height - 4} textAnchor="middle">
+                  {month}
+                </text>
+              ))}
+              {series.map((s) => (
+                <path
+                  key={s.id}
+                  data-hidden={s.hidden}
+                  d={LEADS[s.id].map((v, i) => `${i ? "L" : "M"}${x(i)},${y(v)}`).join("")}
+                  fill="none"
+                  stroke={s.color}
+                  strokeWidth={2}
+                  strokeLinejoin="round"
+                />
+              ))}
+            </svg>
+          );
+        }}
+      />
+      <ChartFrame.Legend />
+      <ChartFrame.Table
+        rows={MONTHS.map((month, i) => ({
+          label: month,
+          values: { site: LEADS.site[i], partners: LEADS.partners[i], ads: LEADS.ads[i] },
+        }))}
+      />
+    </ChartFrame.Root>
+  );
+}

package/src/components/chart-frame/examples/examples.module.css

@@ -0,0 +1,6 @@
+/* Layout of the ChartFrame scenarios: semantic tokens only. */
+
+/* The narrowest supported column: a phone, or a side panel of a dashboard. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+}

package/src/components/chart-frame/examples/narrow.tsx

@@ -0,0 +1,46 @@
+/** A 320px column: the actions drop under the title, the plot gets lower and a self-sizing SVG stretches to it — `children`, `height`. */
+import { Button, ChartFrame, chartColors, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const MRR = [6.1, 6.3, 6.2, 6.6, 6.9, 7.0, 7.4, 7.3, 7.8, 8.1, 8.0, 8.4];
+
+const LINE = MRR.map(
+  (v, i) => `${i ? "L" : "M"}${(i / (MRR.length - 1)) * 100},${(9 - v) * 25}`,
+).join("");
+
+export default function ChartFrameNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <ChartFrame.Root>
+        <ChartFrame.Header>
+          <ChartFrame.Title>Регулярная выручка</ChartFrame.Title>
+          <ChartFrame.Description>За 12 месяцев</ChartFrame.Description>
+          <ChartFrame.Actions>
+            <Button.Root variant="soft" tone="neutral">
+              <Button.Icon>
+                <Icon name="action.download" />
+              </Button.Icon>
+              CSV
+            </Button.Root>
+          </ChartFrame.Actions>
+        </ChartFrame.Header>
+        <ChartFrame.Value>
+          8,4 млн ₽<ChartFrame.Delta tone="success">+38% за год</ChartFrame.Delta>
+        </ChartFrame.Value>
+        <ChartFrame.Plot height={120}>
+          <svg viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
+            <path d={`${LINE}L100,100L0,100Z`} fill={chartColors.series[0]} fillOpacity={0.1} />
+            <path
+              d={LINE}
+              fill="none"
+              stroke={chartColors.series[0]}
+              strokeWidth={2}
+              vectorEffect="non-scaling-stroke"
+            />
+          </svg>
+        </ChartFrame.Plot>
+      </ChartFrame.Root>
+    </div>
+  );
+}