prime-ui-kit 0.10.0 → 0.11.1

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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>
+  );
+}

package/dist/skill/reference/components/chart-frame/examples/overview.tsx

@@ -0,0 +1,127 @@
+/** 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`. */
+import { ChartFrame, type ChartFrameSeries, chartColors, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+type Point = { month: string; values: Record<string, number> };
+
+const SERIES: ChartFrameSeries[] = [
+  { id: "new", label: "Новые клиенты" },
+  { id: "renewals", label: "Продления" },
+];
+
+const YEAR: Point[] = [
+  { month: "ноя", values: { new: 1.9, renewals: 3.1 } },
+  { month: "дек", values: { new: 2.4, renewals: 3.4 } },
+  { month: "янв", values: { new: 1.6, renewals: 3.0 } },
+  { month: "фев", values: { new: 2.1, renewals: 3.3 } },
+  { month: "мар", values: { new: 2.8, renewals: 3.5 } },
+  { month: "апр", values: { new: 2.6, renewals: 3.8 } },
+  { month: "мая", values: { new: 3.0, renewals: 3.6 } },
+  { month: "июн", values: { new: 3.4, renewals: 4.0 } },
+  { month: "июл", values: { new: 3.1, renewals: 4.2 } },
+  { month: "авг", values: { new: 3.6, renewals: 4.1 } },
+  { month: "сен", values: { new: 3.9, renewals: 4.4 } },
+  { month: "окт", values: { new: 4.2, renewals: 4.6 } },
+];
+
+const PERIODS = { half: YEAR.slice(6), year: YEAR };
+
+const MARGIN = { top: 8, right: 16, bottom: 24, left: 40 };
+
+const formatMillions = (value: number) => `${value.toLocaleString("ru-RU")} млн ₽`;
+
+/** Round gridline steps from 0 to just above the largest value. */
+function ticks(max: number): number[] {
+  const step = max > 6 ? 2 : 1;
+  return Array.from({ length: Math.ceil(max / step) + 1 }, (_, i) => i * step);
+}
+
+export default function ChartFrameOverviewExample() {
+  const [period, setPeriod] = React.useState<keyof typeof PERIODS>("year");
+  const points = PERIODS[period];
+  const last = points[points.length - 1];
+  const total = last.values.new + last.values.renewals;
+
+  return (
+    <ChartFrame.Root series={SERIES} formatValue={formatMillions}>
+      <ChartFrame.Header>
+        <ChartFrame.Title>Выручка</ChartFrame.Title>
+        <ChartFrame.Description>По месяцам, в млн ₽</ChartFrame.Description>
+        <ChartFrame.Actions>
+          <SegmentedControl.Root
+            aria-label="Период"
+            value={period}
+            onValueChange={(next) => setPeriod(next as keyof typeof PERIODS)}
+          >
+            <SegmentedControl.Item value="half">6 мес</SegmentedControl.Item>
+            <SegmentedControl.Item value="year">Год</SegmentedControl.Item>
+          </SegmentedControl.Root>
+        </ChartFrame.Actions>
+      </ChartFrame.Header>
+      <ChartFrame.Value>
+        {formatMillions(Math.round(total * 10) / 10)}
+        <ChartFrame.Delta tone="success">+8% к сентябрю</ChartFrame.Delta>
+      </ChartFrame.Value>
+      <ChartFrame.Plot
+        renderPlot={({ width, height, series }) => {
+          const grid = ticks(Math.max(...points.flatMap((p) => Object.values(p.values))));
+          const top = grid[grid.length - 1];
+          const innerW = width - MARGIN.left - MARGIN.right;
+          const innerH = height - MARGIN.top - MARGIN.bottom;
+          const x = (i: number) => MARGIN.left + (innerW * i) / Math.max(points.length - 1, 1);
+          const y = (v: number) => MARGIN.top + innerH * (1 - v / top);
+          const labelStep = Math.ceil(points.length / Math.max(1, Math.floor(innerW / 44)));
+          return (
+            <svg width={width} height={height} aria-hidden="true">
+              {grid.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>
+              ))}
+              {points.map((point, i) =>
+                // A narrow plot labels every second or third month, so the labels never collide.
+                i % labelStep === 0 ? (
+                  <text key={point.month} x={x(i)} y={height - 4} textAnchor="middle">
+                    {point.month}
+                  </text>
+                ) : null,
+              )}
+              {series.map((s) => {
+                const line = points
+                  .map((p, i) => `${i ? "L" : "M"}${x(i)},${y(p.values[s.id])}`)
+                  .join("");
+                return (
+                  <g key={s.id} data-hidden={s.hidden}>
+                    <path
+                      d={`${line}L${x(points.length - 1)},${y(0)}L${x(0)},${y(0)}Z`}
+                      fill={s.color}
+                      fillOpacity={0.08}
+                    />
+                    <path
+                      d={line}
+                      fill="none"
+                      stroke={s.color}
+                      strokeWidth={2}
+                      strokeLinejoin="round"
+                    />
+                  </g>
+                );
+              })}
+            </svg>
+          );
+        }}
+      />
+      <ChartFrame.Legend />
+      <ChartFrame.Table rows={points.map((p) => ({ label: p.month, values: p.values }))} />
+    </ChartFrame.Root>
+  );
+}

package/dist/skill/reference/components/chart-frame/examples/states.tsx

@@ -0,0 +1,78 @@
+/** Loading, empty, error and data swap in the plot's place without moving the panel; the error retries — `state`, `onRetry`. */
+import {
+  ChartFrame,
+  type ChartFrameSeries,
+  type ChartFrameState,
+  chartColors,
+  SegmentedControl,
+} from "prime-ui-kit";
+import * as React from "react";
+
+const SERIES: ChartFrameSeries[] = [{ id: "orders", label: "Заказы" }];
+
+const DAYS = [132, 158, 141, 176, 190, 164, 203, 188, 214, 197];
+
+const formatOrders = (value: number) => value.toLocaleString("ru-RU");
+
+export default function ChartFrameStatesExample() {
+  const [state, setState] = React.useState<ChartFrameState>("loading");
+
+  return (
+    <>
+      <SegmentedControl.Root
+        aria-label="Состояние"
+        value={state}
+        onValueChange={(next) => setState(next as ChartFrameState)}
+      >
+        <SegmentedControl.Item value="loading">Загрузка</SegmentedControl.Item>
+        <SegmentedControl.Item value="ready">Данные</SegmentedControl.Item>
+        <SegmentedControl.Item value="empty">Пусто</SegmentedControl.Item>
+        <SegmentedControl.Item value="error">Ошибка</SegmentedControl.Item>
+      </SegmentedControl.Root>
+      <ChartFrame.Root
+        state={state}
+        series={SERIES}
+        formatValue={formatOrders}
+        onRetry={() =>
+          new Promise<void>((resolve) => {
+            window.setTimeout(() => {
+              setState("ready");
+              resolve();
+            }, 900);
+          })
+        }
+      >
+        <ChartFrame.Header>
+          <ChartFrame.Title>Заказы за 10 дней</ChartFrame.Title>
+        </ChartFrame.Header>
+        <ChartFrame.Value>
+          1 284
+          <ChartFrame.Delta tone="success">+14%</ChartFrame.Delta>
+        </ChartFrame.Value>
+        <ChartFrame.Plot
+          renderPlot={({ width, height, series }) => {
+            const band = width / DAYS.length;
+            const max = Math.max(...DAYS);
+            return (
+              <svg width={width} height={height} aria-hidden="true">
+                <line x1={0} x2={width} y1={height} y2={height} stroke={chartColors.axis} />
+                {DAYS.map((value, i) => (
+                  <rect
+                    // biome-ignore lint/suspicious/noArrayIndexKey: one bar per day, in order
+                    key={i}
+                    x={band * i + 4}
+                    y={height - (height * value) / max}
+                    width={band - 8}
+                    height={(height * value) / max}
+                    rx={2}
+                    fill={series[0].color}
+                  />
+                ))}
+              </svg>
+            );
+          }}
+        />
+      </ChartFrame.Root>
+    </>
+  );
+}