prime-ui-kit 0.15.0 → 0.16.0

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

@@ -59,11 +59,11 @@ The toolbar and the chips are separate parts so a page can put them in different
 | `search` | `string` | — | Search text, controlled. |
 | `defaultSearch` | `string` | `""` | Initial search text, uncontrolled. |
 | `onSearchChange` | `(search: string) => void` | — | Every keystroke; debounce in the owner when it asks a server. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the filter button, the search, the tags and the panel. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the filter button, the search, the tags and the panel. Without it the tier of its host, else `m`. |
 | `collapsedLimit` | `number` | `12` | Values of one field shown before «Ещё N» (not while searching). |
 | `labels` | `Partial<SmartFilterLabels>` | — | Built-in strings, see Labels. |
-| `className` | `string` | — | Class on the root. |
 | `children` | `ReactNode` | — (required) | `SmartFilter.Toolbar` and `SmartFilter.Chips`, anywhere inside. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | — | `className` and the other div attributes. |
 
 ### SmartFilter.Toolbar
 `ref` → `HTMLDivElement`. A `<div>`: the search Input first, then the filter Button (a count Badge while filters apply); the anchor of the panel, a flush Popover.
@@ -80,10 +80,12 @@ The toolbar and the chips are separate parts so a page can put them in different
 |---|---|---|---|
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the chips row. |
 
-### SmartFilterField
+### Types
+
+#### `SmartFilterField`
 One entry of `fields`: data, not a part. Selected values missing from `options` stay visible so they can be removed.
 
-| Prop | Type | Default | Description |
+| Field | Type | Default | Description |
 |---|---|---|---|
 | `key` | `string` | — (required) | Key of the field in the value. |
 | `label` | `string` | — (required) | Field name in the panel and the chips. |
@@ -91,10 +93,24 @@ One entry of `fields`: data, not a part. Selected values missing from `options`
 | `options` | `{ value: string; label: string; icon?: ReactNode; group?: string }[]` | — (required) | `options` fields: values; `icon` is a decorative kit Icon before the label; values with one `group` stay together under that heading, groups in the order they first appear. |
 | `finite` | `boolean` | `true` | `options` fields: a fixed set — hiding every value is refused. `false` for an open set (services, users). |
 | `multiple` | `boolean` | `true` | `options` fields: many values at once. `false` — one value and no hiding: a press picks only that value, a second press clears it (an API that takes one value per field). |
-| `formatValue` | `(value: number) => string` | `Russian digit groups` | `range` fields: a bound in the chip («1 000 ₽»). |
+| `formatValue` | `(value: number) => string` | Russian digit groups | `range` fields: a bound in the chip («1 000 ₽»). |
+
+### Functions
+
+#### `matchesSmartFilter(entry, item)`
+`(entry: SmartFilterFieldValue \| undefined, item: string \| number \| Date \| null \| undefined) => boolean`
+
+Checks one item's value against a field's entry on the client; an empty entry matches everything.
+
+#### `resolveSmartFilterValues(entry, all)`
+`(entry: SmartFilterFieldValue \| undefined, all: readonly string[]) => string[]`
 
-### matchesSmartFilter · resolveSmartFilterValues · isSmartFilterRange
-Helpers. `matchesSmartFilter(entry, item)` checks one item's value on the client. `resolveSmartFilterValues(entry, all)` turns a fixed field into the list of values to ask a server for. `isSmartFilterRange(entry)` tells a range from a selection.
+Turns a fixed field's entry into the list of values to ask a server for.
+
+#### `isSmartFilterRange(entry)`
+`(entry: SmartFilterFieldValue \| undefined) => entry is SmartFilterRange<number> \| SmartFilterRange<Date>`
+
+Tells a range entry from a selection.
 
 ## Variants
 
@@ -141,7 +157,7 @@ same height and type.
 |---|---|---|
 | closed / open | filter button, search focus | button `aria-expanded`; the panel is a Popover below the toolbar |
 | value neutral | no selection | gray Badge |
-| value shown | press | blue Badge, `aria-pressed="true"`, `data-mode="include"` |
+| value shown | press | the Badge's pressed (selected) look, `aria-pressed="true"`, `data-mode="include"` |
 | value hidden | «−», Alt+click, Shift+Enter | red Badge with «НЕ», `data-mode="exclude"`; its «−» stays visible and unhides |
 | cannot hide | last value of a `finite` field | the «−» is disabled |
 | searching | `search` | only matching values, the match in `accent-text` (a `<mark>`); fields with nothing found in a compact EmptyPage; the «Искать» row closes the panel |
@@ -151,10 +167,10 @@ same height and type.
 | no filters | empty value | no count on the button, no Chips |
 
 ## 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 search first, growing from 9rem (`--prime-space-24` × 1.5), then the filter button at its own width. When less than 9rem is left beside the button, the button moves under the search; every row stays one control high. Search first, filter second — the active filters (`SmartFilter.Chips`) sit right under them.
+- 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`; a row narrower than 24rem stacks the label over the values (an intrinsic wrap, no breakpoint).
+- The toolbar is one row of controls (`--prime-space-2` gap): the search first, growing from 9rem (`--prime-space-24` × 1.5), then the filter button at its own width. When less than 9rem is left beside the button, the button moves under the search; every row stays one control high. Search first, filter second — the active filters (`SmartFilter.Chips`) sit under them.
 - 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.
+- Values and chips wrap with `--prime-space-2` gaps; «Сбросить все» is pushed to the end. The chips row rises in with the first filter and closes up in place with the last (`partPresence`).
 - Option groups stack `--prime-space-3` apart, a caption `--prime-space-1` above each group's values. A range row holds two equal Inputs with a dash between them, centred on the field label.
 - While typing a search a range row stays only when its field name matches.
 - The root is a flex column (`--prime-space-3`): Toolbar, then Chips.
@@ -162,6 +178,8 @@ same height and type.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the panel values and their «−» (shown on focus). |
@@ -170,6 +188,8 @@ same height and type.
 | `Enter` · `Escape` | In the search, close the panel. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The filter button has `aria-expanded` and `aria-haspopup="dialog"`; the panel is a non-modal `role="dialog"` named by a visually hidden `labels.filter` title.
 - Values are toggle buttons with `aria-pressed`; the «−» has its own name (`labels.hideValue` / `labels.unhideValue`); a hidden value carries the «НЕ» text, so meaning is never in color alone.
 - Fields with nothing found are announced through `role="status"`.
@@ -231,5 +251,5 @@ same height and type.
 - Cutting the «−» and the search off on the client for a one-value API → `multiple: false` and `searchable={false}`.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Input](../input/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Typography](../typography/COMPONENT.md), Icon (`action.search`, `action.filter`, `action.add`, `nav.chevronDown`)
+- **Built from:** [Button](../button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Input](../input/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Typography](../typography/COMPONENT.md), Icon (`action.search`, `action.filter`, `action.add`, `nav.chevronDown`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [PageToolbar](../page-toolbar/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/smart-filter/examples/examples.module.css

@@ -8,27 +8,6 @@
   min-width: 0;
 }
 
-/* sizes.tsx: one tier per block, its caption right under it, blocks apart. */
-.sizes {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-8);
-  width: 100%;
-  min-width: 0;
-}
-
-.size {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-  min-width: 0;
-}
-
-.size > :first-child {
-  align-self: stretch;
-}
-
 /* A request row in the list: method, route (takes the room), service. */
 .request {
   display: flex;

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

@@ -1,6 +1,7 @@
 /** 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,
+  formatDateValue,
   isSmartFilterRange,
   matchesSmartFilter,
   SmartFilter,
@@ -62,7 +63,7 @@ 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);
+  bound instanceof Date ? formatDateValue(bound) : String(bound);
 
 /** The query a server gets: a range becomes `key_from` / `key_to`, a selection its included values. */
 function toQuery(value: SmartFilterValue) {

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

@@ -1,8 +1,6 @@
 /** Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. */
 import { SmartFilter, type SmartFilterField, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const FIELDS: SmartFilterField[] = [
   {
     key: "method",
@@ -16,9 +14,9 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function SmartFilterSizesExample() {
   return (
-    <div className={styles.sizes}>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.size}>
+        <div key={size}>
           <SmartFilter.Root fields={FIELDS} size={size} defaultValue={ONLY_GET}>
             <SmartFilter.Toolbar />
             <SmartFilter.Chips />

package/src/components/sparkline/COMPONENT.md

@@ -57,13 +57,13 @@ compact:               the plot alone (no head, no value row); loading — the p
 | `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`. |
+| `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, the tooltip, the reference description 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. |
 
@@ -139,6 +139,8 @@ Put it in a `Card` for a dashboard tile.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `←` · `→` · `↓` · `↑` | Previous or next point: `←` / `↓` back, `→` / `↑` forward, as on a slider. |
@@ -147,6 +149,8 @@ Put it in a `Card` for a dashboard tile.
 | `Escape` | Hides the tooltip and returns the headline to rest. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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.
@@ -190,5 +194,5 @@ Put it in a `Card` for a dashboard tile.
 - 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), `ChartTooltip` (the chart tooltip shared with ChartFrame)
+- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow), `ChartTooltip` (the chart tooltip shared with ChartFrame), [ScrollContainer](../scroll-container/COMPONENT.md) (the tooltip's floating panel)
 - **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/examples.module.css

@@ -2,7 +2,7 @@
 
 /* A dashboard card's width: the chart takes the card width. */
 .card {
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* compact: a client list, the name and its trend on one line per client. */

package/src/components/sparkline/examples/signed-bars.tsx

@@ -14,8 +14,8 @@ const PROFIT: SparklinePoint[] = [
   { label: "авг", value: 280_000 },
   { label: "сен", value: 470_000 },
   { label: "окт", value: 390_000 },
-  { label: "ноя", value: 0 },
-  { label: "дек", value: 0 },
+  { label: "ноя", value: null },
+  { label: "дек", value: null },
 ];
 
 /** October is the current month: November and December are still empty. */

package/src/components/spinner/COMPONENT.md

@@ -6,7 +6,7 @@
 > An indeterminate loading indicator: the kit ring with the share unknown — a quarter arc turning on a faint track while a request runs.
 
 ## When to use
-- A region is busy and has no content shape to hold (a running job, a request with no layout yet).
+- Something is busy and has no content shape to hold (a running job on a status line, a request with no layout yet).
 - A status line next to text («Загружаем счета…»).
 - Inside a kit component that shows loading (it is the kit's one spinner).
 
@@ -51,7 +51,7 @@ Spinner          <span role="status">; size and tone
 |---|---|---|---|
 | `default` | the color of the surrounding text | inside text, buttons, rows | yes |
 | `secondary` | `text-secondary` | a status line in secondary text | |
-| `muted` | `text-muted` | a loading region on a card | |
+| `muted` | `text-muted` | a quiet status line under content | |
 | `accent` | `accent-text` | the one loading spot that should draw the eye | |
 | `success` · `warning` · `danger` | the status `*-text` color | loading inside a status block of that tone | |
 
@@ -61,29 +61,34 @@ Spinner          <span role="status">; size and tone
 | `xs` | 14px | dense rows, inside `xs` controls | |
 | `s` | 16px | next to `body-s` text | |
 | `m` | 20px | standalone next to `body-m` text | |
-| `l` | 24px | a loading card or panel | |
-| `xl` | 32px | a loading page region | |
+| `l` | 24px | next to `body-l` or a title | |
+| `xl` | 32px | a running job with nothing to show yet, next to its explanation | |
 | — (omitted) | the host's icon size, else the control tier (16 on `m`) | inside a kit control or next to its text | yes |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
+| appearing | mounted | fades in over `fast` (`internal/enterMotion`), so a spinner that comes and goes never blinks |
 | spinning | mounted | the ring turns at a constant speed (`--prime-motion-loop × 3` per turn, linear) |
 | reduced motion | `prefers-reduced-motion` | the ring keeps turning, twice as slow (`--prime-motion-loop × 6` per turn) and linear: a loading cue is information, so the token is not zeroed |
 | size / tone | `size`, `tone` | `data-size` (the explicit size, else the host control tier, else `m`), `data-tone` (only for a non-default tone) |
 
 ## Layout & spacing
 - The ring fills the icon box: a stroke of two border widths (the line weight, an icon's stroke) — a round-capped quarter arc in the tone color over an 18% track of it; `inline-flex`, `vertical-align: middle`. The svg turns as a whole (a compositor transform).
-- Next to text: one row, `align-items: center`, gap = the tier gap (`--prime-control-m-gap`).
-- In a loading region: centered in the region with its explanation under it, gap `--prime-space-3`.
+- Next to text: one row, `align-items: center`, 8px apart (the `m` tier gap).
+- A region whose content has a shape (a card, a list) shows a `Skeleton` of that shape, not a spinner.
 - Render the real layout around it; never a full-screen overlay of spinners.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `role="status"` with a visually hidden `labels.loading`, so screen readers learn that something is loading.
 - When the host already announces it is busy (`aria-busy` on a button or a region), pass `aria-hidden="true"`.
 - Under `prefers-reduced-motion` the ring keeps turning, slower and linear, so the loading cue stays readable.
@@ -98,17 +103,18 @@ No keyboard interaction.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A loading status next to a short explanation; the spinner takes the text color. |
+| [overview.tsx](examples/overview.tsx) | A loading status next to a short explanation; the spinner takes the text color and names the wait — `labels`. |
 | [variants.tsx](examples/variants.tsx) | Every ring color; `default` follows the surrounding text — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size on the icon scale, 14 to 32 px — `size`. |
-| [loading-region.tsx](examples/loading-region.tsx) | A card that loads its content: the region says it is busy and the spinner stays hidden from screen readers — `aria-hidden`. |
 
 ## Mistakes
 - A hand-made spinner (`@keyframes spin` on a bordered circle) → use `Spinner`.
 - A `Spinner` next to a `loading` Button → the button already shows one.
 - Both `aria-busy` on the region and a spoken spinner inside → add `aria-hidden="true"` to the spinner.
 - A spinner for a known progress → ProgressBar / ProgressCircle.
+- A spinner in a card or a list while its content loads → a `Skeleton` in the content's shape.
+- Fading a conditional spinner in by hand → the spinner fades itself in.
 
 ## Related
-- **Built from:** `internal/ring` (the ring drawing, shared with ProgressCircle and the circle Button)
+- **Built from:** `internal/ring` (the ring drawing, shared with ProgressCircle and the circle Button), `internal/enterMotion` (the fade-in), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Skeleton](../skeleton/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md), [Button](../button/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

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

@@ -1,20 +1,8 @@
 /* Layout of the Spinner scenarios: semantic tokens only. */
 
-/* overview.tsx: spinner and text in one line, icon → text gap of the m tier. */
+/* overview.tsx: spinner and text in one line, 8px apart (the m tier gap). */
 .status {
   display: inline-flex;
   align-items: center;
-  gap: var(--prime-control-m-gap);
-}
-
-/* loading-region.tsx: the Card's size and its centered body. */
-.region {
-  width: min(100%, var(--prime-modal-width-s));
-  min-height: calc(var(--prime-space-24) * 2);
-}
-
-.loading {
-  align-items: center;
-  justify-content: center;
-  gap: var(--prime-space-3);
+  gap: var(--prime-space-2);
 }

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

@@ -1,4 +1,4 @@
-/** A loading status next to a short explanation; the spinner takes the text color. */
+/** A loading status next to a short explanation; the spinner takes the text color and names the wait — `labels`. */
 import { Spinner, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/stepper/COMPONENT.md

@@ -3,7 +3,7 @@
 **Category:** navigation
 **Kind:** navigation
 
-> Steps of a multi-step process with pending, active, completed and danger statuses.
+> Steps of a multi-step process with pending, current, completed and danger statuses.
 
 ## When to use
 - Checkout, onboarding and setup wizards where the user moves through ordered steps.
@@ -23,13 +23,12 @@ import { Stepper } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Stepper.Root                 <ol>; current step; chevrons between horizontal items
+Stepper.Root                 <ol>; current step; chevrons between horizontal items, at the end of vertical rows with `arrows`
 └─ Stepper.Item              <li> with a <button>; a direct child of Root (index = order)
-   ├─ Stepper.Indicator      circle: number, check when completed, or custom content
-   ├─ Stepper.Content        text column
-   │  ├─ Stepper.Title       step name
-   │  └─ Stepper.Description muted support text
-   └─ Stepper.Arrow          trailing chevron for vertical rows that open a page or panel
+   ├─ Stepper.Indicator      circle: number, check when completed, danger mark, or custom content
+   └─ Stepper.Content        text column
+      ├─ Stepper.Title       step name
+      └─ Stepper.Description muted support text
 ```
 
 ## API
@@ -37,34 +36,36 @@ Stepper.Root                 <ol>; current step; chevrons between horizontal ite
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Stepper.Root
-`ref` → `HTMLOListElement`. `<ol>` of items; owns the current step, numbers the items and adds chevrons between horizontal ones.
+`ref` → `HTMLOListElement`. `<ol>` of items; owns the current step, numbers the items and draws the chevrons between horizontal ones and, with `arrows`, at the end of vertical rows.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `number` | — | Current step, 0-based (controlled). |
 | `defaultValue` | `number` | `0` | Initial step (uncontrolled). |
 | `onValueChange` | `(index: number) => void` | — | Called with the index of the clicked item. |
-| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Column of rows, or a row with chevrons that stacks below a 480px container. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Indicator 20 · 24 · 28 · 32 · 36, title in the control text of the tier. |
+| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Column of rows, or one row with chevrons (steps shrink and wrap their titles) that stacks below a 480px container. |
+| `arrows` | `boolean` | `false` | Every vertical row ends with a chevron: each step opens a page or panel. Horizontal steps already have their chevrons. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Indicator 20 · 24 · 28 · 32 · 36, title in the control text of the tier. Without it the tier of its host, else `m`. |
+| `labels` | `Partial<StepperLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `Stepper.Item`s as direct children (an array from `map` is fine). |
 | `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "defaultValue" \| "onChange">` | — | `aria-label`, `className` and the other list attributes. |
 
 ### Stepper.Item
-`ref` → `HTMLButtonElement`. One step: an `<li>` with a `<button>` (and, between horizontal steps, the decorative chevron in front of it); `aria-current="step"` when active.
+`ref` → `HTMLButtonElement`. One step: an `<li>` with a `<button>` (and, between horizontal steps, the decorative chevron in front of it); `aria-current="step"` on the current one; a completed or danger step adds its status to its name.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `status` | `"pending" \| "active" \| "completed" \| "danger"` | — | Overrides the status derived from `value` (before → `completed`, equal → `active`, after → `pending`). |
+| `status` | `"pending" \| "current" \| "completed" \| "danger"` | — | Overrides the status derived from `value` (before → `completed`, equal → `current`, after → `pending`). |
 | `disabled` | `boolean` | — | The item cannot be selected. |
-| `children` | `ReactNode` | — | `Stepper.Indicator`, `Stepper.Content`, optional `Stepper.Arrow`. |
+| `children` | `ReactNode` | — | `Stepper.Indicator` and `Stepper.Content`. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">` | — | `onClick` (runs first; `preventDefault()` stops the selection), `className` and the other button attributes. |
 
 ### Stepper.Indicator
-`ref` → `HTMLSpanElement`. The circle (`aria-hidden`): the item number, or a check when completed.
+`ref` → `HTMLSpanElement`. The circle (`aria-hidden`): the item number, a check when completed, the danger mark on a danger step; a status change cross-fades the glyph.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — | Replaces the default content, e.g. `<Icon name="status.danger" />`. |
+| `children` | `ReactNode` | — | Replaces the default content, e.g. `<Icon name="status.info" />`. |
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
 
 ### Stepper.Content
@@ -81,20 +82,18 @@ Stepper.Root                 <ol>; current step; chevrons between horizontal ite
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
 
-### Stepper.Arrow
-`ref` → `SVGSVGElement`. Trailing chevron (`aria-hidden`) for vertical items that open a page or panel.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `…rest` | `Omit<SVGAttributes<SVGSVGElement>, "children">` | — | `className` and the other svg attributes. |
-
 ## Variants
 
 ### orientation
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `vertical` | full-width rows (indicator · text · optional arrow); hover `fill-subtle`, active row on `fill-subtle`, danger row on `danger-soft` | side columns of wizards, step lists with descriptions | yes |
-| `horizontal` | items in a row with placeholder-colored chevrons between them; hover → primary text; below a 30rem container the items stack one per row and chevrons hide | checkout headers with short step names | |
+| `vertical` | full-width rows (indicator · text · the chevron with `arrows`); hover `fill-subtle`, the current row on `fill-subtle`, danger row on `danger-soft` | side columns of wizards, step lists with descriptions | yes |
+| `horizontal` | one row of items with placeholder-colored chevrons between them; a cramped step wraps its title, the row never wraps; hover → primary text; below a 30rem container the items stack one per row and chevrons hide | checkout headers with short step names | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `arrows` | every vertical row ends with a placeholder-colored chevron (`aria-hidden`); horizontal steps keep their separators only | each vertical step opens a page or panel | off |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -111,66 +110,76 @@ Title uses the control text of the tier, Description the hint text of the tier.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `pending` | `fill-muted` circle with secondary number, secondary text | steps after the current one | derived |
-| `active` | accent circle with a `space-1` `accent-soft` halo, primary text | the current step | derived |
-| `completed` | `accent-soft` circle with an accent check (`Icon action.check`), primary text | finished steps | derived |
-| `danger` | horizontal: `danger-soft` circle; vertical: solid danger circle on a `danger-soft` row; danger text | a step that needs attention | |
+| `current` | accent circle with a `space-1` `accent-soft` halo, primary text | the current step | derived |
+| `completed` | `accent-soft` circle with an accent check (`Icon action.check`), primary text; `labels.completed` added to the name | finished steps | derived |
+| `danger` | the danger mark (`Icon status.danger`) — horizontal: on a `danger-soft` circle; vertical: on a solid danger circle in a `danger-soft` row; danger text; `labels.danger` added to the name | a step that needs attention | |
 
-Derive statuses from `value`; set `status="danger"` only on the failing step with an indicator that is not a number (`<Icon name="status.danger" />`); disable steps the user cannot reach yet. Avoid `Stepper.Arrow` in horizontal mode (the root adds chevrons) and several `active` steps.
+Derive statuses from `value`; set `status="danger"` only on the failing step; disable steps the user cannot reach yet. Never mark several steps `current`.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| status | `value` or `status` | `data-status` on the button and the indicator; `aria-current="step"` on the active item |
+| status | `value` or `status` | `data-status` on the button and the indicator; `aria-current="step"` on the current item; a visually hidden status after the name of a completed or danger step |
 | disabled | `disabled` | native `disabled`, `data-disabled="true"`, `text-disabled`, muted indicator without halo |
-| hover / active | pointer | vertical `fill-subtle` / `fill-subtle-active`; horizontal text → primary; press scale |
+| hover / press | pointer | vertical `fill-subtle` / `fill-subtle-active`; horizontal text → primary; press scale |
 | focus-visible | keyboard | outer focus ring |
 
 Root attributes: `data-orientation`, `data-size`. Uncontrolled (`defaultValue`) clicks still select items.
 
-Motion: a status change moves the indicator's fill, color and halo over `base`; the row fill and text color change over `fast`; press scales the step to `--prime-motion-press-scale`. Under reduced motion the indicator changes at once.
+Motion: a status change fades the indicator's fill, color and halo over `base` and cross-fades its glyph (number ⇄ check ⇄ danger mark); the row fill and text color change over `fast`; press scales the step to `--prime-motion-press-scale` (the kit press). Under reduced motion the press does not scale and the glyph only fades.
 
 ## Layout & spacing
 - The root is a size container (`inline-size: 100%`): give it a definite width, a shrink-wrapped parent collapses it.
-- Wizard: stepper column and form side by side with `gap: var(--prime-space-8)`, stacking on narrow widths.
-- Vertical rows are separated by `var(--prime-space-1)` (`var(--prime-space-2)` at `size="xl"`); the same value is the row gap of a wrapping horizontal stepper.
+- Wizard: stepper column and form side by side with the page gap between groups, stacking on narrow widths.
+- Vertical rows are separated by `var(--prime-space-1)` (`var(--prime-space-2)` at `size="xl"`); the same value is the row gap of a horizontal stepper stacked in a narrow container.
+- On a coarse pointer a step is at least the touch target high.
 - Horizontal steps and their chevrons sit 8 · 12 · 16 · 20 · 24 apart (xs → xl); below a 30rem (480px) container each step takes its own full-width row with the vertical row padding.
 - Indicator → text gap 8 (xs, s) · 12 (m, l) · 16 (xl); titles are medium weight and wrap long words.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus between items; a disabled one is skipped. |
 | `Enter` · `Space` | Selects the item. |
 
 ### ARIA
-- Semantic `<ol>`; each item is a `<button>` inside an `<li>`; the active one has `aria-current="step"`.
-- Separators, indicator and arrow are `aria-hidden`; the name comes from Title (and Description).
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- Semantic `<ol>`; each item is a `<button>` inside an `<li>`; the current one has `aria-current="step"`.
+- Separators, indicator and arrows are `aria-hidden`; the name comes from Title and Description, and a completed or danger step adds `labels.completed` or `labels.danger` to it.
 - Give the `<ol>` an `aria-label` when there are several steppers on a page.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `completed` | `"пройден"` | Spoken after the name of a completed step; the check is only seen. |
+| `danger` | `"требует внимания"` | Spoken after the name of a step that needs attention; its colour and glyph are only seen. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Steps of a process: done ones get a check, the current one is highlighted — `defaultValue`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: indicator 20 to 36 px, title in the control text of the tier — `size`. |
-| [states.tsx](examples/states.tsx) | Statuses that come from the server, a failed step with its own indicator and a locked step — `status`, `disabled`. |
-| [with-icon.tsx](examples/with-icon.tsx) | Vertical rows that open a page or panel end with a chevron — `Stepper.Arrow`. |
+| [states.tsx](examples/states.tsx) | Statuses that come from the server, a failed step marked by a glyph and a locked step — `status`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | Vertical rows that open a page or panel end with a chevron — `arrows`. |
 | [orientation.tsx](examples/orientation.tsx) | A row of steps with chevrons between them above the content, and a column for a side panel — `orientation`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the current step: Back and Next move it, far steps stay locked until reached — `value`, `onValueChange`. |
-| [narrow.tsx](examples/narrow.tsx) | A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons. |
+| [narrow.tsx](examples/narrow.tsx) | A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons — `orientation`. |
 
 ## Mistakes
 - Wrapping `Stepper.Item` in another component or element → it must be a direct child of Root (it throws otherwise).
 - 1-based `value` → steps are 0-based.
 - Adding separators by hand in horizontal mode → every step already draws its chevron.
-- `status="error"` → the status is `danger`; give it an indicator that is not a number so it does not read by color only.
+- `status="error"` → the status is `danger`; its indicator shows the danger mark and its name says it, so it never reads by color only.
+- A chevron added by hand at the end of a vertical row → set `arrows` on the root.
+- `status="active"` → the step a person is on is `current`.
 
 ## Related
-- **Built from:** Icon (`action.check`, `nav.chevronRight`)
+- **Built from:** Icon (`action.check`, `status.danger`, `nav.chevronRight`), `internal/glyphSwap` (the indicator glyph), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [Pagination](../pagination/COMPONENT.md), [Timeline](../timeline/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md)

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

@@ -1,10 +1,5 @@
 /* Layout of the Stepper scenarios: semantic tokens only. */
 
-/* The stepper measures its own width (container query), so its wrapper needs one. */
-.wide {
-  width: 100%;
-}
-
 /* A side column for a vertical stepper (288px), with anything under it a group gap away. */
 .column {
   display: grid;
@@ -14,7 +9,7 @@
 
 /* A phone-width container (320px). */
 .narrow {
-  width: min(100%, calc(var(--prime-drawer-width-s) - var(--prime-space-10)));
+  width: min(100%, var(--prime-layout-min-width));
 }
 
 /* Back / Next under the stepper. */

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

@@ -1,4 +1,4 @@
-/** A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons. */
+/** A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons — `orientation`. */
 import { Stepper } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -1,19 +1,14 @@
 /** Every size tier: indicator 20 to 36 px, title in the control text of the tier — `size`. */
 import { Stepper, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 const STEPS = ["Аккаунт", "Команда", "Готово"];
 
 export default function StepperSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.wide}>
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
+        <div key={size}>
           <Stepper.Root orientation="horizontal" size={size} defaultValue={1}>
             {STEPS.map((title) => (
               <Stepper.Item key={title}>
@@ -24,8 +19,11 @@ export default function StepperSizesExample() {
               </Stepper.Item>
             ))}
           </Stepper.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }