prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/reference/components/slider/examples/in-form.tsx

@@ -1,5 +1,5 @@
 /** 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 { Button, Fieldset, Slider, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -16,24 +16,26 @@ export default function SliderInFormExample() {
   };
 
   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)}
-      />
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Fieldset aria-label="Лимиты кампании">
+        <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)}
+        />
+      </Fieldset>
       <div className={styles.actions}>
         <Button.Root type="submit">Сохранить лимиты</Button.Root>
         {saved ? (

package/dist/skill/reference/components/slider/examples/states.tsx

@@ -3,19 +3,23 @@ import { Slider } from "prime-ui-kit";
 
 export default function SliderStatesExample() {
   return (
-    <div>
+    <>
       <div>
-        <Slider label="min" showValue defaultValue={0} />
+        <div>
+          <Slider label="min" showValue defaultValue={0} />
+        </div>
+        <div>
+          <Slider label="max" showValue defaultValue={100} />
+        </div>
       </div>
       <div>
-        <Slider label="max" showValue defaultValue={100} />
+        <div>
+          <Slider label="invalid" showValue defaultValue={90} invalid />
+        </div>
+        <div>
+          <Slider label="disabled" showValue defaultValue={35} disabled />
+        </div>
       </div>
-      <div>
-        <Slider label="invalid" showValue defaultValue={90} invalid />
-      </div>
-      <div>
-        <Slider label="disabled" showValue defaultValue={35} disabled />
-      </div>
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/smart-filter/COMPONENT.md

@@ -13,10 +13,10 @@
 - An API that takes one value per field (`multiple: false`), a screen whose text search lives elsewhere (`searchable={false}`), values of different kinds in one field (`group`).
 
 ## When not to use
-- One field with a few options → use [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md) in the toolbar.
+- One field with a few options → use [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md) in the page's `Page.Tools`.
 - A search outside a table or list page (inside a picker, a settings section, a panel) → [Input](../input/COMPONENT.md) with a search icon. Over a table or list page the search is SmartFilter even with no fields yet (`fields={[]}`): it grows into filters without a rebuild.
 - Choosing values for a form field → use [TagSelect](../tag-select/COMPONENT.md).
-- One period that drives a whole dashboard → [Datepicker](../datepicker/COMPONENT.md) in the page toolbar; SmartFilter ranges filter rows of a list.
+- One period that drives a whole dashboard → [Datepicker](../datepicker/COMPONENT.md) in the page's `Page.Tools`; SmartFilter ranges filter rows of a list.
 
 ## Import
 ```tsx
@@ -30,7 +30,7 @@ import {
 
 ## Anatomy
 ```
-SmartFilter.Root                  state + context (flex column)
+SmartFilter.Root                  state + context, no DOM
 ├─ SmartFilter.Toolbar            [search Input (searchable)] [filter Button (count Badge)] — the anchor of the panel
 │  └─ panel                       flush Popover as wide as the toolbar; sections split by Dividers
 │     ├─ query row                ghost Button «Искать «text»» + Kbd ↵, while typing
@@ -41,14 +41,14 @@ SmartFilter.Root                  state + context (flex column)
 │     └─ footer                   hint · count · Reset Button
 └─ SmartFilter.Chips              applied filters as removable Badges · add / clear all Buttons
 ```
-The toolbar and the chips are separate parts so a page can put them in different places; both only need to be inside `Root`.
+The toolbar and the chips are separate parts so a page can put them in different places; both only need to be inside `Root`, which draws nothing of its own.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### SmartFilter.Root
-`ref` → `HTMLDivElement`. A `<div>` (flex column) with the state and the context; sets `data-size`.
+No DOM, no ref. The value, the search and the panel state shared by its parts; the host places the parts.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -59,14 +59,13 @@ 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. |
+| `children` | `ReactNode` | — (required) | `SmartFilter.Toolbar` and `SmartFilter.Chips`, anywhere inside — in a page bar the Root wraps `Page.Root`. |
 
 ### 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.
+`ref` → `HTMLDivElement`. A `<div>`: the search Input first, then the filter Button (a count Badge while filters apply), which shows only its icon and count when the search would get too little room; the anchor of the panel, a flush Popover.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -80,10 +79,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 +92,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 +156,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 |
@@ -149,19 +164,22 @@ same height and type.
 | range inverted | `from` above `to` | both bound inputs `aria-invalid` with the danger ring; nothing matches |
 | single value | `multiple: false` | at most one value `aria-pressed`; no «−» |
 | no filters | empty value | no count on the button, no Chips |
+| compact button | the toolbar narrower than the search's 9rem plus the labelled button (search and fields both present) | the button shows its icon and the count Badge; its name stays «Фильтр» (`aria-label` without filters, a visually hidden label with them) |
 
 ## 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 at least as wide as the toolbar (`width="min-trigger"`), by its content up to twice the panel minimum when the toolbar is narrow; 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 at least `--prime-space-24` (a longer name takes its own width, never breaking inside a word); 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 labelled button, the button shows only its icon and count and stays beside the search, which gives its width instead of wrapping. Every row stays one control high. The search and the button also stand alone: `searchable={false}` keeps the button, empty `fields` keep the search. 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.
+- The root draws nothing: its host places Toolbar and Chips. In a page bar the Toolbar goes in `Page.Tools` and the Chips in `Page.Chips`, with `SmartFilter.Root` around `Page.Root`; outside a page a host stacks them (a `Card.Body`, a form column).
 
 ## 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"`.
@@ -224,12 +244,12 @@ same height and type.
 - A fixed field marked `finite: false` → the user can hide every value and get an empty list.
 - Filtering the list with `includes` → use `matchesSmartFilter` (empty `include` is "any", `exclude` rejects; range bounds are inclusive, dates by whole days; an item with no value passes only an empty filter).
 - Sending `include` to a server for a hidden value of a fixed field → use `resolveSmartFilterValues` («hide» becomes «all except», `[]` means no filter).
-- Putting `Chips` outside `SmartFilter.Root` → every part needs the root.
+- Putting `Chips` outside `SmartFilter.Root` → every part needs the root; when Toolbar and Chips stand in different groups of a page bar, wrap `Page.Root` in it.
 - A second row of filter buttons next to the toolbar → fields belong in `fields`.
 - An amount or a period in its own Popover beside the toolbar → a `range` / `date-range` field; it gets a chip and the count.
 - One field split in two because its values are of different kinds → one field with `group` on the options.
 - 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`)
-- **See also:** [PageToolbar](../page-toolbar/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)
+- **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:** [Page](../../layout/page/COMPONENT.md) (`Page.Tools`, `Page.Chips`), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/dist/skill/reference/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;
@@ -51,6 +30,9 @@
 
 /* 320 px: the smallest supported viewport. */
 .narrow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
   width: min(100%, calc(var(--prime-space-20) * 4));
   min-width: 0;
 }

package/dist/skill/reference/components/smart-filter/examples/many-values.tsx

@@ -1,6 +1,8 @@
 /** 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`. */
 import { Icon, SmartFilter, type SmartFilterField } from "prime-ui-kit";
 
+import styles from "./examples.module.css";
+
 const SERVICES = [
   "access-policy",
   "billing",
@@ -41,13 +43,15 @@ const FIELDS: SmartFilterField[] = [
 
 export default function SmartFilterManyValuesExample() {
   return (
-    <SmartFilter.Root
-      fields={FIELDS}
-      collapsedLimit={8}
-      defaultValue={{ service: { include: [], exclude: ["events"] } }}
-    >
-      <SmartFilter.Toolbar />
-      <SmartFilter.Chips />
-    </SmartFilter.Root>
+    <div className={styles.stack}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        collapsedLimit={8}
+        defaultValue={{ service: { include: [], exclude: ["events"] } }}
+      >
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
   );
 }

package/dist/skill/reference/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/dist/skill/reference/components/smart-filter/examples/sizes.tsx

@@ -1,7 +1,5 @@
 /** 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";
+import { Card, SmartFilter, type SmartFilterField, Typography } from "prime-ui-kit";
 
 const FIELDS: SmartFilterField[] = [
   {
@@ -16,12 +14,16 @@ 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 />
+            <Card.Root>
+              <Card.Body>
+                <SmartFilter.Toolbar />
+                <SmartFilter.Chips />
+              </Card.Body>
+            </Card.Root>
           </SmartFilter.Root>
           <Typography as="span" variant="caption" tone="muted">
             {size}

package/dist/skill/reference/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. |
 
@@ -133,12 +133,15 @@ Put it in a `Card` for a dashboard tile.
 - 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.
+- On a head narrower than 20rem (a phone card) the date takes its own line under the title, which wraps instead of being cut; the break follows the width only, so a date that changes while scrubbing never moves it.
 - `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
 
 ### 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 +150,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 +195,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/dist/skill/reference/components/sparkline/examples/curve.tsx

@@ -1,5 +1,7 @@
 /** The same month of active users as a smooth curve, straight segments and steps — `curve`. */
-import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
 
 const USERS: SparklinePoint[] = [
   { label: "сен, 1 нед.", value: 1240 },
@@ -10,19 +12,22 @@ const USERS: SparklinePoint[] = [
   { label: "окт, 2 нед.", value: 1840 },
 ];
 
-const CURVES = ["smooth", "linear", "step"] as const;
+const CURVES = [
+  { curve: "smooth", title: "Плавная кривая" },
+  { curve: "linear", title: "Прямые отрезки" },
+  { curve: "step", title: "Ступени" },
+] 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>
+    <>
+      {CURVES.map(({ curve, title }) => (
+        <Card.Root key={curve} className={styles.card}>
+          <Card.Body>
+            <Sparkline data={USERS} label={title} curve={curve} />
+          </Card.Body>
+        </Card.Root>
       ))}
-    </div>
+    </>
   );
 }

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/components/sparkline/examples/states.tsx

@@ -12,19 +12,23 @@ const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
 
 export default function SparklineStatesExample() {
   return (
-    <div>
+    <>
       <div>
-        <Sparkline data={REVENUE} label="Выручка" formatValue={formatRubles} />
-        <Typography as="span" variant="caption" tone="muted">
-          data
-        </Typography>
+        <div>
+          <Sparkline data={REVENUE} label="Выручка" formatValue={formatRubles} />
+          <Typography as="span" variant="caption" tone="muted">
+            data
+          </Typography>
+        </div>
       </div>
       <div>
-        <Sparkline data={[]} label="Выручка" loading />
-        <Typography as="span" variant="caption" tone="muted">
-          loading
-        </Typography>
+        <div>
+          <Sparkline data={[]} label="Выручка" loading />
+          <Typography as="span" variant="caption" tone="muted">
+            loading
+          </Typography>
+        </div>
       </div>
-    </div>
+    </>
   );
 }

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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";