prime-ui-kit 0.9.3 → 0.11.0

package/src/components/sheet/COMPONENT.md

@@ -0,0 +1,216 @@
+# Sheet
+
+**Category:** overlays
+**Kind:** overlay
+
+> A panel raised from the bottom edge for a short task that ends by itself: pick a date, choose an action, leave a few words.
+
+## When to use
+- A pick that closes the sheet: a date, a status, a delivery slot (`Datepicker.Panel` straight in the body).
+- A short list of actions on one record («Повторить заказ», «Скачать счёт») — each closes the sheet.
+- A short note or a question the person answers in place, on a phone first: one or two fields with an explicit submit (`Sheet.Footer`).
+
+## When not to use
+- Record details, forms, filters that stay open while the person works → use [Drawer](../drawer/COMPONENT.md) (a side panel).
+- A decision or a short form in the centre of the screen → use [Modal](../modal/COMPONENT.md) (it becomes a bottom sheet on phones by itself).
+- A destructive confirm → use [ConfirmDialog](../confirm-dialog/COMPONENT.md).
+- Actions anchored to a button on a desktop → use [Dropdown](../dropdown/COMPONENT.md) (it becomes a sheet on phones by itself).
+
+## Import
+```tsx
+import { Sheet } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Sheet.Root                     state and dismiss policy (no DOM)
+├─ Sheet.Trigger               clones its child; opens on click
+└─ Sheet.Content               portal + scrim + role="dialog" panel at the bottom edge
+   ├─ (grab handle)            aria-hidden bar on top; a drag starts here
+   ├─ Sheet.Guard              no DOM: holds the sheet (busy / dirty) from inside
+   ├─ Sheet.Header             optional: [Icon] [Title + Description] [Actions] [close Button]
+   │  ├─ Sheet.Icon
+   │  ├─ Sheet.Title           <h2>
+   │  ├─ Sheet.Description     <p>
+   │  └─ Sheet.Actions         row of tier-s controls before the close button
+   ├─ Sheet.Body               the content; the only scrolling zone (ScrollContainer)
+   └─ Sheet.Footer             optional: only for a form with an explicit submit
+      ├─ Sheet.Meta            <p>, muted status at the start
+      └─ Sheet.Close           clones its child; closes on click
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Sheet.Root
+No DOM, no ref. State and dismiss policy.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
+| `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. A `Guard` holds the dismisses (not code). |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe down) closes the dialog; turn off for destructive confirms. |
+| `labels` | `Partial<SheetLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | Trigger and Content. |
+
+### Sheet.Content
+`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"` panel raised from the bottom edge, as tall as its content. Header and footer are optional: without a header name it with `aria-label`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` | `string` | — | Dialog name when there is no Title. |
+| `aria-labelledby` | `string` | — | Overrides the Title id. |
+| `aria-describedby` | `string` | — | Overrides the Description id. |
+| `overlayClassName` | `string` | — | Class on the scrim. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes of the `role="dialog"` element. |
+
+### Sheet.Header
+`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [Actions] [close button]. + native `HTMLAttributes<HTMLElement>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`; disabled in place while a `Guard` is `busy`. |
+| `children` | `ReactNode` | — | Icon, Title, Description, Actions in any order; each goes to its column. A `Tabs.List` (with `Tabs.Root` around header and body) turns the header into a tab strip. |
+
+### Sheet.Actions
+`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button. Controls inside take tier `s`. + native `<div>` props.
+
+### Sheet.Icon
+`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color. |
+| `children` | `ReactNode` | — (required) | Icon glyph (sized to the m icon). |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
+
+### Sheet.Title · Sheet.Description
+`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` (title-m) / `<p>` (body-s, muted); their ids name and describe the dialog. + native props except `id`.
+
+### Sheet.Body
+`ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks. + native `<div>` props.
+
+### Sheet.Footer
+`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start. + native `HTMLAttributes<HTMLElement>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `layout` | `"fill" \| "end"` | `"end"` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
+
+### Sheet.Meta
+`ref` → `HTMLParagraphElement`. A `<p>` at the start of the footer: short muted status text («Есть несохранённые изменения»); the buttons keep their width at the end. Not part of the dialog description. + native `<p>` props.
+
+### Sheet.Guard
+No DOM, no ref. Holds the dialog from anywhere inside Content, where the form state lives; renders only the built-in «discard changes?» confirm. Closing from code is never held.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `busy` | `boolean` | `false` | A request runs: Escape, a press outside, a swipe, the close button and `Close` do nothing; the close button and the `Close` child stay in place, disabled. |
+| `dirty` | `boolean` | `false` | Unsaved changes: any of those dismisses first asks «Не сохранять изменения?» (a ConfirmDialog with `labels.discard*`); confirming closes the dialog. |
+
+### Sheet.Trigger · Sheet.Close
+No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`). `Close` goes through a `Guard` and makes its child `disabled` while the guard is busy.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element, usually a Button. |
+
+## Variants
+Sheet has no `variant`, `side` or `size`: it always rises from the bottom edge, centred at `--prime-sheet-width` (560) on a tablet or desktop, full width on a phone, and as tall as its content.
+
+### Structure
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| content alone | the handle, then the body; named by `aria-label` | the content says what it is — a calendar under a «Дата отгрузки» button | |
+| header + body | a title (and description) above the content; the header keeps its × | the content needs a title to be understood — actions «Заказ № 1042» | |
+| header + body + footer | «Отмена» and the submit under the form | a short form that needs an explicit submit | |
+
+### layout (Footer)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `end` | auto-width buttons at the end | a short form | yes |
+| `fill` | equal-width buttons in one row | two equal answers | |
+
+### tone (Icon)
+`neutral` (default) · `accent` · `success` · `warning` · `danger` · `info` — soft tile fill and icon color, as in Modal.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the scrim and the panel; mounted until the slide-down ends |
+| swiping | a drag down from the handle or the header (with `closeOnOutsideClick`) | `data-swiping` and `--swipe-offset` on the panel while the pointer drags it; `data-swipe-dismissed` while it glides out after a closing release; `--swipe-progress` (0…1) on the scrim |
+| open: trapped | while open | focus trapped, page scroll locked, siblings of the portal `inert`; a sheet opened from another overlay stacks above it |
+| closing | `open` turns false | the panel keeps showing the children it had open while it slides down |
+| busy | `Sheet.Guard busy` | Escape, the scrim, a swipe, the close button and `Sheet.Close` do nothing; the close button and the `Close` child are `disabled` in place |
+| dirty | `Sheet.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); no swipe |
+
+Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once. A swipe down moves the sheet with the pointer; on release it closes past 30% of its height or on a quick flick and glides the rest of the way out, otherwise it glides back — both over `base` on the `emphasized` (iOS sheet) curve. A pull upward meets growing resistance and stops at 24; the sheet's fill continues that far below the screen edge. The scrim thins as the sheet goes down. The drag starts from the handle or the header, never from the body, so its content scrolls and its controls work as usual.
+
+## Layout & spacing
+- A sheet is a short task that ends by itself — a pick, a tap on an action, a swipe down. Its zones follow the task, not a template:
+  - **No footer by default.** A footer only for a form with an explicit submit: «Отмена» (`Sheet.Close`, outline neutral) and the submit (solid, last; `type="submit" form={formId}`).
+  - **The header is optional.** Keep it when the content needs a title to be understood (a list of actions on «Заказ № 1042»). Drop it — and with it the × and the hairline — when the content speaks for itself (a calendar opened from a «Дата отгрузки» button): name the sheet with `aria-label` on `Sheet.Content`.
+- The content is the sheet's own, across its width: `Datepicker.Panel` or a column of actions straight in `Sheet.Body` — never a Card or a padded box inside it.
+- Zone padding `--prime-sheet-padding`; height by content up to `100dvh − --prime-sheet-top-gap`, radius `--prime-sheet-radius` on top, a `--prime-sheet-handle-area` strip with the handle bar, the bottom safe-area inset below the content.
+- Only the body scrolls; header and footer stay in place.
+- Tabs in the header: a `Tabs.List` inside `Sheet.Header` (with `Tabs.Root` around the header and the body) spans the header's last row. The header becomes the tab strip, edge to edge and without the hairline; the active tab is the body rising into it, the panels sit in the body.
+- Fields inside get the surface field fill.
+
+```tsx
+<Sheet.Content aria-label="Дата отгрузки">
+  <Sheet.Body>
+    <Datepicker.Panel mode="single" value={date} onValueChange={pick} />
+  </Sheet.Body>
+</Sheet.Content>
+```
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Escape` | Closes the sheet (`closeOnEscape`); focus returns to the trigger. |
+| `Tab` · `Shift+Tab` | Cycle focus inside the sheet. |
+
+### ARIA
+- `role="dialog"`, `aria-modal="true"`, named by Title — without a header by `aria-label` on `Sheet.Content`; described by Description.
+- Focus moves into the sheet on open and returns to the opener on close, including after a scrim click.
+- The page behind is `inert`, scroll is locked; only the topmost layer reacts.
+- A swipe down is an extra way out; Escape and the scrim stay. The grab handle is `aria-hidden`.
+- A busy `Guard` holds every dismiss, the swipe included; a dirty one opens a `role="alertdialog"` confirm with focus on «Продолжить».
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `close` | `"Закрыть"` | `aria-label` of the header close button. |
+| `discardTitle` | `"Не сохранять изменения?"` | Title of the confirm a dismiss opens while a `Guard` is `dirty`. |
+| `discardDescription` | `"Изменения в форме пропадут."` | Its description. |
+| `discardConfirm` | `"Не сохранять"` | Its confirm button: close and lose the changes. |
+| `discardCancel` | `"Продолжить"` | Its cancel button: back to the form. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Actions with an order raised from the bottom edge: a header names the order, a column of actions follows, and each action closes the sheet — `Sheet.Trigger`, `Sheet.Header`, `Sheet.Close`. |
+| [structure.tsx](examples/structure.tsx) | The content alone: a date sheet with no header and no footer, the calendar across its width, named by `aria-label`; a pick or a swipe down closes it — `aria-label`, `Sheet.Body`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A handover the courier must answer: no swipe, scrim or Escape closes the sheet, only its two buttons — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the state and raises the sheet from a link in the text, without a trigger — `open`, `onOpenChange`. |
+| [in-form.tsx](examples/in-form.tsx) | A short form that needs an explicit submit: the one case for a footer, Cancel and Send under the field, an empty comment keeps the sheet open — `Sheet.Footer`, `error`. |
+
+## Mistakes
+- `<Drawer.Content side="bottom">` → there is no bottom Drawer; a panel from the bottom edge is `Sheet`.
+- «Отмена» / «Готово» buttons under a sheet that closes on a pick → drop the footer; the pick, the swipe, the scrim and Escape close it.
+- A header with only a title over a calendar or a list that already says what it is → drop the header and name the sheet with `aria-label`.
+- No header and no `aria-label` → the dialog has no name; give `Sheet.Content` an `aria-label`.
+- A Card or a padded `div` around the content → put it straight into `Sheet.Body`, across its width.
+- Record details or a long form in a sheet → use Drawer; a sheet is a short task.
+- `closeOnOutsideClick={false}` and `closeOnEscape={false}` with no header × and no `Sheet.Close` → nothing closes it; keep a button that answers.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Sheet.Body`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Sheet.Guard` discard confirm), `Icon` (the close glyph)
+- **See also:** [Drawer](../drawer/COMPONENT.md) (the same parts as a side panel), [Modal](../modal/COMPONENT.md) (the same parts in the centre), [Datepicker](../datepicker/COMPONENT.md) (`Datepicker.Panel` in a sheet), [Dropdown](../dropdown/COMPONENT.md)

package/src/components/sheet/examples/controlled-open.tsx

@@ -0,0 +1,37 @@
+/** The parent owns the state and raises the sheet from a link in the text, without a trigger — `open`, `onOpenChange`. */
+import { LinkButton, Sheet, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SheetControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Typography variant="body-m" tone="secondary">
+        Доставка 5 октября.{" "}
+        <LinkButton
+          href="#delivery-cost"
+          onClick={(event) => {
+            event.preventDefault();
+            setOpen(true);
+          }}
+        >
+          Как считается стоимость?
+        </LinkButton>
+      </Typography>
+      <Sheet.Root open={open} onOpenChange={setOpen}>
+        <Sheet.Content>
+          <Sheet.Header>
+            <Sheet.Title>Стоимость доставки</Sheet.Title>
+          </Sheet.Header>
+          <Sheet.Body>
+            <Typography variant="body-m" tone="secondary">
+              Базовый тариф 390 ₽ до 5 кг, дальше 40 ₽ за каждый килограмм. От 5 000 ₽ в заказе
+              доставка бесплатная.
+            </Typography>
+          </Sheet.Body>
+        </Sheet.Content>
+      </Sheet.Root>
+    </>
+  );
+}

package/src/components/sheet/examples/dismiss.tsx

@@ -0,0 +1,42 @@
+/** A handover the courier must answer: no swipe, scrim or Escape closes the sheet, only its two buttons — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, Sheet, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SheetDismissExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Sheet.Root
+      open={open}
+      onOpenChange={setOpen}
+      closeOnOutsideClick={false}
+      closeOnEscape={false}
+    >
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Передать заказ
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header showClose={false}>
+          <Sheet.Title>Заказ № 1042 передан клиенту?</Sheet.Title>
+        </Sheet.Header>
+        <Sheet.Body>
+          <Typography variant="body-m" tone="secondary">
+            Ответ попадёт в историю заказа и закроет доставку. Случайный свайп его не отменит.
+          </Typography>
+        </Sheet.Body>
+        <Sheet.Footer>
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Клиент не вышел
+            </Button.Root>
+          </Sheet.Close>
+          <Sheet.Close>
+            <Button.Root>Передан</Button.Root>
+          </Sheet.Close>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

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

@@ -0,0 +1,13 @@
+/* Layout of the Sheet scenarios: semantic tokens only. */
+
+/* overview.tsx: a column of actions, one per row. */
+.actions {
+  display: grid;
+  gap: var(--prime-space-1);
+}
+
+/* in-form.tsx: field groups get 20 between them. */
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+}

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

@@ -0,0 +1,65 @@
+/** A short form that needs an explicit submit: the one case for a footer, Cancel and Send under the field, an empty comment keeps the sheet open — `Sheet.Footer`, `error`. */
+import { Button, Sheet, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SheetInFormExample() {
+  const formId = React.useId();
+  const [open, setOpen] = React.useState(false);
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const comment = String(new FormData(event.currentTarget).get("comment") ?? "").trim();
+    if (!comment) {
+      setError("Напишите, что передать курьеру");
+      return;
+    }
+    setOpen(false);
+  };
+
+  return (
+    <Sheet.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setError(undefined);
+      }}
+    >
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Комментарий курьеру
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header>
+          <Sheet.Title>Комментарий курьеру</Sheet.Title>
+          <Sheet.Description>Заказ № 1042 · доставка 5 октября</Sheet.Description>
+        </Sheet.Header>
+        <Sheet.Body>
+          <form id={formId} className={styles.form} noValidate onSubmit={submit}>
+            <Textarea.Root
+              label="Комментарий"
+              name="comment"
+              placeholder="Позвонить за час, домофон не работает"
+              error={error}
+              reserveSupportRow
+              onValueChange={() => setError(undefined)}
+            />
+          </form>
+        </Sheet.Body>
+        <Sheet.Footer>
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Отмена
+            </Button.Root>
+          </Sheet.Close>
+          <Button.Root type="submit" form={formId}>
+            Отправить
+          </Button.Root>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

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

@@ -0,0 +1,50 @@
+/** Actions with an order raised from the bottom edge: a header names the order, a column of actions follows, and each action closes the sheet — `Sheet.Trigger`, `Sheet.Header`, `Sheet.Close`. */
+import { Button, Icon, Sheet } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ACTIONS = [
+  { label: "Повторить заказ", icon: "action.refresh" },
+  { label: "Скачать счёт", icon: "action.download" },
+  { label: "Скопировать ссылку", icon: "action.copy" },
+] as const;
+
+export default function SheetOverviewExample() {
+  return (
+    <Sheet.Root>
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Действия с заказом
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header>
+          <Sheet.Title>Заказ № 1042</Sheet.Title>
+          <Sheet.Description>Анна Смирнова · 12 480 ₽</Sheet.Description>
+        </Sheet.Header>
+        <Sheet.Body>
+          <div className={styles.actions}>
+            {ACTIONS.map((action) => (
+              <Sheet.Close key={action.label}>
+                <Button.Root variant="ghost" tone="neutral" fullWidth>
+                  <Button.Icon>
+                    <Icon name={action.icon} />
+                  </Button.Icon>
+                  {action.label}
+                </Button.Root>
+              </Sheet.Close>
+            ))}
+            <Sheet.Close>
+              <Button.Root variant="ghost" tone="danger" fullWidth>
+                <Button.Icon>
+                  <Icon name="action.delete" />
+                </Button.Icon>
+                Отменить заказ
+              </Button.Root>
+            </Sheet.Close>
+          </div>
+        </Sheet.Body>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

package/src/components/sheet/examples/structure.tsx

@@ -0,0 +1,35 @@
+/** The content alone: a date sheet with no header and no footer, the calendar across its width, named by `aria-label`; a pick or a swipe down closes it — `aria-label`, `Sheet.Body`. */
+import { Button, Datepicker, Icon, Sheet } from "prime-ui-kit";
+import * as React from "react";
+
+const FORMAT = new Intl.DateTimeFormat("ru-RU", { day: "numeric", month: "long", year: "numeric" });
+
+export default function SheetStructureExample() {
+  const [open, setOpen] = React.useState(false);
+  const [date, setDate] = React.useState<Date | null>(new Date(2026, 2, 8));
+
+  return (
+    <Sheet.Root open={open} onOpenChange={setOpen}>
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="field.calendar" />
+          </Button.Icon>
+          {date ? `Отгрузка ${FORMAT.format(date)}` : "Дата отгрузки"}
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content aria-label="Дата отгрузки">
+        <Sheet.Body>
+          <Datepicker.Panel
+            mode="single"
+            value={date}
+            onValueChange={(next) => {
+              setDate(next);
+              setOpen(false);
+            }}
+          />
+        </Sheet.Body>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

package/src/components/skeleton/COMPONENT.md

@@ -59,7 +59,7 @@ Skeleton           <span aria-hidden="true">; data-shape, data-size
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| pulsing | mounted | opacity eases 1 → 0.4 and back (`slow × 5`, `standard`, alternate) |
+| pulsing | mounted | opacity eases 1 → 0.6 and back (`slow × 5`, `standard`, alternate) |
 | reduced motion | `prefers-reduced-motion: reduce` | no pulse: the placeholder stands still and stays visible |
 | shape / size | `shape`, `size` | `data-shape`, `data-size` |
 

package/src/components/slider/COMPONENT.md

@@ -39,18 +39,21 @@ Slider                 field frame (FieldFrame): className, ref, rest
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Slider
-`ref` → `HTMLDivElement` (the field frame). A framed field like every other: the label row with the value, a native `<input type="range">` (transparent, on top) over the visual track, fill and thumb, then the hint or the error. Field-root rule: `className`, `ref` and the rest go to the frame; `id` and `aria-label` to the range input.
+`ref` → `HTMLDivElement` (the field frame). A framed field: the label row with the value, a native `<input type="range">` over the visual track, then the hint or the error. `id` and `aria-label` go to the range input.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `number` | — | Controlled value; clamped to `min`…`max`. |
 | `defaultValue` | `number` | `min` | Initial value when uncontrolled. |
 | `onValueChange` | `(value: number) => void` | — | Called with the new number while dragging and on every key step. |
+| `onCommit` | `(value: number) => void \| Promise<void>` | — | The value the person settled on, once after a drag or a key step. Save here, not in `onValueChange`. Return the save's promise: the thumb dims until it settles; on reject the value goes back. |
+| `name` | `string` | — | Name of the range input, submitted with a form. |
 | `min` | `number` | `0` | Lower bound. |
 | `max` | `number` | `100` | Upper bound. |
 | `step` | `number` | `1` | Step of the keyboard and of the snapping; fractions allowed. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the track thickness T (thumb 4.5T × 3T), the label, the value and the hint. Without it the tier of its host (a form, a panel), else `m`. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Color of the filled part of the track. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` — the track stands upright, minimum at the bottom: a level beside a button, a mixer column. |
 | `disabled` | `boolean` | — | Muted track and thumb, dimmed label and value, no interaction. |
 | `label` | `ReactNode` | — | Visible label linked to the range input (`<label htmlFor>`). Without it, set `aria-label`. |
 | `required` | `boolean` | — | Red `*` after the label (`aria-hidden`); a range always has a value, so there is no native `required`. |
@@ -80,7 +83,7 @@ Everything derives from the tier track thickness T (`--prime-control-<tier>-trac
 | `l` | 7px track, 31.5×21 thumb, 14/20 label | spacious settings pages | |
 | `xl` | 8px track, 36×24 thumb, 14/20 label | touch-first screens | |
 
-**Sizes:** the slider fills its container and never gets narrower than 192px (like a native range); the tier changes the track, the thumb and the label / value text. Use the same tier as the other fields of the form.
+**Sizes:** the slider fills its container; the tier changes the track, the thumb and the label / value text. Use the same tier as the other fields of the form.
 
 ### tone
 | Value | Looks like | Use when | Default |
@@ -94,6 +97,12 @@ Everything derives from the tier track thickness T (`--prime-control-<tier>-trac
 
 Tone never carries meaning alone: the label names what the value means.
 
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | the track across its container | a value in a form or a panel | yes |
+| `vertical` | the track upright, minimum at the bottom, seven thumbs long at its tier; the label row above it | a level beside a button (a video's sound), a column of a mixer | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -104,18 +113,21 @@ Tone never carries meaning alone: the label names what the value means.
 - `showValue` + `formatValue` for any value with a unit; `formatValue` alone only changes `aria-valuetext`.
 - Neither `label` nor `aria-label` → forbidden (unnamed control).
 - A paired number input with `showValue` → redundant; drop `showValue`.
+- `onValueChange` for a live preview, `onCommit` to save: it fires once on pointer release or key release, only when the value differs from the last commit.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| default | — | `data-size`, `data-tone`; track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
+| default | — | `data-size`, `data-tone` (`data-orientation="vertical"` when upright); track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
 | hover | pointer (fine pointers only) | light liquid glass: the thumb grows to 110%, turns translucent and slightly frosted |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | pressed | dragging | clear glass: the thumb grows to 125%, the rounded end of the fill shows through |
 | focus-visible | keyboard | outer focus ring around the thumb |
 | disabled | `disabled` | `data-disabled="true"` on the root, native `disabled`; muted track and fill, flat thumb, `cursor: not-allowed` |
+| saving | `onCommit` returned a pending promise | `data-pending="true"` on the root, `aria-busy` on the input; the thumb quiets to 0.6 (`fast`, both ways); the slider stays usable — only the latest commit's answer counts |
+| refused | that promise rejected | the value goes back to the last saved one (`onValueChange` when controlled); `data-settling` glides the thumb and the fill there (`base`, emphasized) |
 
-Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back to `min`).
+Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back to `min`). Both are clamped to `min`…`max`. `onCommit` reports the settled value after a drag or a key step.
 
 ## Layout & spacing
 - Fills its container; place it in a grid column to limit the width.
@@ -136,8 +148,10 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 ### ARIA
 - A native `<input type="range">` (`role="slider"`) on top of the visual layer.
 - `label` is a `<label htmlFor>`; otherwise `aria-label` is required.
+- `orientation="vertical"` turns the native range with `writing-mode`, so ↑ / ↓ and the pointer work natively; the input has `aria-orientation="vertical"`.
 - `formatValue` sets `aria-valuetext`, so screen readers announce the unit; the visual `<output>` is `aria-hidden`.
 - `aria-describedby` on the input: your ids + the hint or the error; `aria-invalid` when invalid.
+- While a commit is saved the input has `aria-busy`; say why a refused value went back with `error`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -153,9 +167,11 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 | [variants.tsx](examples/variants.tsx) | Every fill color; accent by default, semantic tones when the value carries meaning — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the thumb, the label and the value grow with the tier — `size`. |
 | [states.tsx](examples/states.tsx) | The fill at both ends and a disabled slider — `disabled`. |
+| [orientation.tsx](examples/orientation.tsx) | Notification levels as a row of upright sliders, minimum at the bottom — `orientation`. |
 | [value-format.tsx](examples/value-format.tsx) | Units in the shown value that are also read by screen readers — `formatValue`, `showValue`. |
 | [range-step.tsx](examples/range-step.tsx) | Own bounds and a coarse or fractional step; a slider without a visible label — `min`, `max`, `step`, `aria-label`. |
 | [hint-and-error.tsx](examples/hint-and-error.tsx) | A slider framed like every field: required marker, a hint, and an error in its place — `required`, `hint`, `error`, `optional`. |
+| [autosave.tsx](examples/autosave.tsx) | A setting saved once the thumb is let go, not on every step: the thumb waits dimmed while it saves, and a value the server refuses glides back — `onCommit`, `hint`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value and shares it with a number field for exact entry — `value`, `onValueChange`. |
 
 ## Mistakes
@@ -163,6 +179,7 @@ Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back
 - A slider for an exact amount → use `Input type="number"`.
 - `tone="danger"` as the only signal of a dangerous value → say it in the label.
 - No `label` and no `aria-label` → the control has no name.
+- Saving a setting in `onValueChange` → it fires on every step of a drag; save in `onCommit`.
 
 ## Related
 - **Built from:** the field frame — [Label](../label/COMPONENT.md) (`label`) and [Hint](../hint/COMPONENT.md) (`hint`, `error`)

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

@@ -0,0 +1,39 @@
+/** A setting saved once the thumb is let go, not on every step: the thumb waits dimmed while it saves, and a value the server refuses glides back — `onCommit`, `hint`, `error`. */
+import { Slider } from "prime-ui-kit";
+import * as React from "react";
+
+/** The server saving the reminder lead time a beat later: more than ten days is not allowed. */
+function saveLeadTime(days: number) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (days > 10) reject(new Error("Тариф позволяет напоминать не раньше чем за 10 дней"));
+      else resolve();
+    }, 600);
+  });
+}
+
+export default function SliderAutosaveExample() {
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <Slider
+      label="Напоминать об оплате счёта"
+      min={1}
+      max={14}
+      defaultValue={3}
+      showValue
+      formatValue={(days) => `за ${days} дн.`}
+      hint="Сохраняется само, когда вы отпустите ползунок"
+      error={error}
+      onCommit={async (days) => {
+        setError(undefined);
+        try {
+          await saveLeadTime(days);
+        } catch (reason) {
+          setError(reason instanceof Error ? reason.message : String(reason));
+          throw reason;
+        }
+      }}
+    />
+  );
+}

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

@@ -16,3 +16,9 @@
   gap: var(--prime-space-4);
   width: min(100%, var(--prime-modal-width-s));
 }
+
+/* orientation.tsx: upright sliders side by side, a mixer row. */
+.levels {
+  display: flex;
+  gap: var(--prime-space-8);
+}