prime-ui-kit 0.10.0 → 0.11.1

package/src/components/sparkline/COMPONENT.md

@@ -3,16 +3,18 @@
 **Category:** data-display
 **Kind:** primitive
 
-> A small line chart with its headline — the latest value, its change against the point before and its date — where any point can be scrubbed.
+> A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed.
 
 ## When to use
 - A metric card on a dashboard: revenue, orders, sign-ups over the last days or weeks.
 - A trend next to a number where the shape matters more than exact axes.
+- Values with a sign by period — profit, net new customers (`variant="bars"`: up when positive, down when negative), with the current period highlighted (`highlight`).
 - A detail page header that shows how a value moved.
 
 ## When not to use
-- Exact values on axes, several series, or a legend → a full chart library; Sparkline has no axes.
+- Exact values on axes, several series, or a legend → a full chart library on the kit's chart palette (`chartColors`); Sparkline has no axes.
 - Progress toward a goal → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- Shares of categories or a ranking → [ProgressBar](../progress-bar/COMPONENT.md) with `segments` or `layout="rows"`.
 - A list of values to compare → [DataTable](../data-table/COMPONENT.md).
 
 ## Import
@@ -22,11 +24,13 @@ import { Sparkline, type SparklinePoint } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Sparkline              <div>; the headline and the chart
+Sparkline              <div>; the headline and the chart; aria-busy while loading
 ├─ head                title (label) · date of the shown point
 ├─ value row           value (rolling digits when settled) · change Badge with the trend arrow
-└─ plot                role="slider" over the svg line and area
-   └─ cursor           guide line and dot of the shown point (aria-hidden)
+└─ plot                role="slider" over the chart
+   ├─ line:            svg line and area + cursor (guide line and dot, aria-hidden)
+   └─ bars:            zero line (chart axis) + a slot per point with its bar (aria-hidden)
+loading:               Skeletons of the date, the value line and the plot
 ```
 
 ## API
@@ -34,46 +38,66 @@ Sparkline              <div>; the headline and the chart
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Sparkline
-`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line chart; the chart is a `role="slider"` that picks a point.
+`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line or bar chart; the chart is a `role="slider"` that picks a point. The change hides when a percentage means nothing (the previous value is 0 or the sign flips).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»). Two or more draw a line. A new array cross-fades the line in. |
 | `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart. |
+| `variant` | `"line" \| "bars"` | `"line"` | `line` — a line over a soft area; `bars` — a bar per point standing on a zero line: up when positive, down (danger) when negative, the value end rounded. |
+| `highlight` | `number` | `the latest point` | Index of the point at rest (the current month): the headline shows it when nobody scrubs and leaving the chart returns to it; `bars` draw the other bars quieter. |
+| `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 and the spoken point («312 400 ₽»). |
 | `labels` | `Partial<SparklineLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
 
 ## Variants
-No variants: one accent line on the surface it sits on. Put it in a `Card` for a dashboard tile.
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `line` | an accent line over a soft area, a dot on the shown point | a continuous trend (daily revenue) | yes |
+| `bars` | a bar per point from a zero line (`--prime-color-chart-axis`): accent up, danger down, value end rounded | values by period, especially with a sign (monthly profit) | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `highlight` | the headline rests on that point; in `bars` the other bars are quieter | the current period is not the last point (a year with empty months ahead) | the latest point |
+| `loading` | Skeletons of the date, the value and the plot | the series is on its way | `false` |
+
+Put it in a `Card` for a dashboard tile.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| at rest | — | the latest point; the value rolls its digits when `data` changes |
-| scrubbing | pointer or touch over the plot | `data-scrubbing` on the root; the cursor and the headline follow the pointer with no easing (direct manipulation), digits change in place |
-| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`; the cursor glides to the point (`base` · emphasized) |
-| settle | pointer leaves, touch ends, focus leaves | the cursor glides back to the latest point |
-| new series | a new `data` array | the line cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+| at rest | — | the latest point or `highlight`; the value rolls its digits when `data` changes |
+| scrubbing | pointer, touch or the arrow keys | `data-scrubbing` on the root; the cursor (or the bar under the pointer) and the headline follow with no easing (direct manipulation), digits change in place |
+| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`, `data-scrubbing`; the cursor moves to the point at once (keyboard steps are high-frequency); in `bars` the current bar keeps its fill, the others go quiet (`fast` opacity) |
+| settle | pointer leaves, touch ends, focus leaves | back to the point at rest |
+| change hidden | the first point, the previous value is 0, or the sign flips | no change Badge: a percentage would mean nothing |
+| new series | a new `data` array | the chart cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+| loading | `loading` | `aria-busy` on the root; Skeletons in place of the date, the value and the plot; no slider until the data comes; the data cross-fades in |
 
 ## Layout & spacing
 - Takes the width of its container; the plot is 80 px high and inset by the dot radius so the cursor is never clipped.
+- 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.
-- Below 320 px the value row wraps the change badge under the value.
+- When the value row does not fit (a narrow card), the change badge wraps under the value.
 
 ## Accessibility
 
 ### Keyboard
 | Key | Action |
 |---|---|
-| `←` · `→` | Previous or next point. |
+| `←` · `→` · `↓` · `↑` | Previous or next point: `←` / `↓` back, `→` / `↑` forward, as on a slider. |
 | `Home` · `End` | First or last point. |
-| `Tab` | Focuses the chart; leaving focus returns to the latest point. |
+| `Tab` | Focuses the chart; leaving focus returns to the point at rest (the latest or `highlight`). |
 
 ### ARIA
-- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`).
-- The headline with the latest value and change reads as plain text.
-- The change carries a sign and an arrow, never color alone.
+- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`). The headline is the tooltip of the chart: the value of 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.
+- While `loading` the root is `aria-busy` and the chart is not in the tab order yet.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -86,13 +110,18 @@ No variants: one accent line on the surface it sits on. Put it in a `Card` for a
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. |
+| [variants.tsx](examples/variants.tsx) | The same week as a line and as bars from zero — `variant`. |
+| [states.tsx](examples/states.tsx) | While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. |
+| [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`. |
 | [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. |
 
 ## Mistakes
 - A new array on every render (`data={rows.map(...)}` inline) → the line cross-fades on every render; memoize the series.
 - Formatting inside `label` of a point («312 400 ₽») → the point label is its name («8 окт»); format values with `formatValue`.
 - A Sparkline without a container width (inside an inline flex row) → give it a width or put it in a `Card`.
+- A separate tooltip over the bars → the headline already shows the scrubbed point; a floating tooltip would cover the next bar.
+- A grey box while the series loads → `loading`.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md)
+- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow)
 - **See also:** [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -0,0 +1,41 @@
+/** 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`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const PROFIT: SparklinePoint[] = [
+  { label: "янв", value: 420_000 },
+  { label: "фев", value: 310_000 },
+  { label: "мар", value: -120_000 },
+  { label: "апр", value: 180_000 },
+  { label: "мая", value: 540_000 },
+  { label: "июн", value: 610_000 },
+  { label: "июл", value: -60_000 },
+  { label: "авг", value: 280_000 },
+  { label: "сен", value: 470_000 },
+  { label: "окт", value: 390_000 },
+  { label: "ноя", value: 0 },
+  { label: "дек", value: 0 },
+];
+
+/** October is the current month: November and December are still empty. */
+const CURRENT_MONTH = 9;
+
+const formatRubles = (value: number) =>
+  `${value < 0 ? "−" : ""}${Math.abs(value).toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineSignedBarsExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline
+          data={PROFIT}
+          label="Прибыль по месяцам, 2026"
+          variant="bars"
+          highlight={CURRENT_MONTH}
+          formatValue={formatRubles}
+        />
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,30 @@
+/** While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const REVENUE: SparklinePoint[] = [
+  { label: "июл", value: 2_840_000 },
+  { label: "авг", value: 3_120_000 },
+  { label: "сен", value: 2_960_000 },
+  { label: "окт", value: 3_410_000 },
+];
+
+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>
+      <div>
+        <Sparkline data={[]} label="Выручка" loading />
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+/** The same week as a line and as bars from zero — `variant`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const ORDERS: SparklinePoint[] = [
+  { label: "2 окт", value: 38 },
+  { label: "3 окт", value: 44 },
+  { label: "4 окт", value: 41 },
+  { label: "5 окт", value: 29 },
+  { label: "6 окт", value: 33 },
+  { label: "7 окт", value: 47 },
+  { label: "8 окт", value: 52 },
+];
+
+const VARIANTS = ["line", "bars"] as const;
+
+export default function SparklineVariantsExample() {
+  return (
+    <div>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          <Sparkline data={ORDERS} label="Заказы за неделю" variant={variant} />
+          <Typography as="span" variant="caption" tone="muted">
+            {variant}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/spinner/COMPONENT.md

@@ -3,7 +3,7 @@
 **Category:** status
 **Kind:** primitive
 
-> An indeterminate loading indicator: a ring with a gap that turns while a request runs.
+> 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).
@@ -12,6 +12,7 @@
 
 ## When not to use
 - The progress is known (upload, steps, quota) → use [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A named process on the data scale whose share is not known yet (an import card) → [ProgressCircle](../progress-circle/COMPONENT.md) `value={null}`: a `progressbar` with your name that can show the share once it arrives.
 - 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).
@@ -25,7 +26,7 @@ import { Spinner } from "prime-ui-kit";
 ## Anatomy
 ```
 Spinner          <span role="status">; size and tone
-├─ ring          the turning ring (aria-hidden)
+├─ ring          the kit ring (internal/ring, value null): a quarter arc on a faint track (aria-hidden)
 └─ label         visually hidden labels.loading
 ```
 
@@ -34,7 +35,7 @@ Spinner          <span role="status">; size and tone
 <!-- 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.
+`ref` → `HTMLSpanElement`. The kit ring with the share unknown — a quarter arc turning on a faint track, at the line weight — inside a `role="status"` region with text for screen readers.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -67,11 +68,12 @@ Spinner          <span role="status">; size and tone
 ## 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) |
+| 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`.
 - Render the real layout around it; never a full-screen overlay of spinners.
@@ -84,7 +86,7 @@ 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.
+- Under `prefers-reduced-motion` the ring keeps turning, slower and linear, so the loading cue stays readable.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -108,5 +110,5 @@ No keyboard interaction.
 - A spinner for a known progress → ProgressBar / ProgressCircle.
 
 ## Related
-- **Built from:** —
+- **Built from:** `internal/ring` (the ring drawing, shared with ProgressCircle and the circle Button)
 - **See also:** [Skeleton](../skeleton/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md), [Button](../button/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

package/src/components/stepper/COMPONENT.md

@@ -127,10 +127,14 @@ Derive statuses from `value`; set `status="danger"` only on the failing step wit
 
 Root attributes: `data-orientation`, `data-size`. Uncontrolled (`defaultValue`) clicks still select items.
 
+Motion: a status change moves the indicator's fill, color and halo over `base`; the row fill and text color change over `fast`; press scales the step to `--prime-motion-press-scale`. Under reduced motion the indicator changes at once.
+
 ## Layout & spacing
 - The root is a size container (`inline-size: 100%`): give it a definite width, a shrink-wrapped parent collapses it.
 - Wizard: stepper column and form side by side with `gap: var(--prime-space-8)`, stacking on narrow widths.
 - Vertical rows are separated by `var(--prime-space-1)` (`var(--prime-space-2)` at `size="xl"`); the same value is the row gap of a wrapping horizontal stepper.
+- Horizontal steps and their chevrons sit 8 · 12 · 16 · 20 · 24 apart (xs → xl); below a 30rem (480px) container each step takes its own full-width row with the vertical row padding.
+- Indicator → text gap 8 (xs, s) · 12 (m, l) · 16 (xl); titles are medium weight and wrap long words.
 
 ## Accessibility
 

package/src/components/switch/COMPONENT.md

@@ -34,13 +34,14 @@ Switch.Root          field grid; ref and input props go to the native input (rol
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Switch.Root
-`ref` → `HTMLInputElement` (the native `input type="checkbox" role="switch"`). Renders the field `<div>`, the `<label>` row with the input and the track, and the support row. Field-root rule for a leaf: `className` goes to the field `<div>`; `id`, `ref` and native input props to the input.
+`ref` → `HTMLInputElement` (the native `input type="checkbox" role="switch"`). Renders the field `<div>`, the `<label>` row with the input and the track, and the support row. `className` goes to the field `<div>`, native input props to the input.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `checked` | `boolean` | — | Controlled state. |
 | `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
-| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on every toggle (not while `readOnly`). |
+| `onCheckedChange` | `(checked: boolean) => void \| Promise<void>` | — | Called with the new state on every toggle. Return the save's promise: the thumb waits with a spinner; a controlled owner sets `checked` before resolving; on reject the thumb goes back (say why with `error`). |
+| `loading` | `boolean` | `false` | Saving, for an owner that tracks the request itself: a spinner in the thumb, `aria-busy` on the input, presses do nothing. A promise from `onCheckedChange` does the same on its own. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the track (24×16 … 44×24), the text and the gap. Without it the tier of its host (a form, a panel), else `m`. |
 | `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
@@ -76,6 +77,7 @@ No `variant` / `tone` / `color`.
 | `readOnly` | normal colours, no hover or press, clicks ignored | the value is meaningful but someone else controls it | `false` |
 | `disabled` | muted track (on = `accent-soft`), dimmed text | the setting is unavailable | `false` |
 | `invalid` | danger ring on the off track | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `loading` | a spinner turns inside the thumb, presses do nothing | the owner tracks the save itself; with a promise from `onCheckedChange` it comes on its own | `false` |
 
 **Combinations**
 - `readOnly` and `disabled` together are pointless — pick one.
@@ -90,6 +92,7 @@ No `variant` / `tone` / `color`.
 | invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid`; danger ring on the off track and on focus; the row shakes once when an error arrives (`data-shake`) |
 | disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, `cursor: not-allowed` |
 | read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the field; no hover or press, default cursor |
+| saving | `loading`, or `onCheckedChange` returned a pending promise | the thumb stands in the new position with a `Spinner` inside (accent when on, muted when off; it enters with `enterMotion`), `aria-busy` on the input, `data-loading` on the track, presses ignored; a rejection glides the thumb back (`base`, emphasized) |
 | pressed | pointer press | the track scales to the compact press scale (not when disabled or read-only) |
 | focus-visible | keyboard | outer focus ring around the track |
 
@@ -107,12 +110,13 @@ Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncont
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus to the switch. |
-| `Space` | Toggles it (not while `readOnly`). |
+| `Space` | Toggles it (not while `readOnly` or saving). |
 
 ### ARIA
 - A native `<input type="checkbox" role="switch">` (its native checked state is the switch state), visually hidden over the track and wrapped by the `<label>` row.
 - `aria-invalid`, `aria-readonly` and `aria-describedby` (your ids + the hint or the error) are set on the input.
 - Without visible text, name it with `aria-label` or `aria-labelledby` on `Switch.Root`.
+- While a change is saved (`loading` or a pending promise) the input has `aria-busy`; the thumb's spinner is hidden from assistive tech. A refused save puts the state back — say why with `error`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -124,8 +128,9 @@ No `labels`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A setting that applies at once, with a hint under its text — `hint`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size, track 24×16 to 44×24; the text follows the control tier — `size`. |
-| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `disabled`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `loading`, `disabled`. |
 | [settings-row.tsx](examples/settings-row.tsx) | A settings row with text on the left and a bare track on the right — `aria-labelledby`, `aria-describedby`. |
+| [saving.tsx](examples/saving.tsx) | A setting that applies on the server at once: the thumb waits in its new place with a spinner, and a refused save glides it back and says why — `onCheckedChange`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the state and rewrites the hint to match it — `checked`, `onCheckedChange`. |
 | [in-form.tsx](examples/in-form.tsx) | Switches submitted with a form: the value goes to FormData by `name`, a required one shows an error — `name`, `required`, `error`. |
 
@@ -135,7 +140,8 @@ No `labels`.
 - `invalid` plus `error` → pass `error` alone.
 - A bare switch without `aria-label` / `aria-labelledby` → it has no accessible name.
 - `readOnly` used to block a setting that is unavailable → use `disabled`.
+- Setting `checked` in `onCheckedChange` and flipping it back when the request fails, or a separate «saving» flag → return the request's promise; set `checked` only after it succeeds.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (the row), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Spinner](../spinner/COMPONENT.md) (saving); the row is a native `<label>`
 - **See also:** [Checkbox](../checkbox/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/switch/examples/in-form.tsx

@@ -22,7 +22,9 @@ export default function SwitchInFormExample() {
         name="processing"
         required
         error={error}
-        onCheckedChange={(checked) => checked && setError(undefined)}
+        onCheckedChange={(checked) => {
+          if (checked) setError(undefined);
+        }}
       >
         <Switch.Label>Согласие на обработку данных</Switch.Label>
       </Switch.Root>

package/src/components/switch/examples/saving.tsx

@@ -0,0 +1,53 @@
+/** A setting that applies on the server at once: the thumb waits in its new place with a spinner, and a refused save glides it back and says why — `onCheckedChange`, `error`. */
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** The server's answer a beat later: SMS needs a confirmed phone number. */
+function saveSetting(setting: "email" | "sms", enabled: boolean) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (setting === "sms" && enabled) reject(new Error("Сначала подтвердите номер телефона"));
+      else resolve();
+    }, 900);
+  });
+}
+
+export default function SwitchSavingExample() {
+  const [email, setEmail] = React.useState(true);
+  const [sms, setSms] = React.useState(false);
+  const [smsError, setSmsError] = React.useState<string>();
+
+  return (
+    <div className={styles.form}>
+      <Switch.Root
+        checked={email}
+        onCheckedChange={async (enabled) => {
+          await saveSetting("email", enabled);
+          setEmail(enabled);
+        }}
+        hint="Счета и акты на почту бухгалтерии"
+      >
+        <Switch.Label>Документы на почту</Switch.Label>
+      </Switch.Root>
+      <Switch.Root
+        checked={sms}
+        error={smsError}
+        onCheckedChange={async (enabled) => {
+          setSmsError(undefined);
+          try {
+            await saveSetting("sms", enabled);
+          } catch (error) {
+            setSmsError(error instanceof Error ? error.message : String(error));
+            throw error;
+          }
+          setSms(enabled);
+        }}
+        hint="Код и статус оплаты по SMS"
+      >
+        <Switch.Label>SMS-уведомления</Switch.Label>
+      </Switch.Root>
+    </div>
+  );
+}

package/src/components/switch/examples/states.tsx

@@ -1,4 +1,4 @@
-/** Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `disabled`. */
+/** Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `loading`, `disabled`. */
 import { Switch } from "prime-ui-kit";
 
 export default function SwitchStatesExample() {
@@ -27,6 +27,11 @@ export default function SwitchStatesExample() {
         </div>
       </div>
       <div>
+        <div>
+          <Switch.Root defaultChecked loading>
+            <Switch.Label>loading</Switch.Label>
+          </Switch.Root>
+        </div>
         <div>
           <Switch.Root disabled>
             <Switch.Label>disabled</Switch.Label>