prime-ui-kit 0.14.0 → 0.16.0

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

@@ -0,0 +1,49 @@
+/** Campaign limits submitted with the form by `name`, a calm note confirms the save — `name`, `label`. */
+import { Button, Fieldset, Slider, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SliderInFormExample() {
+  const [saved, setSaved] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    setSaved(
+      `Сохранено: показов в день — ${data.get("dailyCap")}, ставка — ${data.get("bidShare")}%.`,
+    );
+  };
+
+  return (
+    <form className={styles.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 ? (
+          <Typography as="p" variant="body-s" tone="secondary" role="status">
+            {saved}
+          </Typography>
+        ) : null}
+      </div>
+    </form>
+  );
+}

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

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

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

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

package/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;

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

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

package/dist/skill/reference/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/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. |
 
@@ -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.
@@ -173,7 +177,7 @@ Put it in a `Card` for a dashboard tile.
 | [compact.tsx](examples/compact.tsx) | Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, scrubbing shows the month in a tooltip, the label is the chart's accessible name — `layout`, `label`. |
 | [signed-bars.tsx](examples/signed-bars.tsx) | Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. |
 | [curve.tsx](examples/curve.tsx) | The same month of active users as a smooth curve, straight segments and steps — `curve`. |
-| [reference.tsx](examples/reference.tsx) | Checkout conversion against its plan: a dashed reference line, the scale from zero and the change over the whole period — `reference`, `min`, `change`. |
+| [reference.tsx](examples/reference.tsx) | Checkout conversion against its plan: a dashed reference line, the scale from zero to 5% and the change over the whole period — `reference`, `min`, `max`, `change`. |
 | [gaps.tsx](examples/gaps.tsx) | Daily API requests with days the collector was down: the line breaks over a missing day and the headline says there is no data — `data`, `labels`. |
 | [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`, `summary`. |
 
@@ -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/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/reference.tsx

@@ -1,4 +1,4 @@
-/** Checkout conversion against its plan: a dashed reference line, the scale from zero and the change over the whole period — `reference`, `min`, `change`. */
+/** Checkout conversion against its plan: a dashed reference line, the scale from zero to 5% and the change over the whole period — `reference`, `min`, `max`, `change`. */
 import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -27,6 +27,7 @@ export default function SparklineReferenceExample() {
           label="Конверсия оформления заказа"
           reference={PLAN}
           min={0}
+          max={5}
           change="first"
           formatValue={formatPercent}
           labels={{ reference: "План: {value}" }}

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/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";