prime-ui-kit 0.13.1 → 0.15.0

package/src/components/sheet/examples/header-actions.tsx

@@ -0,0 +1,56 @@
+/** The courier is at the door: an icon tile heads the sheet, the payment status and a ⋯ menu sit before the close button, and two equal buttons fill the footer — `Sheet.Icon`, `Sheet.Actions`, `layout`. */
+import { Badge, Button, Dropdown, Icon, Sheet, Typography } from "prime-ui-kit";
+
+export default function SheetHeaderActionsExample() {
+  return (
+    <Sheet.Root>
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Курьер на месте
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header>
+          <Sheet.Icon tone="info">
+            <Icon name="object.truck" />
+          </Sheet.Icon>
+          <Sheet.Title>Курьер у двери</Sheet.Title>
+          <Sheet.Description>Заказ № 1042 · 3 коробки</Sheet.Description>
+          <Sheet.Actions>
+            <Badge.Root color="green">Оплачен</Badge.Root>
+            <Dropdown.Root>
+              <Dropdown.Trigger>
+                <Button.Root variant="ghost" tone="neutral" aria-label="Действия с заказом">
+                  <Button.Icon>
+                    <Icon name="action.more" />
+                  </Button.Icon>
+                </Button.Root>
+              </Dropdown.Trigger>
+              <Dropdown.Content>
+                <Dropdown.Item>Позвонить курьеру</Dropdown.Item>
+                <Dropdown.Item>Перенести доставку</Dropdown.Item>
+                <Dropdown.Separator />
+                <Dropdown.Item tone="danger">Отказаться от заказа</Dropdown.Item>
+              </Dropdown.Content>
+            </Dropdown.Root>
+          </Sheet.Actions>
+        </Sheet.Header>
+        <Sheet.Body>
+          <Typography variant="body-m" tone="secondary">
+            Проверьте коробки при курьере: после приёмки претензии к упаковке не принимаются.
+          </Typography>
+        </Sheet.Body>
+        <Sheet.Footer layout="fill">
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Позже
+            </Button.Root>
+          </Sheet.Close>
+          <Sheet.Close>
+            <Button.Root>Принять заказ</Button.Root>
+          </Sheet.Close>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

package/src/components/slider/COMPONENT.md

@@ -166,13 +166,14 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 | [overview.tsx](examples/overview.tsx) | A labelled slider with its current value — `label`, `showValue`. |
 | [variants.tsx](examples/variants.tsx) | Every fill color; accent by default, semantic tones when the value carries meaning — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the thumb, the label and the value grow with the tier — `size`. |
-| [states.tsx](examples/states.tsx) | The fill at both ends and a disabled slider — `disabled`. |
+| [states.tsx](examples/states.tsx) | The fill at both ends, an invalid slider and a disabled one — `invalid`, `disabled`. |
 | [orientation.tsx](examples/orientation.tsx) | Notification levels as a row of upright sliders, minimum at the bottom — `orientation`. |
 | [value-format.tsx](examples/value-format.tsx) | Units in the shown value that are also read by screen readers — `formatValue`, `showValue`. |
 | [range-step.tsx](examples/range-step.tsx) | Own bounds and a coarse or fractional step; a slider without a visible label — `min`, `max`, `step`, `aria-label`. |
 | [hint-and-error.tsx](examples/hint-and-error.tsx) | A slider framed like every field: required marker, a hint, and an error in its place — `required`, `hint`, `error`, `optional`. |
 | [autosave.tsx](examples/autosave.tsx) | A setting saved once the thumb is let go, not on every step: the thumb waits dimmed while it saves, and a value the server refuses glides back — `onCommit`, `hint`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value and shares it with a number field for exact entry — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | Campaign limits submitted with the form by `name`, a calm note confirms the save — `name`, `label`. |
 
 ## Mistakes
 - `<Slider.Root>` → the slider is a single export: `<Slider />`.

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

@@ -22,3 +22,11 @@
   display: flex;
   gap: var(--prime-space-8);
 }
+
+/* in-form.tsx: the submit row after the fields, the note beside the button. */
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}

package/src/components/slider/examples/in-form.tsx

@@ -0,0 +1,47 @@
+/** Campaign limits submitted with the form by `name`, a calm note confirms the save — `name`, `label`. */
+import { Button, Slider, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SliderInFormExample() {
+  const [saved, setSaved] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    setSaved(
+      `Сохранено: показов в день — ${data.get("dailyCap")}, ставка — ${data.get("bidShare")}%.`,
+    );
+  };
+
+  return (
+    <form className={styles.column} noValidate onSubmit={submit}>
+      <Slider
+        label="Показов одному клиенту в день"
+        name="dailyCap"
+        min={1}
+        max={10}
+        defaultValue={3}
+        showValue
+        onValueChange={() => setSaved(undefined)}
+      />
+      <Slider
+        label="Доля бюджета на ставки, %"
+        name="bidShare"
+        step={5}
+        defaultValue={40}
+        showValue
+        onValueChange={() => setSaved(undefined)}
+      />
+      <div className={styles.actions}>
+        <Button.Root type="submit">Сохранить лимиты</Button.Root>
+        {saved ? (
+          <Typography as="p" variant="body-s" tone="secondary" role="status">
+            {saved}
+          </Typography>
+        ) : null}
+      </div>
+    </form>
+  );
+}

package/src/components/slider/examples/states.tsx

@@ -1,4 +1,4 @@
-/** The fill at both ends and a disabled slider — `disabled`. */
+/** The fill at both ends, an invalid slider and a disabled one — `invalid`, `disabled`. */
 import { Slider } from "prime-ui-kit";
 
 export default function SliderStatesExample() {
@@ -10,6 +10,9 @@ export default function SliderStatesExample() {
       <div>
         <Slider label="max" showValue defaultValue={100} />
       </div>
+      <div>
+        <Slider label="invalid" showValue defaultValue={90} invalid />
+      </div>
       <div>
         <Slider label="disabled" showValue defaultValue={35} disabled />
       </div>

package/src/components/smart-filter/COMPONENT.md

@@ -213,7 +213,7 @@ same height and type.
 | [overview.tsx](examples/overview.tsx) | Filters above a request list: the filter button and the search, applied filters as tags, rows narrowed by the value and the text — `fields`, `value`, `search`, `matchesSmartFilter`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. |
 | [many-values.tsx](examples/many-values.tsx) | An open set of twenty services, degraded ones marked with an icon, collapsed after eight; typing narrows the panel and marks the match in accent — `finite`, `icon`, `collapsedLimit`. |
-| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip — `kind`, `formatValue`, `matchesSmartFilter`. |
+| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. |
 | [single-value.tsx](examples/single-value.tsx) | For an API that takes one value per field: the filter button without a search, a press picks only that value and nothing can be hidden — `searchable`, `multiple`. |
 | [option-groups.tsx](examples/option-groups.tsx) | Values of different kinds in one field: owner types and people under their own headings — `options`, `group`. |
 | [controlled.tsx](examples/controlled.tsx) | A saved view sets the value from outside; the selection is read back as the list to ask the server for — `value`, `onValueChange`, `resolveSmartFilterValues`. |

package/src/components/smart-filter/examples/controlled.tsx

@@ -30,13 +30,13 @@ export default function SmartFilterControlledExample() {
         <SmartFilter.Chips />
       </SmartFilter.Root>
       <div className={styles.views}>
-        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(ONLY_PUT)}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setValue(ONLY_PUT)}>
           Только PUT
         </Button.Root>
-        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(NO_READS)}>
+        <Button.Root variant="soft" tone="neutral" onClick={() => setValue(NO_READS)}>
           Без GET и POST
         </Button.Root>
-        <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setValue({})}>
+        <Button.Root variant="ghost" tone="neutral" onClick={() => setValue({})}>
           Сбросить
         </Button.Root>
       </div>

package/src/components/smart-filter/examples/ranges.tsx

@@ -1,5 +1,7 @@
-/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip — `kind`, `formatValue`, `matchesSmartFilter`. */
+/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. */
 import {
+  Card,
+  isSmartFilterRange,
   matchesSmartFilter,
   SmartFilter,
   type SmartFilterField,
@@ -59,6 +61,23 @@ const DEALS = [
 
 const INITIAL: SmartFilterValue = { amount: { from: 50_000, to: 500_000 } };
 
+const asParam = (bound: number | Date) =>
+  bound instanceof Date ? bound.toISOString().slice(0, 10) : String(bound);
+
+/** The query a server gets: a range becomes `key_from` / `key_to`, a selection its included values. */
+function toQuery(value: SmartFilterValue) {
+  const params = new URLSearchParams();
+  for (const [key, entry] of Object.entries(value)) {
+    if (isSmartFilterRange(entry)) {
+      if (entry.from !== null) params.set(`${key}_from`, asParam(entry.from));
+      if (entry.to !== null) params.set(`${key}_to`, asParam(entry.to));
+    } else if (entry.include.length > 0) {
+      params.set(key, entry.include.join(","));
+    }
+  }
+  return params.toString();
+}
+
 export default function SmartFilterRangesExample() {
   const [value, setValue] = React.useState<SmartFilterValue>(INITIAL);
   const rows = DEALS.filter(
@@ -74,16 +93,31 @@ export default function SmartFilterRangesExample() {
         <SmartFilter.Toolbar />
         <SmartFilter.Chips />
       </SmartFilter.Root>
-      {rows.map((deal) => (
-        <div key={deal.id} className={styles.request}>
-          <Typography as="span" variant="body-m" truncate className={styles.route}>
-            {deal.client}
-          </Typography>
-          <Typography as="span" variant="body-m" tone="secondary">
-            {formatRubles(deal.amount)}
+      <Card.Root variant="list">
+        <Card.Header>
+          <Card.Title>Сделки</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            {rows.length} из {DEALS.length}
           </Typography>
-        </div>
-      ))}
+        </Card.Header>
+        <Card.List>
+          {rows.map((deal) => (
+            <Card.ListItem key={deal.id}>
+              <span className={styles.request}>
+                <Typography as="span" variant="body-m" truncate className={styles.route}>
+                  {deal.client}
+                </Typography>
+                <Typography as="span" variant="body-m" tone="secondary">
+                  {formatRubles(deal.amount)}
+                </Typography>
+              </span>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </Card.Root>
+      <Typography as="span" variant="code" tone="secondary">
+        {`GET /deals?${toQuery(value)}`}
+      </Typography>
     </div>
   );
 }

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 to 5% and the change over the whole period — `reference`, `min`, `max`, `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>
   );