prime-ui-kit 0.13.0 → 0.14.0

package/src/components/sparkline/COMPONENT.md

@@ -3,14 +3,17 @@
 **Category:** data-display
 **Kind:** primitive
 
-> A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed.
+> A small chart — a smooth line over a fading area, a bare line or bars — with its headline: the value at rest, its change and its date; any point can be scrubbed.
 
 ## When to use
 - A metric card on a dashboard: revenue, orders, sign-ups over the last days or weeks.
 - A trend next to a number where the shape matters more than exact axes.
 - Values with a sign by period — profit, net new customers (`variant="bars"`: up when positive, down when negative), with the current period highlighted (`highlight`).
 - A detail page header that shows how a value moved.
-- A trend per record in a table cell or a list row (`layout="compact"`): revenue by month per client.
+- A trend per record in a table cell or a list row (`layout="compact"`): revenue by month per client; one scale for the whole column with `min` / `max`.
+- A daily flow over a period — revenue, orders, sign-ups (`summary="sum"`, `compareTo` the previous period).
+- A metric against its plan or average (`reference`), or its change over the whole period (`change="first"`).
+- A series with missing days — a collector that was down (`value: null` breaks the line).
 
 ## When not to use
 - Exact values on axes, several series, or a legend → a full chart library on the kit's chart palette (`chartColors`); Sparkline has no axes.
@@ -28,10 +31,13 @@ import { Sparkline, type SparklinePoint } from "prime-ui-kit";
 Sparkline              <div>; the headline and the chart; aria-busy while loading
 ├─ head                title (label) · date of the shown point
 ├─ value row           value (rolling digits when settled) · change Badge with the trend arrow
-└─ plot                role="slider" over the chart
-   ├─ line:            svg line and area + cursor (guide line and dot, aria-hidden)
-   └─ bars:            zero line (chart axis) + a slot per point with its bar (aria-hidden)
+├─ plot                role="slider" over the chart
+│  ├─ reference        dashed line at `reference` (aria-hidden)
+│  ├─ area · line:     svg gradient area and monotone line, lone points as dots + cursor (guide and dot, aria-hidden)
+│  └─ bars:            zero line (chart axis) + a slot per point with its bar (aria-hidden)
+└─ reference text      hidden; describes the slider (aria-describedby)
 loading:               Skeletons of the date, the value line and the plot
+tooltip:               the kit chart tooltip (date · value) right of the pointer, portaled to <body>, aria-hidden
 compact:               the plot alone (no head, no value row); loading — the plot Skeleton
 ```
 
@@ -40,17 +46,24 @@ compact:               the plot alone (no head, no value row); loading — the p
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Sparkline
-`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line or bar chart; the chart is a `role="slider"` that picks a point. The change hides when a percentage means nothing (the previous value is 0 or the sign flips).
+`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over an area, line or bar chart; the chart is a `role="slider"` that picks a point, a tooltip beside the pointer shows the value and date. The change hides when a percentage means nothing.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»). Two or more draw a line. A new array cross-fades the line in. |
+| `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»), `value: null` is a point with no data — the line breaks, the bar is absent. A new array cross-fades the chart in. |
 | `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart; with `layout="compact"` only the accessible name. |
-| `layout` | `"default" \| "compact"` | `"default"` | `default` — the headline over an 80 px plot; `compact` — the plot alone at an `xs` control height with the dot at rest, for a DataTable cell; the point stays in `aria-valuetext`. |
-| `variant` | `"line" \| "bars"` | `"line"` | `line` — a line over a soft area; `bars` — a bar per point standing on a zero line: up when positive, down (danger) when negative, the value end rounded. |
-| `highlight` | `number` | `the latest point` | Index of the point at rest (the current month): the headline shows it when nobody scrubs and leaving the chart returns to it; `bars` draw the other bars quieter. |
+| `variant` | `"area" \| "line" \| "bars"` | `"area"` | `area` — a line over an accent gradient that fades to the bottom; `line` — the line alone, for many trends side by side; `bars` — a bar per point standing on a zero line: up when positive, down (danger) when negative. |
+| `curve` | `"smooth" \| "linear" \| "step"` | `"smooth"` | Shape of the line (`area`, `line`): `smooth` — a monotone cubic through every point that never overshoots a peak or a trough; `linear` — straight segments; `step` — a level per point, changing halfway between points. |
+| `layout` | `"default" \| "compact"` | `"default"` | `default` — the headline over an 80 px plot; `compact` — the plot alone at an `xs` control height with the dot at rest, for a DataTable cell; the scrubbed point shows in the tooltip and `aria-valuetext`. |
+| `change` | `"previous" \| "first" \| "none"` | `"previous"` | What the change badge of a shown point compares it with: `previous` — the point before it; `first` — the first point with a value (the change over the period); `none` — no badge. |
+| `summary` | `"latest" \| "sum" \| "average"` | `"latest"` | What the headline shows at rest: `latest` — the latest point (or `highlight`), for a level (MRR, conversion); `sum` — the period total, for a flow (revenue per day); `average` — the period mean. |
+| `highlight` | `number` | `the latest point with a value` | Index of the point at rest with `summary="latest"` (the current month): the headline returns to it; `bars` draw the other bars quieter. Not allowed with `sum` / `average`. |
+| `compareTo` | `number` | — | The same summary for the previous period («прошлые 30 дней»): the badge at rest compares the headline with it. Without it a `sum` / `average` headline shows no change at rest. |
+| `min` | `number` | — | The value axis reaches down to at least this value: a floor of zero, or one scale for several sparklines (a table column). Data below widens the scale, never gets cut. |
+| `max` | `number` | — | The value axis reaches up to at least this value; data above widens the scale. |
+| `reference` | `number` | — | A dashed horizontal line at this value — a plan, a target, an average; the scale holds it and the chart is described by `labels.reference`. |
 | `loading` | `boolean` | `false` | The series is on its way: Skeletons of the date, the value and the plot that cross-fade into the data; the title stays, the root is `aria-busy` and the chart is not focusable yet. |
-| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the headline and the spoken point («312 400 ₽»). |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the headline, the tooltip, the reference description and the spoken point («312 400 ₽»). |
 | `labels` | `Partial<SparklineLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
 
@@ -59,19 +72,45 @@ compact:               the plot alone (no head, no value row); loading — the p
 ### variant
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `line` | an accent line over a soft area, a dot on the shown point | a continuous trend (daily revenue) | yes |
+| `area` | an accent line over a gradient that fades to the bottom, a dot on the shown point | a continuous trend in a tile (daily revenue) | yes |
+| `line` | the accent line alone, a dot on the shown point | many trends side by side, a quiet trend in a dense list | |
 | `bars` | a bar per point from a zero line (`--prime-color-chart-axis`): accent up, danger down, value end rounded | values by period, especially with a sign (monthly profit) | |
 
+### curve
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `smooth` | a monotone cubic through every point: round, never above a peak or below a trough | most trends | yes |
+| `linear` | straight segments between points | few points where each turn matters | |
+| `step` | a level per point, changing halfway between points | values that hold for a period (a price, a plan, a headcount) | |
+
+### change
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `previous` | change against the point before the shown one | period-over-period (this month vs the last) | yes |
+| `first` | change against the first point with a value | the change over the whole range («за полгода») | |
+| `none` | no badge | a percentage means nothing (a rate near zero, a count of events) | |
+
+### summary
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `latest` | the latest point (or `highlight`) at rest, its date, the dot on it | a level: MRR, a balance, a price, a conversion rate | yes |
+| `sum` | the period total at rest, the period as its date («9 сен – 8 окт»), no dot | a flow: revenue, orders, sign-ups per day | |
+| `average` | the period mean at rest, the period as its date, no dot | a rate over the period: average check, response time | |
+
+Scrubbing always shows the point under the pointer; leaving returns to the summary. With `compareTo` (the same summary for the previous period) the badge at rest is the change against it — «+8% к прошлым 30 дням».
+
 ### layout
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `default` | the headline (title · date, value · change) over an 80 px plot | a dashboard tile, a page header | yes |
-| `compact` | the plot alone at the height of an `xs` control (28 px), the dot on the point at rest, the guide line only while scrubbing; at least 96 px wide | a DataTable cell or a list row: one trend per record next to its name or total | |
+| `compact` | the plot alone at the height of an `xs` control (28 px), the dot on the point at rest; scrubbing shows the guide and the tooltip; at least 96 px wide | a DataTable cell or a list row: one trend per record next to its name or total | |
 
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `highlight` | the headline rests on that point; in `bars` the other bars are quieter | the current period is not the last point (a year with empty months ahead) | the latest point |
+| `min` · `max` | the scale spans at least this range; data outside widens it | one scale for a table column, a floor of zero | the data's own range |
+| `reference` | a dashed chart-axis line at the value | a plan, a target, an average | — |
 | `loading` | Skeletons of the date, the value and the plot | the series is on its way | `false` |
 
 Put it in a `Card` for a dashboard tile.
@@ -79,21 +118,23 @@ Put it in a `Card` for a dashboard tile.
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| at rest | — | the latest point or `highlight`; the value rolls its digits when `data` changes |
-| scrubbing | pointer, touch or the arrow keys | `data-scrubbing` on the root; the cursor (or the bar under the pointer) and the headline follow with no easing (direct manipulation), digits change in place |
+| at rest | `summary`, `highlight`, `compareTo` | the latest point or `highlight` (`latest`), or the period total / mean with the period as date and no dot (`sum` / `average`, cursor `data-hidden`); the badge compares with `compareTo` when given; the value rolls its digits when `data` changes or scrubbing ends |
+| scrubbing | pointer, touch or the arrow keys | `data-scrubbing` on the root; the guide and the tooltip (`data-state="open"`, date · value, right of the pointer at its height, left of it only where the right has no room in the viewport; from the keyboard beside the point at mid-height) fade in (`fast`), the cursor (or the bar under the pointer) and the headline follow with no easing (direct manipulation), digits change in place |
 | keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`, `data-scrubbing`; the cursor moves to the point at once (keyboard steps are high-frequency); in `bars` the current bar keeps its fill, the others go quiet (`fast` opacity) |
-| settle | pointer leaves, touch ends, focus leaves | back to the point at rest |
-| change hidden | the first point, the previous value is 0, or the sign flips | no change Badge: a percentage would mean nothing |
+| settle | pointer leaves, touch ends, focus leaves | back to the point at rest; the tooltip fades out (`fast`) |
+| change hidden | `change="none"`, nothing to compare with, a missing value, a base of 0, or a sign flip | no change Badge: a percentage would mean nothing |
+| no data | a point with `value: null` | the line breaks (a point alone between gaps is a dot), no bar; shown, the value reads `labels.empty` (`data-empty`, muted) and the dot fades out, the guide marks the point |
 | new series | a new `data` array | the chart cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
-| compact | `layout="compact"` | `data-layout="compact"` on the root; no headline: `label` names the slider, the point is spoken through `aria-valuetext`; the guide fades in while scrubbing (`fast`) |
+| compact | `layout="compact"` | `data-layout="compact"` on the root; no headline: `label` names the slider, the point is spoken through `aria-valuetext` and shown in the tooltip |
 | loading | `loading` | `aria-busy` on the root; Skeletons in place of the date, the value and the plot; no slider until the data comes; the data cross-fades in |
 
 ## Layout & spacing
-- Takes the width of its container; the plot is 80 px high and inset by the dot radius so the cursor is never clipped.
+- Takes the width of its container; the plot is 80 px high and inset by the dot radius so the cursor is never clipped. The smooth curve never leaves the plot: a monotone cubic does not overshoot the extremes.
 - Bars share the width equally, 4 px apart; the zero line sits where 0 falls on the scale (the bottom when every value is positive).
 - In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
 - When the value row does not fit (a narrow card), the change badge wraps under the value.
-- `layout="compact"` fits a DataTable row of any tier (plot and dot within an `xs` control height) and takes the cell width, at least `--prime-space-24`; give the column a `width` for an even plot per row. Put the number next to it in its own column: the compact plot shows no value.
+- `layout="compact"` fits a DataTable row of any tier (plot and dot within an `xs` control height) and takes the cell width, at least `--prime-space-24`; give the column a `width` for an even plot per row. Put the number next to it in its own column: the compact plot shows a value only in its tooltip while scrubbed.
+- The tooltip is the kit's chart tooltip, placed like every anchored layer (`usePosition`): right of the pointer at its height, on the left only where the right has no room in the viewport — crossing the middle never moves it; from the keyboard right of the point at mid-height. Portaled, so a card or a table scroller never clips it.
 
 ## Accessibility
 
@@ -102,14 +143,16 @@ Put it in a `Card` for a dashboard tile.
 |---|---|
 | `←` · `→` · `↓` · `↑` | Previous or next point: `←` / `↓` back, `→` / `↑` forward, as on a slider. |
 | `Home` · `End` | First or last point. |
-| `Tab` | Focuses the chart; leaving focus returns to the point at rest (the latest or `highlight`). |
+| `Tab` | Focuses the chart; leaving focus returns the headline to rest (`summary`, `highlight`). |
+| `Escape` | Hides the tooltip and returns the headline to rest. |
 
 ### ARIA
-- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`). The headline is the tooltip of the chart: the value of the point under the pointer or the arrows, in text.
+- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`); a point with no data speaks `labels.empty` («8 окт: Нет данных»). At rest with `sum` / `average` it speaks the period and the summary («9 сен – 8 окт: 8 914 000 ₽»). With `reference` the slider is described by `labels.reference` («Ориентир: 3%», `aria-describedby`). The headline follows the point under the pointer or the arrows, in text.
 - The headline with the value and change reads as plain text.
 - The change carries a sign and an arrow, never color alone; a negative bar goes down, not only red.
 - While `loading` the root is `aria-busy` and the chart is not in the tab order yet.
-- `layout="compact"`: no visible title; `label` is only the slider's name, the point still goes to `aria-valuetext`. The plot carries `data-row-click-ignore` (and is a slider), so its pointer and keys never open a DataTable row.
+- `layout="compact"`: no visible title; `label` is only the slider's name, the point still goes to `aria-valuetext`.
+- The tooltip is `aria-hidden`: it repeats `aria-valuetext` for sighted users. The plot carries `data-row-click-ignore` (and is a slider), so its pointer and keys never open a DataTable row.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -117,25 +160,35 @@ Put it in a `Card` for a dashboard tile.
 | Key | Default | Used for |
 |---|---|---|
 | `point` | `"{label}: {value}"` | Spoken value of the chosen point (`aria-valuetext`); `{label}` and `{value}` are replaced. |
+| `period` | `"{first} – {last}"` | The date line of a `sum` / `average` headline at rest; `{first}` and `{last}` are the labels of the first and the last point. |
+| `empty` | `"Нет данных"` | Shown and spoken in place of the value of a point with `value: null`. |
+| `reference` | `"Ориентир: {value}"` | Description of the chart with a `reference` line (`aria-describedby`); `{value}` is replaced. |
 
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. |
-| [variants.tsx](examples/variants.tsx) | The same week as a line and as bars from zero — `variant`. |
+| [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: at rest the total for the period against the previous 30 days, drag across the chart to see a day — `data`, `label`, `summary`, `compareTo`, `formatValue`. |
+| [variants.tsx](examples/variants.tsx) | The same week as an area, a bare line and bars from zero — `variant`. |
 | [states.tsx](examples/states.tsx) | While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. |
-| [compact.tsx](examples/compact.tsx) | Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, the label is the chart's accessible name — `layout`, `label`. |
+| [compact.tsx](examples/compact.tsx) | Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, scrubbing shows the month in a tooltip, the label is the chart's accessible name — `layout`, `label`. |
 | [signed-bars.tsx](examples/signed-bars.tsx) | Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. |
-| [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. |
+| [curve.tsx](examples/curve.tsx) | The same month of active users as a smooth curve, straight segments and steps — `curve`. |
+| [reference.tsx](examples/reference.tsx) | Checkout conversion against its plan: a dashed reference line, the scale from zero and the change over the whole period — `reference`, `min`, `change`. |
+| [gaps.tsx](examples/gaps.tsx) | Daily API requests with days the collector was down: the line breaks over a missing day and the headline says there is no data — `data`, `labels`. |
+| [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`, `summary`. |
 
 ## Mistakes
 - A new array on every render (`data={rows.map(...)}` inline) → the line cross-fades on every render; memoize the series.
 - Formatting inside `label` of a point («312 400 ₽») → the point label is its name («8 окт»); format values with `formatValue`.
 - A Sparkline without a container width (inside an inline flex row) → give it a width or put it in a `Card`.
-- A separate tooltip over the bars → the headline already shows the scrubbed point; a floating tooltip would cover the next bar.
+- A Tooltip or a chart library tooltip wrapped around the chart → Sparkline draws its own beside the pointer.
+- A daily flow (revenue per day) with the latest day in the headline → `summary="sum"`: the card is about the period; pass `compareTo` for its change.
+- A missing day as `0` → the line dives to zero; pass `value: null`, the line breaks and the headline says there is no data.
+- Compact sparklines in a column, each on its own scale, when rows must be compared by size → pass the column's `min` / `max` to every row.
+- A plan drawn as a second series → `reference`.
 - A grey box while the series loads → `loading`.
 - A full Sparkline squeezed into a table cell, or its headline hidden with CSS → `layout="compact"`.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow)
-- **See also:** [DataTable](../data-table/COMPONENT.md) (a compact Sparkline per row), [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)
+- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow), `ChartTooltip` (the chart tooltip shared with ChartFrame)
+- **See also:** [ChartFrame](../chart-frame/COMPONENT.md), [DataTable](../data-table/COMPONENT.md) (a compact Sparkline per row), [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/sparkline/examples/compact.tsx

@@ -1,4 +1,4 @@
-/** Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, the label is the chart's accessible name — `layout`, `label`. */
+/** Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, scrubbing shows the month in a tooltip, the label is the chart's accessible name — `layout`, `label`. */
 import { Card, Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/sparkline/examples/curve.tsx

@@ -0,0 +1,28 @@
+/** The same month of active users as a smooth curve, straight segments and steps — `curve`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const USERS: SparklinePoint[] = [
+  { label: "сен, 1 нед.", value: 1240 },
+  { label: "сен, 2 нед.", value: 1380 },
+  { label: "сен, 3 нед.", value: 1310 },
+  { label: "сен, 4 нед.", value: 1620 },
+  { label: "окт, 1 нед.", value: 1590 },
+  { label: "окт, 2 нед.", value: 1840 },
+];
+
+const CURVES = ["smooth", "linear", "step"] as const;
+
+export default function SparklineCurveExample() {
+  return (
+    <div>
+      {CURVES.map((curve) => (
+        <div key={curve}>
+          <Sparkline data={USERS} label="Активные пользователи" curve={curve} />
+          <Typography as="span" variant="caption" tone="muted">
+            {curve}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/sparkline/examples/gaps.tsx

@@ -0,0 +1,33 @@
+/** Daily API requests with days the collector was down: the line breaks over a missing day and the headline says there is no data — `data`, `labels`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const REQUESTS: SparklinePoint[] = [
+  { label: "29 сен", value: 182_400 },
+  { label: "30 сен", value: 191_800 },
+  { label: "1 окт", value: 176_300 },
+  { label: "2 окт", value: null },
+  { label: "3 окт", value: 168_900 },
+  { label: "4 окт", value: 203_500 },
+  { label: "5 окт", value: 214_100 },
+  { label: "6 окт", value: null },
+  { label: "7 окт", value: null },
+  { label: "8 окт", value: 226_700 },
+  { label: "9 окт", value: 219_200 },
+  { label: "10 окт", value: 238_600 },
+];
+
+export default function SparklineGapsExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline
+          data={REQUESTS}
+          label="Запросы к API в день"
+          labels={{ empty: "Сборщик не работал" }}
+        />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/sparkline/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. */
+/** Revenue for 30 days in a dashboard card: at rest the total for the period against the previous 30 days, drag across the chart to see a day — `data`, `label`, `summary`, `compareTo`, `formatValue`. */
 import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -14,13 +14,22 @@ const REVENUE: SparklinePoint[] = Array.from({ length: 30 }, (_, i) => {
   };
 });
 
+/** Revenue for the 30 days before, 10 August — 8 September 2026. */
+const PREVIOUS_TOTAL = 8_240_000;
+
 const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
 
 export default function SparklineOverviewExample() {
   return (
     <Card.Root className={styles.card}>
       <Card.Body>
-        <Sparkline data={REVENUE} label="Выручка за 30 дней" formatValue={formatRubles} />
+        <Sparkline
+          data={REVENUE}
+          label="Выручка за 30 дней"
+          summary="sum"
+          compareTo={PREVIOUS_TOTAL}
+          formatValue={formatRubles}
+        />
       </Card.Body>
     </Card.Root>
   );

package/src/components/sparkline/examples/period.tsx

@@ -1,4 +1,4 @@
-/** Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. */
+/** Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`, `summary`. */
 import { Card, SegmentedControl, Sparkline, type SparklinePoint } from "prime-ui-kit";
 import * as React from "react";
 
@@ -39,7 +39,12 @@ export default function SparklinePeriodExample() {
           <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
           <SegmentedControl.Item value="quarter">Квартал</SegmentedControl.Item>
         </SegmentedControl.Root>
-        <Sparkline data={SERIES[period]} label="Новые заказы" formatValue={formatRubles} />
+        <Sparkline
+          data={SERIES[period]}
+          label="Новые заказы"
+          summary="sum"
+          formatValue={formatRubles}
+        />
       </Card.Body>
     </Card.Root>
   );

package/src/components/sparkline/examples/reference.tsx

@@ -0,0 +1,37 @@
+/** Checkout conversion against its plan: a dashed reference line, the scale from zero and the change over the whole period — `reference`, `min`, `change`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const CONVERSION: SparklinePoint[] = [
+  { label: "май", value: 2.1 },
+  { label: "июн", value: 2.4 },
+  { label: "июл", value: 2.2 },
+  { label: "авг", value: 2.8 },
+  { label: "сен", value: 3.1 },
+  { label: "окт", value: 3.4 },
+];
+
+const PLAN = 3;
+
+const PERCENT = new Intl.NumberFormat("ru-RU", { maximumFractionDigits: 1 });
+
+const formatPercent = (value: number) => `${PERCENT.format(value)}%`;
+
+export default function SparklineReferenceExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline
+          data={CONVERSION}
+          label="Конверсия оформления заказа"
+          reference={PLAN}
+          min={0}
+          change="first"
+          formatValue={formatPercent}
+          labels={{ reference: "План: {value}" }}
+        />
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -1,4 +1,4 @@
-/** The same week as a line and as bars from zero — `variant`. */
+/** The same week as an area, a bare line and bars from zero — `variant`. */
 import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
 
 const ORDERS: SparklinePoint[] = [
@@ -11,7 +11,7 @@ const ORDERS: SparklinePoint[] = [
   { label: "8 окт", value: 52 },
 ];
 
-const VARIANTS = ["line", "bars"] as const;
+const VARIANTS = ["area", "line", "bars"] as const;
 
 export default function SparklineVariantsExample() {
   return (

package/src/components/tabs/examples/examples.module.css

@@ -22,12 +22,6 @@
   max-width: calc(10 * var(--prime-control-m-height));
 }
 
-/* in-drawer.tsx: blocks of a panel in the drawer body, the full body width. */
-.stack {
-  display: grid;
-  gap: var(--prime-space-5);
-}
-
 /* The same column, which the reader can drag narrower to watch the tabs collapse and scroll. */
 .resizable {
   composes: frame;

package/src/components/tabs/examples/in-drawer.tsx

@@ -1,7 +1,5 @@
 /** Order details in a Drawer: the tab bar runs along the bottom of the header, the active tab is the body rising into it, and every panel is the body's own content — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`. */
-import { Badge, Button, DescriptionList, Drawer, Input, Tabs, Typography } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+import { Badge, Button, DescriptionList, Drawer, Fieldset, Input, Tabs } from "prime-ui-kit";
 
 const ITEMS = [
   { name: "Кресло «Орион», графит", amount: "2 × 18 900 ₽" },
@@ -10,9 +8,9 @@ const ITEMS = [
 ];
 
 const HISTORY = [
-  "3 октября, 10:14 — заказ оформлен",
-  "3 октября, 10:20 — оплата прошла",
-  "4 октября, 16:02 — передан на склад",
+  { time: "3 октября, 10:14", event: "Заказ оформлен" },
+  { time: "3 октября, 10:20", event: "Оплата прошла" },
+  { time: "4 октября, 16:02", event: "Передан на склад" },
 ];
 
 export default function TabsInDrawerExample() {
@@ -61,7 +59,7 @@ export default function TabsInDrawerExample() {
             </Tabs.Panel>
 
             <Tabs.Panel value="delivery">
-              <div className={styles.stack}>
+              <Fieldset aria-label="Доставка">
                 <Input.Root label="Адрес">
                   <Input.Wrapper>
                     <Input.Field defaultValue="Москва, Ленинградский проспект, 37, кв. 12" />
@@ -72,17 +70,17 @@ export default function TabsInDrawerExample() {
                     <Input.Field defaultValue="Позвонить за час" />
                   </Input.Wrapper>
                 </Input.Root>
-              </div>
+              </Fieldset>
             </Tabs.Panel>
 
             <Tabs.Panel value="history">
-              <div className={styles.stack}>
+              <DescriptionList.Root>
                 {HISTORY.map((entry) => (
-                  <Typography key={entry} variant="body-m" tone="secondary">
-                    {entry}
-                  </Typography>
+                  <DescriptionList.Item key={entry.time} label={entry.time}>
+                    {entry.event}
+                  </DescriptionList.Item>
                 ))}
-              </div>
+              </DescriptionList.Root>
             </Tabs.Panel>
           </Drawer.Body>
         </Tabs.Root>

package/src/components/timeline/examples/examples.module.css

@@ -6,14 +6,6 @@
   width: min(100%, calc(var(--prime-space-24) * 5));
 }
 
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-10);
-  width: min(100%, calc(var(--prime-space-24) * 5));
-  min-width: 0;
-}
-
 /* narrow.tsx: a 375px phone column. */
 .phone {
   width: min(100%, calc(var(--prime-space-1) * 93.75));

package/src/components/timeline/examples/narrow.tsx

@@ -20,7 +20,7 @@ const EVENTS = [
 
 export default function TimelineNarrowExample() {
   return (
-    <div className={styles.stack}>
+    <>
       {WIDTHS.map((width) => (
         <Timeline.Root key={width.id} className={width.className}>
           <Timeline.Group label={width.label}>
@@ -36,6 +36,6 @@ export default function TimelineNarrowExample() {
           </Timeline.Group>
         </Timeline.Root>
       ))}
-    </div>
+    </>
   );
 }

package/src/components/timeline/examples/sizes.tsx

@@ -7,9 +7,9 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TimelineSizesExample() {
   return (
-    <div className={styles.stack}>
+    <>
       {SIZES.map((size) => (
-        <Timeline.Root key={size} size={size}>
+        <Timeline.Root key={size} size={size} className={styles.feed}>
           <Timeline.Group label={size}>
             <Timeline.Item>
               <Timeline.Title>Аренда закончилась · Иван К.</Timeline.Title>
@@ -28,6 +28,6 @@ export default function TimelineSizesExample() {
           </Timeline.Group>
         </Timeline.Root>
       ))}
-    </div>
+    </>
   );
 }

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

@@ -27,8 +27,8 @@ const TONES: { tone: Tone; title: string; value: string }[] = [
 
 export default function TimelineVariantsExample() {
   return (
-    <div className={styles.stack}>
-      <Timeline.Root>
+    <>
+      <Timeline.Root className={styles.feed}>
         <Timeline.Group label="color">
           {COLORS.map((color) => (
             <Timeline.Item key={color} color={color}>
@@ -38,7 +38,7 @@ export default function TimelineVariantsExample() {
           ))}
         </Timeline.Group>
       </Timeline.Root>
-      <Timeline.Root>
+      <Timeline.Root className={styles.feed}>
         <Timeline.Group label="tone">
           {TONES.map(({ tone, title, value }) => (
             <Timeline.Item key={tone} tone={tone}>
@@ -51,6 +51,6 @@ export default function TimelineVariantsExample() {
           <Timeline.Gap tone="danger">Просрочка 30 дней</Timeline.Gap>
         </Timeline.Group>
       </Timeline.Root>
-    </div>
+    </>
   );
 }

package/src/components/tooltip/COMPONENT.md

@@ -70,7 +70,7 @@ No DOM of its own: clones the single child and links it to the tooltip with `ari
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Preferred side; flips to the opposite one when it does not fit, then shifts inside the viewport. |
-| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the trigger: its start edge, centre or end edge; the arrow keeps pointing at the trigger. |
+| `align` | `"auto" \| "start" \| "center" \| "end"` | `"center"` | Alignment along the trigger: centred by default; `auto` lines the chip up with the trigger edge that has more room beyond it; `start` or `end` fix the edge. The arrow keeps pointing at the trigger. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text and padding tier; also the size context of controls inside (a Kbd). |
 | `children` | `ReactNode` | — (required) | Hint text, optionally with a Kbd. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "role" \| "onPointerEnter" \| "onPointerLeave">` | — | `className`, `style` and the other attributes of the chip. |
@@ -100,9 +100,10 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 ### align (Content)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `start` | Chip starts at the trigger's start edge | Wide triggers, triggers at a container's start | |
 | `center` | Chip centred on the trigger | Most triggers | yes |
-| `end` | Chip ends at the trigger's end edge | Triggers at a container's end | |
+| `auto` | Lined up with the trigger edge that has more room: near the end of the screen the end edges meet and the chip grows toward the start, near the start the other way | A long chip on a wide trigger near a screen edge | |
+| `start` | Chip starts at the trigger's start edge | The chip must line up with the start of a block whatever room there is | |
+| `end` | Chip ends at the trigger's end edge | The chip must line up with the end of a block whatever room there is | |
 
 **Combinations** — size of the tooltip = size of the trigger control; a Kbd inside takes the tier one step down by itself.
 
@@ -133,6 +134,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 - `Tooltip.Trigger` composes the child's `ref`, sets `data-state` and chains the child's `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus` and `onBlur`.
 - The tooltip is a description, not the name: an icon-only button needs its own `aria-label`.
 - The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, focus does.
+- Tooltip has no `closeOnEscape` / `closeOnOutsideClick` (foundation §8): it closes on pointer-leave, blur, a press on the trigger and Escape, and Escape cannot be turned off — WCAG 1.4.13 requires the chip to be dismissable without moving the pointer or focus.
 - A `disabled` control is wrapped by the kit in a focusable `<span>`: the host takes hover and Tab, the focus ring is drawn on the control.
 - A trigger that is no tab stop (Badge, Avatar, ProgressCircle, `Icon` with `label`) gets `tabIndex={0}` and the focus ring; its name comes from `aria-label` or the icon `label`.
 
@@ -146,7 +148,7 @@ No `labels`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | An icon-only button with a tooltip that repeats its name on hover and keyboard focus — `Tooltip.Trigger`, `Tooltip.Content`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier next to buttons of the same tier; take the tier of the control it describes — `size`. |
-| [placement.tsx](examples/placement.tsx) | Every side, and start / end alignment along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. |
+| [placement.tsx](examples/placement.tsx) | Every side, and alignment by room, start and end along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. |
 | [toolbar.tsx](examples/toolbar.tsx) | A formatting toolbar in one group: after the first tooltip the neighbours open at once, each with its name and shortcut — `Tooltip.Provider`. |
 | [disabled-trigger.tsx](examples/disabled-trigger.tsx) | Why an action is unavailable: the disabled button still shows its tooltip on hover and Tab, no wrapper needed — `Tooltip.Trigger`. |
 | [non-interactive-trigger.tsx](examples/non-interactive-trigger.tsx) | A status badge, an avatar and an information icon explain themselves: the kit makes each a tab stop, so the tooltip opens from the keyboard too — `Tooltip.Trigger`. |

package/src/components/tooltip/examples/placement.tsx

@@ -1,4 +1,4 @@
-/** Every side, and start / end alignment along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. */
+/** Every side, and alignment by room, start and end along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. */
 import { Button, Tooltip } from "prime-ui-kit";
 
 const PLACEMENTS = [
@@ -6,6 +6,7 @@ const PLACEMENTS = [
   { side: "bottom", align: "center" },
   { side: "left", align: "center" },
   { side: "right", align: "center" },
+  { side: "bottom", align: "auto" },
   { side: "bottom", align: "start" },
   { side: "bottom", align: "end" },
 ] as const;

package/src/components/video-note/COMPONENT.md

@@ -79,7 +79,7 @@ One look. The circle is the video; the play disk and the pills stand on the medi
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| loading | the first frame not drawn yet | `data-frame="loading"` on the circle: a Skeleton fills it, the video fades in (`base`) once loaded |
+| loading | the first frame not drawn yet | `data-frame="loading"` on the circle: a Skeleton fills it; once loaded the video fades in over it (`base`), then the Skeleton goes |
 | at rest | idle | `data-state="idle"` on the circle; the still first frame (or `poster`) with the play disk and the duration; nothing plays, loops or decodes past the metadata and the first frame — a long chat costs nothing until a press |
 | playing | the disk (or a press on the circle), `playing` / `defaultPlaying` | `data-playing="true"` on the root, `data-state="playing"`; sound from the start, the ring fills over the edge every frame (one CSS variable on the ring), the duration counts down, the disk's glyph turns to pause and the disk fades out (it stays while it has the keyboard focus); `onPlayingChange(true)`; any other sound pauses |
 | paused | the disk or the circle again, another sound starting, `playing={false}` | `data-state="paused"`, the disk with the play glyph comes back, the ring stays; `onPlayingChange(false)` |