prime-ui-kit 0.9.1 → 0.9.3

package/src/components/page-toolbar/examples/save-changes.tsx

@@ -0,0 +1,40 @@
+/** A settings page: sections of the form on the left, the save action with the number of changes at the end of the top row — never a sticky bar at the bottom of a phone screen — `PageToolbar.Actions`. */
+import { Button, PageToolbar, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+const SECTIONS = [
+  { value: "profile", label: "Профиль" },
+  { value: "billing", label: "Оплата" },
+  { value: "team", label: "Команда" },
+];
+
+const CHANGES = 3;
+
+export default function PageToolbarSaveChangesExample() {
+  const [section, setSection] = React.useState("profile");
+
+  return (
+    <PageToolbar.Root aria-label="Настройки">
+      <PageToolbar.Sections>
+        <SegmentedControl.Root
+          fullWidth
+          value={section}
+          onValueChange={setSection}
+          aria-label="Раздел настроек"
+        >
+          {SECTIONS.map((item) => (
+            <SegmentedControl.Item key={item.value} value={item.value}>
+              {item.label}
+            </SegmentedControl.Item>
+          ))}
+        </SegmentedControl.Root>
+      </PageToolbar.Sections>
+      <PageToolbar.Actions>
+        <Button.Root variant="ghost" tone="neutral">
+          Отменить
+        </Button.Root>
+        <Button.Root>Сохранить {CHANGES} изменения</Button.Root>
+      </PageToolbar.Actions>
+    </PageToolbar.Root>
+  );
+}

package/src/components/page-toolbar/examples/without-search.tsx

@@ -0,0 +1,60 @@
+/** A dashboard panel without search on a tablet-width column: the sections fill the top row, the period selector alone in the bottom row stretches to the full width — `PageToolbar.Sections`, `PageToolbar.View`. */
+import { Icon, PageToolbar, SegmentedControl, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "overview", label: "Обзор" },
+  { value: "activity", label: "Активность" },
+  { value: "resources", label: "Ресурсы" },
+];
+
+const PERIODS = [
+  { value: "1h", label: "1 час" },
+  { value: "24h", label: "24 часа" },
+  { value: "7d", label: "7 дней" },
+];
+
+export default function PageToolbarWithoutSearchExample() {
+  const [section, setSection] = React.useState("overview");
+  const [period, setPeriod] = React.useState("24h");
+
+  return (
+    <div className={styles.tablet}>
+      <PageToolbar.Root aria-label="Панель мониторинга">
+        <PageToolbar.Sections>
+          <SegmentedControl.Root
+            fullWidth
+            value={section}
+            onValueChange={setSection}
+            aria-label="Раздел"
+          >
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </PageToolbar.Sections>
+        <PageToolbar.View>
+          <Select.Root value={period} onValueChange={setPeriod}>
+            <Select.Trigger aria-label="Период">
+              <Select.TriggerIcon>
+                <Icon name="field.calendar" />
+              </Select.TriggerIcon>
+              <Select.Value />
+            </Select.Trigger>
+            <Select.Content>
+              {PERIODS.map((item) => (
+                <Select.Item key={item.value} value={item.value}>
+                  {item.label}
+                </Select.Item>
+              ))}
+            </Select.Content>
+          </Select.Root>
+        </PageToolbar.View>
+      </PageToolbar.Root>
+    </div>
+  );
+}

package/src/components/popover/COMPONENT.md

@@ -61,7 +61,7 @@ No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles th
 | `children` | `ReactElement` | — (required) | One element, usually a Button (Anchor: any element, e.g. a toolbar). |
 
 ### Popover.Content
-`ref` → `HTMLDivElement`. Portal + `role="dialog"` on the floating surface (a ScrollContainer); renders while open and during its exit animation. Named by `Popover.Title`, else by the trigger. Opened from a Trigger, focus moves into the panel (`[data-autofocus]`, else the first tab stop, else the panel).
+`ref` → `HTMLDivElement`. Portal + `role="dialog"` on the floating surface (a ScrollContainer); renders while open and during its exit animation. Named by `Popover.Title`, else by the trigger. Opened from a Trigger, focus moves into the panel (`[data-autofocus]`, else the first tab stop, else the panel). Below 640px of viewport a panel opened from a Trigger (not an Anchor) is a bottom sheet: a scrim, a grab handle, swipe down to close (with `closeOnOutsideClick`), page scroll locked.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -74,10 +74,10 @@ No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles th
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `className` and the other attributes of the panel. |
 
 ### Popover.Header · Popover.Title · Popover.Description · Popover.Actions
-`ref` → the element. `<div>` (title + description with a 4 px step) / `<h2>` (names the dialog) / `<p>` (describes it) / `<div>` (buttons at the end, stacked full width below 480 px). + native props.
+`ref` → the element. `<div>` (title + description with a 4 px step) / `<h2>` (names the dialog) / `<p>` (describes it) / `<div>` (buttons at the end, stacked full width on phones, below 640 px). + native props.
 
 ## Variants
-The panel has one look: `bg-raised` fill, `--prime-panel-radius`, `shadow-overlay`, no border. Fields inside get the surface field fill; cards inside become sunken tiles.
+The panel has one look: the floating layer of the ladder (`data-depth="floating"`), `--prime-panel-radius`, `shadow-overlay`, no border. Fields inside take that layer's fill; a card inside is the next layer, a flat tile.
 
 ### size (Content)
 | Value | Looks like | Use when | Default |
@@ -121,6 +121,7 @@ Title uses the tier text size with title weight; Description uses the tier label
 | size | `size` on Content | `data-size` |
 | width | `matchTriggerWidth` | `data-match-trigger-width="true"` |
 | flush | `flush` | `data-flush="true"` |
+| sheet | viewport below 640px, opened from a Trigger (an Anchor keeps the panel next to its field) | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it (with `closeOnOutsideClick`) |
 
 There is no `disabled` on Popover: a disabled trigger never opens it.
 
@@ -128,7 +129,7 @@ There is no `disabled` on Popover: a disabled trigger never opens it.
 - Width is `max-content` between `--prime-panel-min-width` and twice that, never wider than the viewport; give forms an explicit width with `className`.
 - Max height follows the free space on the resolved side; the panel scrolls inside.
 - Kept `--prime-space-2` from viewport edges; follows the trigger on scroll and resize.
-- Actions: at the end, `--prime-space-2` gap; below 480px they stack full width.
+- Actions: at the end, `--prime-space-2` gap; on phones (below 640px) they stack full width.
 
 ## Accessibility
 

package/src/components/progress-bar/COMPONENT.md

@@ -1,6 +1,6 @@
 # ProgressBar
 
-**Category:** feedback
+**Category:** status
 **Kind:** primitive
 
 > Linear progress: one value on a native `<progress>`, or `segments` that split a whole (storage by type, task statuses), with a label, a percentage and status colors.
@@ -51,6 +51,7 @@ A native `<progress>` (transparent, for assistive tech) under the drawn line.
 | `value` | `number` | — (required) | The current value, clamped to `0…max`. |
 | `max` | `number` | `100` | Top of the scale. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Fill color, telling the outcome. |
+| `steps` | `boolean` | `false` | Draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. In one change the cells go one after another — from the start when filling, from the end when emptying. For a level out of a few: password strength, onboarding steps. |
 
 ### ProgressBar · segments mode
 A `role="group"` bar of parts, named by `label` and described by the distribution text.
@@ -100,8 +101,9 @@ A `role="group"` bar of parts, named by `label` and described by the distributio
 | tone / size | props | `data-tone` (value mode), `data-size` on the root |
 | value | `value`, `max` | native `value` / `max`; the drawn pill slides by `translate` over `slow` + `standard`, RTL aware |
 | segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the group, `data-tone` per part; widths animate by `flex-grow` over `slow` |
+| steps | `steps` (value mode) | `data-steps="true"` on the bar; `max` cells (2–12), filled ones `data-filled`; a cell fills from its start edge (`base` · emphasized), cells of one change go half a stagger step apart — from the start when filling, from the end when emptying |
 | empty segments | `segments` empty or all `0` | only the track; accessible text `labels.empty` / `labels.allEmpty` |
-| reduced motion | `prefers-reduced-motion` | fill and widths change instantly |
+| reduced motion | `prefers-reduced-motion` | fill, widths and cells change instantly |
 
 Always controlled: pass the current `value` or `segments` on every render.
 
@@ -137,6 +139,8 @@ No keyboard interaction.
 | [sizes.tsx](examples/sizes.tsx) | Every tier: the line grows from 4 to 8 px like the Slider track — `size`. |
 | [custom-max.tsx](examples/custom-max.tsx) | A scale of steps instead of percent: 3 of 5 profile steps — `max`. |
 | [segments.tsx](examples/segments.tsx) | Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list — `segments`, `segmentGap`, `max`. |
+| [steps.tsx](examples/steps.tsx) | The scale as whole cells that fill one after another: 2 of 5 onboarding steps, forward and back — `steps`, `max`. |
+| [milestone.tsx](examples/milestone.tsx) | A rare milestone: the last invoice of the quarter fills the bar, the tone turns success and a short confetti burst marks it — `value`, `tone`, `celebrate()`. |
 
 ## Mistakes
 - No `label` and no `aria-label` → the bar has no accessible name.

package/src/components/progress-bar/examples/examples.module.css

@@ -8,3 +8,10 @@
   width: min(100%, var(--prime-modal-width-s));
   min-width: 0;
 }
+
+/* Buttons under a bar that drive it. */
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}

package/src/components/progress-bar/examples/milestone.tsx

@@ -0,0 +1,43 @@
+/** A rare milestone: the last invoice of the quarter fills the bar, the tone turns success and a short confetti burst marks it — `value`, `tone`, `celebrate()`. */
+import { Button, celebrate, ProgressBar } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INVOICES = 12;
+
+export default function ProgressBarMilestoneExample() {
+  const [paid, setPaid] = React.useState(INVOICES - 1);
+  const closed = paid === INVOICES;
+
+  return (
+    <div className={styles.column}>
+      <ProgressBar
+        value={paid}
+        max={INVOICES}
+        tone={closed ? "success" : "accent"}
+        label={
+          closed
+            ? "III квартал закрыт: все счета оплачены"
+            : `Оплачено счетов: ${paid} из ${INVOICES}`
+        }
+      />
+      <div className={styles.actions}>
+        <Button.Root
+          variant={closed ? "soft" : "solid"}
+          tone={closed ? "neutral" : "accent"}
+          onClick={(event) => {
+            if (closed) {
+              setPaid(INVOICES - 1);
+              return;
+            }
+            setPaid(INVOICES);
+            celebrate({ origin: event.currentTarget });
+          }}
+        >
+          {closed ? "Вернуть последний счёт" : "Отметить оплату ООО «Вектор»"}
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-bar/examples/steps.tsx

@@ -0,0 +1,35 @@
+/** The scale as whole cells that fill one after another: 2 of 5 onboarding steps, forward and back — `steps`, `max`. */
+import { Button, ProgressBar } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TOTAL = 5;
+
+export default function ProgressBarStepsExample() {
+  const [done, setDone] = React.useState(2);
+
+  return (
+    <div className={styles.column}>
+      <ProgressBar
+        steps
+        value={done}
+        max={TOTAL}
+        label={`Настройка компании: ${done} из ${TOTAL}`}
+      />
+      <div className={styles.actions}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          disabled={done === 0}
+          onClick={() => setDone(done - 1)}
+        >
+          Назад
+        </Button.Root>
+        <Button.Root disabled={done === TOTAL} onClick={() => setDone(done + 1)}>
+          Следующий шаг
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/COMPONENT.md

@@ -1,6 +1,6 @@
 # ProgressCircle
 
-**Category:** feedback
+**Category:** status
 **Kind:** primitive
 
 > Circular progress — the ring version of ProgressBar: one value or `segments` that split a whole, with status colors and optional content in the center.

package/src/components/scroll-container/COMPONENT.md

@@ -1,6 +1,6 @@
 # ScrollContainer
 
-**Category:** layout
+**Category:** page
 **Kind:** layout
 
 > A scroll region with the kit's thin scrollbar that shrinks correctly inside flex and grid parents.

package/src/components/segmented-control/COMPONENT.md

@@ -27,7 +27,7 @@ import { SegmentedControl } from "prime-ui-kit";
 SegmentedControl.Root                 role="radiogroup"; track + sliding thumb, scrolling row, keyboard
 └─ SegmentedControl.Item              role="radio" button, one option
    ├─ SegmentedControl.Icon           icon slot (optional; icon-only → square segment)
-   ├─ SegmentedControl.Label          title, truncates (optional; plain text is wrapped automatically)
+   ├─ SegmentedControl.Label          title, one line (optional; plain text is wrapped automatically)
    ├─ SegmentedControl.Count          counter Badge after the label (optional)
    └─ SegmentedControl.Description    second line; makes the segment two-line (optional)
 ```
@@ -46,12 +46,12 @@ SegmentedControl.Root                 role="radiogroup"; track + sliding thumb,
 | `onValueChange` | `(value: string) => void` | — | Called with the new value on click or arrow keys. |
 | `disabled` | `boolean` | `false` | Disables the whole group. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier; the outer height equals the control height 28 · 32 · 36 · 40 · 48. Without it the tier of its host (a toolbar, a panel with a size), else `m`. |
-| `fullWidth` | `boolean` | `false` | Fills the container; single-line segments share the width equally and truncate. |
+| `fullWidth` | `boolean` | `false` | Fills the container; single-line segments tend to equal widths but never get narrower than their label — when they do not fit, the row scrolls. |
 | `children` | `ReactNode` | — | `SegmentedControl.Item`s (may be wrapped, e.g. in `Tooltip.Trigger`). |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange">` | — | `aria-label` / `aria-labelledby` (name the group), `className` and the other div attributes. |
 
 ### SegmentedControl.Item
-`ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped to truncate.
+`ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped in a `SegmentedControl.Label`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -70,7 +70,7 @@ SegmentedControl.Root                 role="radiogroup"; track + sliding thumb,
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Label
-`ref` → `HTMLSpanElement`. Segment title; truncates with an ellipsis. Plain text is wrapped automatically.
+`ref` → `HTMLSpanElement`. Segment title on one line; never truncated. Plain text is wrapped automatically.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -123,7 +123,7 @@ Track is `fill-muted` with a faint 1px ring; the selected segment is a floating
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `fullWidth` | fills the container; single-line segments are equal and truncate, two-line segments grow from their content | modals, mobile panels, overview strips | off |
+| `fullWidth` | fills the container; single-line segments tend to equal widths, a long label keeps its own width and the row scrolls when they do not fit; two-line segments grow from their content | modals, mobile panels, overview strips | off |
 | `disabled` | every segment disabled, thumb `fill-muted-hover` without shadow | the choice is temporarily unavailable | off |
 | icon-only (only `SegmentedControl.Icon`) | square segment (`data-icon-only`) | toolbar view toggles; needs `aria-label` | — |
 
@@ -140,13 +140,13 @@ Colour all items or none; do not give an item and its Count the same hue; prefer
 | focus-visible | keyboard | focus ring inside the segment |
 | overflow | row wider than the container | root `data-overflow-start` / `data-overflow-end`: edge fades in the track color |
 
-Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb glides (`emphasized` + `base`, `data-animate`) only into a user's choice (click, arrows); a value set from outside and layout changes snap it; it stays still under `prefers-reduced-motion`. It sits inside the segment track, which clips it, so moving the selection never changes the row's scroll area; when the row scrolls, the chosen segment is scrolled into view.
+Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb glides (`emphasized` + `base`, `data-animate`) only into a user's choice (click, arrows); a value set from outside and layout changes snap it; it stays still under `prefers-reduced-motion`. It sits inside the segment track, which clips it, so moving the selection never changes the row's scroll area. When the row scrolls, the selected segment is kept in view on mount and on every value change: only the row scrolls, never the page, and the scroll glides only after a user's choice.
 
 ## Layout & spacing
 - Width is content-based by default; segments never wrap. In a narrow container the row scrolls horizontally with fading edges.
 - In a toolbar: gap `--prime-space-3` between controls; keep every control at one size.
 - Caption under a group: gap `--prime-space-2`.
-- `fullWidth` inside modals and mobile sheets.
+- `fullWidth` inside modals and mobile sheets. Single-line segments are `flex: 1 1 0` with `min-width: max-content`: short labels share the spare width equally, a long label keeps its own width, nothing truncates; when the labels do not fit, the row scrolls.
 
 ## Accessibility
 
@@ -177,7 +177,7 @@ No `labels`.
 | [states.tsx](examples/states.tsx) | No selection yet, a disabled segment and a disabled group next to the default — `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments named for screen readers — `SegmentedControl.Icon`, `aria-label`. |
 | [colors.tsx](examples/colors.tsx) | A status per option: a dot of its hue before the label and a tinted thumb when chosen — `color`. |
-| [full-width.tsx](examples/full-width.tsx) | The group fills its column; segments share the width equally and truncate long labels — `fullWidth`. |
+| [full-width.tsx](examples/full-width.tsx) | The group fills its column; segments tend to equal widths and a long label keeps its own — `fullWidth`. |
 | [scroll.tsx](examples/scroll.tsx) | Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view. |
 | [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a metric on the second — `SegmentedControl.Label`, `SegmentedControl.Count`, `SegmentedControl.Description`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the choice and updates other content from it — `value`, `onValueChange`. |

package/src/components/segmented-control/examples/full-width.tsx

@@ -1,4 +1,4 @@
-/** The group fills its column; segments share the width equally and truncate long labels — `fullWidth`. */
+/** The group fills its column; segments tend to equal widths and a long label keeps its own — `fullWidth`. */
 import { SegmentedControl } from "prime-ui-kit";
 
 export default function SegmentedControlFullWidthExample() {

package/src/components/select/COMPONENT.md

@@ -95,7 +95,7 @@ Select.Root                       field frame: label · control · hint/error; v
 `ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` with a leading glyph at the tier icon size: before the value / before the option label. + native `<span>` props.
 
 ### Select.Content
-`ref` → `HTMLDivElement` (the panel). Portal + the floating list panel, mounted while open and during its exit animation (closed, the items render hidden in place so the trigger knows their labels), shown with the overlay motion. Holds the search row, the `role="listbox"` and the empty state.
+`ref` → `HTMLDivElement` (the panel). Portal + the floating list panel, mounted while open and during its exit animation (closed, the items render hidden in place so the trigger knows their labels), shown with the overlay motion. Holds the search row, the `role="listbox"` and the empty state. Below 640px of viewport the panel is a bottom sheet: a scrim, a grab handle, swipe down to close, page scroll locked.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -163,6 +163,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | disabled | `disabled` | native `disabled`, `data-disabled="true"` |
 | loading | `loading` | `data-loading="true"`, `aria-busy`; status row in the list |
 | searching | typing in the search | panel `data-searching="true"`; groups without matches and separators hide; the match in an option's title, description and plain text is a `<mark>` in `accent-text` (not in the trigger) |
+| sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it |
 | option highlighted / selected / disabled | keyboard and pointer / value / `disabled` | `data-highlighted`, `data-selected` + `aria-selected`, `data-disabled` + `aria-disabled`; highlight is a fill only |
 
 ## Layout & spacing

package/src/components/skeleton/COMPONENT.md

@@ -1,6 +1,6 @@
 # Skeleton
 
-**Category:** feedback
+**Category:** status
 **Kind:** primitive
 
 > A placeholder in the shape of the content that is loading — text lines, a control, an avatar, a block — so the layout is in place before the data arrives.

package/src/components/skeleton/examples/with-crossfade.tsx

@@ -5,9 +5,9 @@ import * as React from "react";
 import styles from "./examples.module.css";
 
 const PAYMENTS = [
-  { id: "p1", payer: "ООО «Гранит»", amount: "₽ 94 750" },
-  { id: "p2", payer: "ИП Орлов Д. С.", amount: "₽ 18 000" },
-  { id: "p3", payer: "АО «Альфа Медиа»", amount: "₽ 380 000" },
+  { id: "p1", payer: "ООО «Гранит»", amount: "94 750 ₽" },
+  { id: "p2", payer: "ИП Орлов Д. С.", amount: "18 000 ₽" },
+  { id: "p3", payer: "АО «Альфа Медиа»", amount: "380 000 ₽" },
 ];
 
 const LOAD_MS = 1500;

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

@@ -117,6 +117,8 @@ same height and type.
 
 ## Layout & spacing
 - The panel is a flush Popover as wide as the toolbar; every section is a full-width row with its own padding (`--prime-space-3` × `--prime-space-4`, footer `--prime-space-2` × `--prime-space-4`), Dividers run edge to edge, the field label column is `--prime-space-24`.
+- The toolbar is one row of controls (`--prime-space-2` gap): the filter button keeps its width, the search grows from 9rem (`--prime-space-24` × 1.5). When less than 9rem is left beside the button, the search moves under it at full width; every row stays one control high.
+- Chips are Badges of the toolbar tier on the badge scale (`xs` → `s`), so a tag sits lower than the controls above it; «Добавить фильтр» is a tag of the same tier and «Сбросить все» a LinkButton with the tag's text size.
 - Values and chips wrap with `--prime-space-2` gaps; «Сбросить все» is pushed to the end.
 - The root is a flex column (`--prime-space-3`): Toolbar, then Chips.
 

package/src/components/sparkline/COMPONENT.md

@@ -0,0 +1,98 @@
+# Sparkline
+
+**Category:** data-display
+**Kind:** primitive
+
+> A small line chart with its headline — the latest value, its change against the point before and its date — where 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.
+- A detail page header that shows how a value moved.
+
+## When not to use
+- Exact values on axes, several series, or a legend → a full chart library; Sparkline has no axes.
+- Progress toward a goal → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A list of values to compare → [DataTable](../data-table/COMPONENT.md).
+
+## Import
+```tsx
+import { Sparkline, type SparklinePoint } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Sparkline              <div>; the headline and the chart
+├─ 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 svg line and area
+   └─ cursor           guide line and dot of the shown point (aria-hidden)
+```
+
+## API
+
+<!-- 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 chart; the chart is a `role="slider"` that picks a point.
+
+| 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. |
+| `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the headline 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. |
+
+## Variants
+No variants: one accent line on the surface it sits on. Put it in a `Card` for a dashboard tile.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| at rest | — | the latest point; the value rolls its digits when `data` changes |
+| scrubbing | pointer or touch over the plot | `data-scrubbing` on the root; the cursor and the headline follow the pointer with no easing (direct manipulation), digits change in place |
+| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`; the cursor glides to the point (`base` · emphasized) |
+| settle | pointer leaves, touch ends, focus leaves | the cursor glides back to the latest point |
+| new series | a new `data` array | the line cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+
+## 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.
+- In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
+- Below 320 px the value row wraps the change badge under the value.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `←` · `→` | Previous or next point. |
+| `Home` · `End` | First or last point. |
+| `Tab` | Focuses the chart; leaving focus returns to the latest point. |
+
+### ARIA
+- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`).
+- The headline with the latest value and change reads as plain text.
+- The change carries a sign and an arrow, never color alone.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `point` | `"{label}: {value}"` | Spoken value of the chosen point (`aria-valuetext`); `{label}` and `{value}` are 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`. |
+| [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`. |
+
+## 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`.
+
+## Related
+- **Built from:** [Badge](../badge/COMPONENT.md)
+- **See also:** [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -0,0 +1,13 @@
+/* Layout of the Sparkline scenarios: semantic tokens only. */
+
+/* A dashboard card's width: the chart takes the card width. */
+.card {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* The period switch above the chart inside the card body. */
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+}

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

@@ -0,0 +1,27 @@
+/** Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const MONTHS = ["янв", "фев", "мар", "апр", "мая", "июн", "июл", "авг", "сен", "окт", "ноя", "дек"];
+
+/** Daily revenue, 9 September — 8 October 2026. */
+const REVENUE: SparklinePoint[] = Array.from({ length: 30 }, (_, i) => {
+  const day = new Date(2026, 8, 9 + i);
+  return {
+    label: `${day.getDate()} ${MONTHS[day.getMonth()]}`,
+    value: Math.round(260 + 40 * Math.sin(i / 3.2) + 28 * Math.sin(i / 1.4 + 1) + i * 2.6) * 1000,
+  };
+});
+
+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} />
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,46 @@
+/** Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. */
+import { Card, SegmentedControl, Sparkline, type SparklinePoint } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Period = "week" | "month" | "quarter";
+
+const series = (labels: string[], base: number, swing: number): SparklinePoint[] =>
+  labels.map((label, i) => ({
+    label,
+    value: Math.round((base + swing * Math.sin(i / 1.7) + (swing / 4) * i) / 100) * 100,
+  }));
+
+const SERIES: Record<Period, SparklinePoint[]> = {
+  week: series(["2 окт", "3 окт", "4 окт", "5 окт", "6 окт", "7 окт", "8 окт"], 41_000, 6_000),
+  month: series(
+    ["сен, 1 нед.", "сен, 2 нед.", "сен, 3 нед.", "сен, 4 нед.", "окт, 1 нед."],
+    286_000,
+    32_000,
+  ),
+  quarter: series(["авг", "сен", "окт"], 1_240_000, 160_000),
+};
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklinePeriodExample() {
+  const [period, setPeriod] = React.useState<Period>("month");
+
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body className={styles.body}>
+        <SegmentedControl.Root
+          value={period}
+          onValueChange={(value) => setPeriod(value as Period)}
+          aria-label="Период"
+        >
+          <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+          <SegmentedControl.Item value="quarter">Квартал</SegmentedControl.Item>
+        </SegmentedControl.Root>
+        <Sparkline data={SERIES[period]} label="Новые заказы" formatValue={formatRubles} />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/spinner/COMPONENT.md

@@ -1,6 +1,6 @@
 # Spinner
 
-**Category:** feedback
+**Category:** status
 **Kind:** primitive
 
 > An indeterminate loading indicator: a ring with a gap that turns while a request runs.