prime-ui-kit 0.7.13 → 0.9.1

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

@@ -0,0 +1,23 @@
+/** Every fill color; accent by default, semantic tones when the value carries meaning — `tone`. */
+import { Slider } from "prime-ui-kit";
+
+const TONE_ROWS = [
+  ["accent", "neutral", "success"],
+  ["warning", "danger", "info"],
+] as const;
+
+export default function SliderVariantsExample() {
+  return (
+    <>
+      {TONE_ROWS.map((row) => (
+        <div key={row[0]}>
+          {row.map((tone) => (
+            <div key={tone}>
+              <Slider tone={tone} label={tone} showValue defaultValue={60} />
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}

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

@@ -0,0 +1,182 @@
+# SmartFilter
+
+**Category:** selection
+**Kind:** composite
+
+> A filter bar for lists and tables: a filter button and a search with a panel of values, applied filters as removable tags, and a "show / hide" choice for every value.
+
+## When to use
+- Narrowing a list, table or log by several fields at once (service, method, status), where the user also types free text.
+- Filters where "everything except this" matters as much as "only this": every value can be shown or hidden.
+- Many values per field (dozens of services): the panel collapses them to «Ещё N» and narrows as the user types.
+
+## 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.
+- Only a text search → use [Input](../input/COMPONENT.md) with a search icon.
+- Choosing values for a form field → use [TagSelect](../tag-select/COMPONENT.md).
+- Filtering by a range (dates, price) → use [Datepicker](../datepicker/COMPONENT.md) or [Slider](../slider/COMPONENT.md); SmartFilter works on discrete values.
+
+## Import
+```tsx
+import { SmartFilter, matchesSmartFilter, resolveSmartFilterValues } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+SmartFilter.Root                  state + context (flex column)
+├─ SmartFilter.Toolbar            [filter Button (count Badge)] [search Input] — 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
+│     ├─ field rows               field label · value Badges with a «−» Badge.Action · «Ещё N» Badge
+│     ├─ no matches               compact EmptyPage naming the fields with nothing found
+│     └─ 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`.
+
+## 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`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `fields` | `readonly SmartFilterField[]` | — (required) | Fields of this screen, in display order; empty — only the search. Pass a stable reference. |
+| `value` | `SmartFilterValue` | — | Selection per field key, controlled: `{ include, exclude }` per field. |
+| `defaultValue` | `SmartFilterValue` | `{}` | Initial selection, uncontrolled. |
+| `onValueChange` | `(value: SmartFilterValue) => void` | — | The whole next value; keys of fields this root does not show are kept. |
+| `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. |
+| `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. |
+
+### SmartFilter.Toolbar
+`ref` → `HTMLDivElement`. A `<div>`: the filter Button (a count Badge while filters apply) and a search Input; the anchor of the panel, a flush Popover.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the toolbar. |
+
+### SmartFilter.Chips
+`ref` → `HTMLDivElement`. A `<div>` of applied filters as removable Badges with «Добавить фильтр» and «Сбросить все»; renders nothing without filters.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the chips row. |
+
+### 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 |
+|---|---|---|---|
+| `key` | `string` | — (required) | Key of the field in the value. |
+| `label` | `string` | — (required) | Field name in the panel and the chips. |
+| `options` | `{ value: string; label: string; icon?: ReactNode }[]` | — (required) | Values; `icon` is a decorative kit Icon before the label. |
+| `finite` | `boolean` | `true` | A fixed set: hiding every value is refused. `false` for an open set (services, users). |
+
+### matchesSmartFilter · resolveSmartFilterValues
+Helpers. `matchesSmartFilter(selection, value)` checks one value on the client (`include` empty = any, `exclude` rejects). `resolveSmartFilterValues(selection, all)` turns a fixed field into the list to ask a server for: «hide» becomes «all except», `[]` — no filter.
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | toolbar 28; value and filter tags 20 (tags never go below `s`) | dense table toolbars | |
+| `s` | toolbar 32; tags 20 | compact toolbars | |
+| `m` | toolbar 36; tags 24 | most pages | yes |
+| `l` | toolbar 40; tags 28 | roomier pages | |
+| `xl` | toolbar 48; tags 32 | hero search | |
+
+In the tag row «Добавить фильтр» is a pressable gray Badge of the tag tier and «Сбросить все» a
+neutral LinkButton with the tags' text size, at the end of the row: every element of the row has the
+same height and type.
+
+### field `finite`
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `true` | the «−» of the last shown value is disabled | fixed sets (method, status) | yes |
+| `false` | every value can be hidden | open sets (services, users) | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| 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 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 |
+| 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`.
+- Values and chips wrap with `--prime-space-2` gaps; «Сбросить все» is pushed to the end.
+- The root is a flex column (`--prime-space-3`): Toolbar, then Chips.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the panel values and their «−» (shown on focus). |
+| `Enter` · `Space` | Shows only this value; pressing again clears it. |
+| `Shift + Enter` | Hides the value. |
+| `Enter` · `Escape` | In the search, close the panel. |
+
+### ARIA
+- 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"`.
+- Every filter tag has a remove button named by `labels.remove`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `filter` | `"Фильтр"` | Filter button and panel name. |
+| `searchPlaceholder` | `"Поиск"` | Placeholder and name of the search. |
+| `clearSearch` | `"Очистить поиск"` | Name of the search clear button. |
+| `searchText` | `"Искать «{query}»"` | The text search row while typing. |
+| `noMatches` | `"{fields} — нет совпадений"` | Fields with nothing found while typing (compact EmptyPage). |
+| `hint` | `"Нажмите значение, чтобы показать только его; «−» справа — скрыть"` | Panel footer hint. |
+| `count` | `"Фильтров: {count}"` | Panel footer counter. |
+| `reset` | `"Сбросить"` | Panel footer reset. |
+| `more` | `"Ещё {count}"` | Collapsed values of a field. |
+| `add` | `"Добавить фильтр"` | Chips row: opens the panel. |
+| `clearAll` | `"Сбросить все"` | Chips row: clears every field. |
+| `showValue` | `"Показать только {value}"` | Title of a value. |
+| `hideValue` | `"Скрыть {value}"` | Name of the «−» of a value. |
+| `unhideValue` | `"Не скрывать {value}"` | Name of the «−» of a hidden value. |
+| `not` | `"НЕ"` | Prefix of a hidden value. |
+| `chipInclude` | `"{field}: {value}"` | Text of a «show» tag. |
+| `chipExclude` | `"{field}: не {value}"` | Text of a «hide» tag. |
+| `remove` | `"Убрать фильтр «{value}»"` | Name of a tag's remove button. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [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`. |
+| [narrow.tsx](examples/narrow.tsx) | A 320 px column: the search shrinks next to the filter button and the tags wrap under them — `size`. |
+
+## Mistakes
+- Creating `fields` inline on every render → pass a stable array (a module constant or `useMemo`).
+- 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).
+- Sending `include` to a server for a hidden value of a fixed field → use `resolveSmartFilterValues`.
+- Putting `Chips` outside `SmartFilter.Root` → every part needs the root.
+- A second row of filter buttons next to the toolbar → fields belong in `fields`.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Input](../input/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Typography](../typography/COMPONENT.md)
+- **See also:** [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

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

@@ -0,0 +1,48 @@
+/** A saved view sets the value from outside; the selection is read back as the list to ask the server for — `value`, `onValueChange`, `resolveSmartFilterValues`. */
+import {
+  Button,
+  resolveSmartFilterValues,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+const FIELDS: SmartFilterField[] = [
+  { key: "method", label: "Метод", options: METHODS.map((v) => ({ value: v, label: v })) },
+];
+
+const ONLY_PUT: SmartFilterValue = { method: { include: ["PUT"], exclude: [] } };
+const NO_READS: SmartFilterValue = { method: { include: [], exclude: ["GET", "POST"] } };
+
+export default function SmartFilterControlledExample() {
+  const [value, setValue] = React.useState<SmartFilterValue>({});
+
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root fields={FIELDS} value={value} onValueChange={setValue}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+      <div className={styles.views}>
+        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(ONLY_PUT)}>
+          Только PUT
+        </Button.Root>
+        <Button.Root variant="soft" tone="neutral" size="s" onClick={() => setValue(NO_READS)}>
+          Без GET и POST
+        </Button.Root>
+        <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setValue({})}>
+          Сбросить
+        </Button.Root>
+      </div>
+      <Typography as="span" variant="code" tone="secondary">
+        {`method: ${JSON.stringify(resolveSmartFilterValues(value.method, METHODS))}`}
+      </Typography>
+    </div>
+  );
+}

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

@@ -0,0 +1,56 @@
+/* Layout of the SmartFilter scenarios: semantic tokens only. */
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: 100%;
+  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;
+  align-items: center;
+  gap: var(--prime-space-3);
+  width: 100%;
+  min-width: 0;
+}
+
+.route {
+  flex: 1;
+  min-width: 0;
+}
+
+.views {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}
+
+/* 320 px: the smallest supported viewport. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+  min-width: 0;
+}

package/src/components/smart-filter/examples/many-values.tsx

@@ -0,0 +1,53 @@
+/** 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";
+
+const SERVICES = [
+  "access-policy",
+  "billing",
+  "catalog",
+  "checkout",
+  "conformance",
+  "delivery",
+  "events",
+  "go-events",
+  "http-gateway",
+  "inventory",
+  "loyalty",
+  "notifications",
+  "orders",
+  "payments",
+  "pricing",
+  "reports",
+  "rpc-gateway",
+  "search",
+  "users",
+  "workflow",
+];
+
+const DEGRADED = new Set(["checkout", "events", "pricing"]);
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "service",
+    label: "Сервис",
+    finite: false,
+    options: SERVICES.map((name) => ({
+      value: name,
+      label: name,
+      icon: DEGRADED.has(name) ? <Icon name="status.warning" tone="warning" /> : undefined,
+    })),
+  },
+];
+
+export default function SmartFilterManyValuesExample() {
+  return (
+    <SmartFilter.Root
+      fields={FIELDS}
+      collapsedLimit={8}
+      defaultValue={{ service: { include: [], exclude: ["events"] } }}
+    >
+      <SmartFilter.Toolbar />
+      <SmartFilter.Chips />
+    </SmartFilter.Root>
+  );
+}

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

@@ -0,0 +1,38 @@
+/** A 320 px column: the search shrinks next to the filter button and the tags wrap under them — `size`. */
+import { SmartFilter, type SmartFilterField } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "status",
+    label: "Статус",
+    options: [
+      { value: "new", label: "Новые" },
+      { value: "paid", label: "Оплаченные" },
+      { value: "refund", label: "Возвраты" },
+    ],
+  },
+  {
+    key: "city",
+    label: "Город",
+    finite: false,
+    options: ["Москва", "Казань", "Самара", "Пермь"].map((v) => ({ value: v, label: v })),
+  },
+];
+
+const APPLIED = {
+  status: { include: ["paid"], exclude: [] },
+  city: { include: [], exclude: ["Самара"] },
+};
+
+export default function SmartFilterNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <SmartFilter.Root fields={FIELDS} size="s" defaultValue={APPLIED}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,109 @@
+/** 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`. */
+import {
+  Badge,
+  Card,
+  matchesSmartFilter,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const METHOD_COLOR = {
+  GET: "green",
+  POST: "blue",
+  PUT: "orange",
+  PATCH: "purple",
+  DELETE: "red",
+} as const;
+
+const REQUESTS = [
+  { id: 1, route: "/orders", method: "GET", service: "orders", state: "active" },
+  { id: 2, route: "/orders", method: "POST", service: "orders", state: "active" },
+  { id: 3, route: "/orders/:id", method: "PUT", service: "orders", state: "inactive" },
+  { id: 4, route: "/catalog/items", method: "GET", service: "catalog", state: "active" },
+  { id: 5, route: "/catalog/items/:id", method: "PATCH", service: "catalog", state: "active" },
+  { id: 6, route: "/billing/invoices", method: "GET", service: "billing", state: "active" },
+  {
+    id: 7,
+    route: "/billing/invoices/:id",
+    method: "DELETE",
+    service: "billing",
+    state: "inactive",
+  },
+  { id: 8, route: "/events/subscribe", method: "POST", service: "events", state: "active" },
+] as const;
+
+const asOptions = (values: readonly string[]) => values.map((v) => ({ value: v, label: v }));
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "service",
+    label: "Сервис",
+    finite: false,
+    options: asOptions(["billing", "catalog", "events", "orders"]),
+  },
+  { key: "method", label: "Метод", options: asOptions(["GET", "POST", "PUT", "PATCH", "DELETE"]) },
+  {
+    key: "state",
+    label: "Состояние",
+    options: [
+      { value: "active", label: "Активные" },
+      { value: "inactive", label: "Неактивные" },
+    ],
+  },
+];
+
+export default function SmartFilterOverviewExample() {
+  const [value, setValue] = React.useState<SmartFilterValue>({});
+  const [search, setSearch] = React.useState("");
+
+  const found = REQUESTS.filter(
+    (request) =>
+      matchesSmartFilter(value.service, request.service) &&
+      matchesSmartFilter(value.method, request.method) &&
+      matchesSmartFilter(value.state, request.state) &&
+      request.route.toLowerCase().includes(search.trim().toLowerCase()),
+  );
+
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        value={value}
+        onValueChange={setValue}
+        search={search}
+        onSearchChange={setSearch}
+      >
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+      <Card.Root variant="list">
+        <Card.Header>
+          <Card.Title>Запросы</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            {found.length} из {REQUESTS.length}
+          </Typography>
+        </Card.Header>
+        <Card.List>
+          {found.map((request) => (
+            <Card.ListItem key={request.id}>
+              <span className={styles.request}>
+                <Badge.Root color={METHOD_COLOR[request.method]}>{request.method}</Badge.Root>
+                <Typography as="span" variant="code" className={styles.route} truncate>
+                  {request.route}
+                </Typography>
+                <Typography as="span" variant="caption" tone="muted">
+                  {request.service}
+                </Typography>
+              </span>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </Card.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,33 @@
+/** 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",
+    label: "Метод",
+    options: ["GET", "POST", "PUT", "DELETE"].map((v) => ({ value: v, label: v })),
+  },
+];
+
+const ONLY_GET = { method: { include: ["GET"], exclude: [] } };
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function SmartFilterSizesExample() {
+  return (
+    <div className={styles.sizes}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.size}>
+          <SmartFilter.Root fields={FIELDS} size={size} defaultValue={ONLY_GET}>
+            <SmartFilter.Toolbar />
+            <SmartFilter.Chips />
+          </SmartFilter.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/spinner/COMPONENT.md

@@ -0,0 +1,112 @@
+# Spinner
+
+**Category:** feedback
+**Kind:** primitive
+
+> An indeterminate loading indicator: a ring with a gap that turns 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).
+- A status line next to text («Загружаем счета…»).
+- Inside a kit component that shows loading (it is the kit's one spinner).
+
+## When not to use
+- The progress is known (upload, steps, quota) → use [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A button waiting for its request → set `loading` on [Button](../button/COMPONENT.md); it places the spinner itself.
+- Content of a known shape is loading (a list, a card, a form) → [Skeleton](../skeleton/COMPONENT.md) of that shape inside [Crossfade](../crossfade/COMPONENT.md).
+- A table loading its rows → `loading` on [DataTable](../data-table/COMPONENT.md) (skeleton rows keep the layout).
+- A whole page failed to load → [EmptyPage](../empty-page/COMPONENT.md) with a retry action.
+
+## Import
+```tsx
+import { Spinner } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Spinner          <span role="status">; size and tone
+├─ ring          the turning ring (aria-hidden)
+└─ label         visually hidden labels.loading
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Spinner
+`ref` → `HTMLSpanElement`. A turning ring inside a `role="status"` region with text for screen readers.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Explicit size on the icon scale: 14 · 16 · 20 · 24 · 32. Without it the spinner follows its host like `Icon`: the host's `--prime-icon-size`, else the nearest control tier, else 16. |
+| `tone` | `"default" \| "secondary" \| "muted" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Ring color; `default` inherits `currentColor`. |
+| `labels` | `Partial<SpinnerLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className`, `aria-hidden`, `data-*` and the other span attributes. |
+
+## Variants
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | |
+| `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 | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | |
+| — (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 |
+|---|---|---|
+| spinning | mounted | the ring turns at a constant speed (`slow × 3` per turn, linear) |
+| reduced motion | `prefers-reduced-motion` | duration collapses to 0: the ring stays still and visible |
+| size / tone | `size`, `tone` | `data-size`, `data-tone` (only for a non-default tone) |
+
+## Layout & spacing
+- 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`.
+- Render the real layout around it; never a full-screen overlay of spinners.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- `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 does not turn and stays visible.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `loading` | `"Загрузка"` | Visually hidden text inside `role="status"`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A loading status next to a short explanation; the spinner takes the text color. |
+| [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.
+
+## Related
+- **Built from:** —
+- **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)