prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/components/button/COMPONENT.md

@@ -12,7 +12,9 @@
 - Destructive actions without a dialog: `holdToConfirm` needs a held press.
 - Compact toolbars: icon-only buttons (only `Button.Icon` inside) are square.
 - Round icon actions — the disk is the control (play, download, cancel or retry of a transfer, a floating main action): `shape="circle"`; over a picture or a video, `variant="shade"`. A transfer it can cancel shows its share as the circle's `progress` ring.
-- Action-styled navigation: `asChild` with an `<a>` or a router link.
+- Action-styled navigation: `asChild` with an `<a>` or a router link; the current page of a set (page numbers) is `current`.
+- A single toggle (favourite, pin): the `pressed` / `defaultPressed` / `onPressedChange` triad.
+- A floating action beside a glass bar: `variant="glass"`; a host that sets its own height (the BottomNav capsule) gives it through `--prime-control-height`.
 
 ## When not to use
 - Inline text link or quiet navigation in text → use [LinkButton](../link-button/COMPONENT.md).
@@ -31,7 +33,7 @@ import { Button } from "prime-ui-kit";
 Button.Root        <button> (or the single child with asChild); variant, tone, size; size tier for nested icons
 ├─ (fill)          progress / hold wash under the label, rendered by Root once used, aria-hidden
 ├─ (ring)          a circle's progress ring along its inner edge (internal/ring), once used, aria-hidden
-├─ (Spinner)       rendered by Root while loading, aria-hidden
+├─ (Spinner)       rendered by Root while loading: the leading icon's glyph, else over the label; aria-hidden
 ├─ (label)         text children; a changed label flows in letter by letter
 └─ Button.Icon     decorative icon wrapper (aria-hidden), sized to the tier
 (hold hint)        visually hidden description beside the button with holdToConfirm
@@ -46,22 +48,27 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "shade"` | `"solid"` | Visual treatment: fill, soft fill, line or transparent. `shade` — the media shade with a light glyph for a button over a picture or video; with `tone="danger"` — the error disk. |
+| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "shade" \| "glass"` | `"solid"` | Visual treatment: fill, soft fill, line or transparent. `shade` — the media shade for a button over a picture or video (with `tone="danger"`, the error disk); `glass` — the glass of a floating bar. |
 | `shape` | `"square" \| "circle"` | `"square"` | Outline. `circle` — a disk as wide as it is tall, with only a `Button.Icon` inside; same tiers, tones and variants. Requires `aria-label`. |
 | `tone` | `"accent" \| "neutral" \| "success" \| "danger" \| "inherit"` | `"accent"` | Meaning: primary, secondary, done (`success`) or destructive (`danger`). `inherit` takes the host's text color for an action on a colored host; only with `ghost`, `soft` or `outline`. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier: height 28 · 32 · 36 · 40 · 48, padding, text, icon, radius. Without it the button takes the tier of its host (LoginForm, Popover, a field, a panel with a size), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier: height 28 · 32 · 36 · 40 · 48, padding, text, icon, radius. Without it the button takes the tier of its host (LoginForm, Popover, a field, a panel with a size), else `m`. |
+| `density` | `"regular" \| "tight" \| "inline"` | `"regular"` | `tight` — a number in a row of controls: tabular figures and 4px side air, so two digits stay square (page numbers). `inline` — a chip inside a line of text, as tall as the line, in its type. |
+| `align` | `"center" \| "start"` | `"center"` | Where the content sits: `start` reads from the start edge, for a column of choices (presets). |
 | `fullWidth` | `boolean` | — | Stretches to the container width. |
-| `loading` | `boolean` | `false` | Shows a `Spinner` in place of the leading icon or over the label, sets `aria-busy`, blocks clicks; width does not change. With `asChild` no spinner is added — the child owns its content. |
-| `pressed` | `boolean` | — | A toggle button: `true` on, `false` off (`aria-pressed`). On takes the selected look, an accent soft fill that glides in and out. Leave it out for an ordinary action; a set of toggles is a ButtonGroup. |
+| `loading` | `boolean` | `false` | A `Spinner` takes the leading icon's glyph (or stands over the label), sets `aria-busy`, blocks clicks; width does not change. With `asChild` no spinner is added — the child owns its content. |
+| `pressed` | `boolean` | — | A toggle button: `true` on, `false` off (`aria-pressed`); on takes the selected look (accent soft). Leave the triad out for an ordinary action; a set of toggles is a ButtonGroup. |
+| `defaultPressed` | `boolean` | — | The initial state of an uncontrolled toggle; a click, `Enter` or `Space` flips it. |
+| `onPressedChange` | `(pressed: boolean) => void` | — | Fires with the new state when the toggle is pressed; an `onClick` that calls `preventDefault()` keeps the state. |
+| `current` | `boolean` | `false` | The current page of a set (a page number): `aria-current="page"` and the selected look. A router link with its own `aria-current` gets the same look. |
 | `progress` | `number \| null` | — | Progress of a long action, `0…1`; `null` — the share is unknown. Sets `aria-busy`, stays pressable (to cancel); a square fills from the start edge, a circle draws a ring. Remove the prop when done. |
 | `holdToConfirm` | `boolean` | `false` | The action needs a held press (pointer, `Space` or `Enter`): the fill runs for 1.2 s, then `onConfirm` fires; releasing earlier rolls it back. |
 | `onConfirm` | `() => void \| Promise<void>` | — | Fires when a `holdToConfirm` press completes; the action goes here, not in `onClick`. Return the request's promise to keep the button `loading` until it settles. |
 | `labels` | `Partial<ButtonLabels>` | — | Built-in strings, see Labels. |
-| `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`. |
-| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type; not forwarded with `asChild`. |
-| `disabled` | `boolean` | — | Disabled state; `loading` also disables. |
-| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. |
-| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | `onClick`, `className`, `aria-*`, `data-*` and the other button attributes. |
+| `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element (a link) instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`; `progress` and `holdToConfirm` need a `<button>`. |
+| `disabled` | `boolean` | — | Disabled state; `loading` also disables. With `asChild` the child leaves the Tab order and a link loses its `href`. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element. |
+| `aria-label` | `string` | — | The name of a button without a visible label; required with `shape="circle"`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size" \| "aria-pressed">` | — | `onClick`, `type` (`"button"` by default, not passed on with `asChild`), `className`, `aria-*`, `data-*` and the other button attributes. |
 
 ### Button.Icon
 `ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the button tier.
@@ -69,7 +76,8 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="action.copy" />`; `Icon` without `size` takes the button tier. A new icon (another `name`) cross-fades in and plays its gesture once (`fast`). |
-| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+| `className` | `string` | — | Class on the icon box. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | The other span attributes. |
 
 ## Variants
 
@@ -95,10 +103,11 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `outline` + `inherit` | 1px inset line in a `currentColor` wash, the host's text color | an action with an edge on a colored host | |
 | `shade` (+ `accent` / `neutral` / `success`) | the media disk ground (`--prime-color-media-disk`, lighter than the pills' `media-shade`) under a gentle backdrop blur (`--prime-media-disk-blur`), so the frame shows through, and its light glyph (≥ 3:1 even over a white frame); the same in both themes and the same look as the still play mark of a video frame | a button over a picture, a video or a video circle (edit a cover, cancel an upload) | |
 | `shade` + `danger` | the danger fill, danger-fg glyph | a failed transfer over media: the retry | |
+| `glass` | the glass of a floating bar (`--prime-color-bg-glass`) over a strong backdrop blur (`--prime-glass-blur`), ink text; the solid floating fill where the user asks for less transparency; the host draws the rim and the lift | a floating action beside a glass bar, a labelled action over a photo | |
 
 `tone="inherit"` has no `solid` (the type requires `ghost`, `soft` or `outline`); its focus ring and disabled look also derive from the host's text color, so it reads on any host fill in both themes. Never recolor a Button from its host with a CSS override — use `inherit`.
 
-`outline` is the only variant with a visible line. With `aria-current="page"` (usually via `asChild` on a router link), `ghost`/`soft` show the `fill-subtle-active` selected look; soft accent keeps its own accent look, so a current item can be marked with accent explicitly (Pagination).
+`outline` is the only variant with a visible line. `current` (or `aria-current="page"` set by a router link through `asChild`) and an on toggle take the selected look — accent soft — over any tone × variant.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -117,48 +126,68 @@ A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedContr
 | `square` | the tier's radius; with only `Button.Icon`, a square | every labelled button, toolbar icon buttons | yes |
 | `circle` | a disk: width = the tier height, full radius; the focus ring, the touch area and the press (`press-scale-compact`, 0.96) follow the circle; `progress` draws a ring along the inner edge in the glyph's color | play / download / cancel / retry disks, a floating main action; only `Button.Icon` inside, `aria-label` required | |
 
+### density
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `regular` | the tier's padding | every button | yes |
+| `tight` | 4px side air, tabular figures; one or two digits stay square (the height is the minimum width) | page numbers, a count in a row of controls | |
+| `inline` | as tall as the line of text it sits in, the text's own type, 4px side air, a pill; the touch area still applies | a chip inside a caption line (a playback speed) | |
+
+### align
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `center` | content centred | every button | yes |
+| `start` | content from the start edge | a column of choices or actions (`fullWidth` rows, presets) | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `fullWidth` | button fills the row | narrow forms, cards, mobile footers | off |
 | icon-only (children are only `Button.Icon`) | square, width = height | toolbars; needs `aria-label` | — |
-| `pressed` | on: accent soft fill and accent text over any variant; off: the variant's own look | a single toggle (favourite, pin, «show archived») | — (not a toggle) |
+| `pressed` / `defaultPressed` | on: accent soft fill and accent text over any variant; off: the variant's own look | a single toggle (favourite, pin, «show archived») | — (not a toggle) |
+| `current` | the selected look, `aria-current="page"` | the current page of a set (page numbers) | off |
 
 **Hierarchy:** one primary (`solid accent`) per area, the rest neutral `soft`/`outline`/`ghost`; a destructive action is `tone="danger"` and sits apart (start of the footer). Avoid two `solid accent` buttons side by side and `tone="danger"` for non-destructive actions.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| hover / active | pointer | hover fill per variant; active `scale(var(--prime-motion-press-scale))` |
+| hover / active | pointer | hover fill per variant; press gives to `--prime-motion-press-scale` (`-compact` on a circle) through the shared `internal/press`; not while disabled, loading or busy |
 | focus-visible | keyboard | outer focus ring with `--prime-focus-offset`; `tone="inherit"` draws it in `currentColor` |
 | disabled | `disabled`, or a disabled `Fieldset` around it | native `disabled`, `data-disabled="true"`, `fill-muted` + `text-disabled`, `cursor: not-allowed`; ghost stays transparent |
-| loading | `loading` (native `<button>`) | `data-loading="true"`, native `disabled`, `aria-busy="true"`, colors kept (busy, not unavailable), no hover or press; a `Spinner` (`aria-hidden`) replaces the leading (or only) icon, otherwise it is centered over the hidden label (`data-loading-overlay="true"`) |
+| loading | `loading` (native `<button>`) | `data-loading="true"`, native `disabled`, `aria-busy="true"`, colors kept (busy, not unavailable), no hover or press; the leading (or only) icon's glyph cross-fades into a `Spinner` (`aria-hidden`) and back, otherwise the spinner is centered over the hidden label (`data-loading-overlay="true"`) |
 | progress | `progress` (0…1) | `data-progress="true"`, `aria-busy="true"`, still pressable; a plate of the text color with the button's radius slides in from the start edge (`fast` · standard), so corners match at any value; removing the prop fades it where it is |
-| progress unknown (square) | `progress={null}` | `data-spinner="true"`, `aria-busy="true"`, still pressable; a `Spinner` takes the leading icon's place as with `loading` |
+| progress unknown (square) | `progress={null}` | `aria-busy="true"`, still pressable; a `Spinner` takes the leading icon's glyph (or stands over the label, `data-loading-overlay="true"`) as with `loading` |
 | progress (circle) | `shape="circle"` + `progress` (0…1 or `null`) | `aria-busy="true"`, still pressable; the kit ring at the line weight along the inner edge, arc in the glyph's color over a 32% track, always turning (3 × `--prime-motion-loop` a turn, slower but never still under reduced motion; never under 8%; `null` a quarter arc); the share glides (`base`); removing the prop fades the ring where it is (`data-shown="false"`, its turn paused) |
 | glyph change | a new icon in `Button.Icon` (another `name`) | the old glyph shrinks to 0.6 and fades, the new one grows in (`fast`) and plays its gesture once; reduced motion swaps at once |
 | holding | `holdToConfirm` + a held pointer, `Space` or `Enter` | `data-hold="holding"`: the fill runs linearly for 1.2 s (kept under reduced motion — it is a gesture clock), then `onConfirm` and `data-hold="done"` (on release the fill fades in place, `data-hold="idle"`); releasing, leaving the button or losing focus earlier → `data-hold="cancel"`, the fill rolls back (`fast` · exit) |
 | confirming | `onConfirm` returned a pending promise | `data-hold="confirming"`: the full fill stays, the button is `loading` (spinner, `aria-busy`, disabled) even after the release; resolve → `data-hold="idle"`, the fill fades; reject → `data-hold="cancel"`, the fill rolls back (say why with a notification) |
 | label change | new text children | the old letters leave upward, the new ones rise from below one short step apart (`base` · emphasized, blur `--prime-motion-blur`) while the width glides; digits-only changes and reduced motion change in place |
-| pressed | `pressed` | `aria-pressed="true" \| "false"`; on adds `data-pressed="true"` and the selected fill (accent soft), which glides in and out with the color transition (`fast`) |
-| asChild disabled / loading | `asChild` + `disabled`/`loading` | `aria-disabled="true"`, `pointer-events: none`, click `preventDefault`; no native `disabled`, no automatic spinner |
+| pressed | `pressed`, or `defaultPressed` flipped by a press | `aria-pressed="true" \| "false"`; on adds `data-pressed="true"` and the selected fill (accent soft), which glides in and out with the color transition (`fast`); `onPressedChange` gets the new state |
+| current | `current` | `aria-current="page"`, `data-current="true"`, the selected fill |
+| asChild disabled / loading | `asChild` + `disabled`/`loading` | `aria-disabled="true"`, `tabIndex=-1`, a link child loses its `href`, `pointer-events: none`, the click is stopped; no native `disabled`, no automatic spinner |
 
-Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`, `data-shape`, `data-full-width`, `data-icon-only`, `data-leading-icon`, `data-trailing-icon`.
+Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-shape`, `data-density`, `data-align`, `data-full-width`, `data-icon-only`, `data-leading-icon`, `data-trailing-icon`.
 
 ## Layout & spacing
-- Buttons in a row: `gap: var(--prime-space-2)`–`var(--prime-space-3)`; toolbar icon buttons `var(--prime-space-1)`.
-- Form footer: actions right-aligned, primary last; below 480px stack full width (`fullWidth` or a column flex).
+- Buttons in a row: a gap of space step 2–3 (8–12px); toolbar icon buttons step 1 (4px).
+- Form footer: actions at the end, primary last; in a narrow container they stack full width (`fullWidth` in a column).
+- Height: the tier's (`size`), or the host's through `--prime-control-height` (a glass action as tall as the BottomNav capsule).
 - `max-width: 100%`, the label does not wrap (`white-space: nowrap`).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `Enter` · `Space` | Presses the button (native `<button>`); with `holdToConfirm` the key is held until the fill completes. |
-| `Tab` | Moves focus; a disabled button is skipped, with `asChild` it stays focusable with `aria-disabled`. |
+| `Enter` · `Space` | Presses the button (native `<button>`); a toggle flips its state; with `holdToConfirm` the key is held until the fill completes. |
+| `Tab` | Moves focus; a disabled button is skipped, the `asChild` child too (`tabIndex=-1`, `aria-disabled`). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Native `<button>`, `type="button"` by default, so it never submits a form by accident.
 - Icon-only buttons need `aria-label`; `Button.Icon` is `aria-hidden`.
 - `progress` is visual only: put the share in the label or in `aria-describedby` («Скачивание 42%»).
@@ -166,7 +195,8 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 - `loading` sets `aria-busy="true"` and blocks the press; `progress` sets `aria-busy` and keeps the button pressable.
 - `holdToConfirm` describes the gesture through `aria-describedby` (`labels.holdHint`); `Space` / `Enter` hold like a pointer.
 - A changed label is announced once: the animated letters are hidden, the name is the new text.
-- With `asChild` the disabled state is `aria-disabled="true"` without a native `disabled`.
+- With `asChild` the disabled state is `aria-disabled="true"` without a native `disabled`; a link child loses its `href`.
+- A toggle (`pressed`, `defaultPressed` or `onPressedChange`) carries `aria-pressed`; `current` sets `aria-current="page"`. Both are named states, never color alone: the selected fill comes with the attribute.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -185,12 +215,15 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before or after the label, and a square icon-only button — `Button.Icon`, `aria-label`. |
 | [download.tsx](examples/download.tsx) | A long download inside the button: the fill shows how far it got, the label counts and then offers the file — `progress`. |
 | [circle.tsx](examples/circle.tsx) | Round icon buttons in every treatment, and a disk whose ring tracks an export it can cancel — `shape`, `variant`, `tone`, `progress`. |
-| [over-media.tsx](examples/over-media.tsx) | Buttons over a listing's cover stand on the media shade; a failed upload turns its disk danger — `variant`, `shape`, `tone`. |
-| [toggle.tsx](examples/toggle.tsx) | A toggle in a toolbar: the favourite mark turns the button on with the selected fill and back off — `pressed`. |
+| [over-media.tsx](examples/over-media.tsx) | Buttons over a listing's cover: round actions on the media shade, a labelled one on glass; a failed upload turns its disk danger — `variant`, `shape`, `tone`. |
+| [toggle.tsx](examples/toggle.tsx) | A toggle in a toolbar keeps its own state: the favourite mark turns the button on with the selected fill and back off — `defaultPressed`. |
+| [density.tsx](examples/density.tsx) | Page numbers stay square and the current one takes the selected look; a speed chip sits inside a caption line — `density`, `current`. |
+| [align.tsx](examples/align.tsx) | A column of export actions reads from the start edge, every row the full width — `align`, `fullWidth`. |
 | [hold-to-confirm.tsx](examples/hold-to-confirm.tsx) | A destructive action that needs a held press; letting go early rolls the fill back and does nothing, and the delete request keeps the button loading until the server answers — `holdToConfirm`, `onConfirm`. |
-| [label-morph.tsx](examples/label-morph.tsx) | A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `children`, `loading`, `tone`. |
-| [on-colored-host.tsx](examples/on-colored-host.tsx) | Actions on a colored strip take its text color: a ghost icon close and a soft action — `tone="inherit"`. |
+| [label-morph.tsx](examples/label-morph.tsx) | A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `loading`, `tone`. |
+| [on-colored-host.tsx](examples/on-colored-host.tsx) | Actions on a solid banner take its text color: a soft action and a ghost one beside it — `tone="inherit"`. |
 | [as-child.tsx](examples/as-child.tsx) | The button look on a real link; a disabled link blocks navigation — `asChild`, `disabled`. |
+| [controlled.tsx](examples/controlled.tsx) | A toggle whose state the screen owns: pinning an order shows the note under it — `pressed`, `onPressedChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A full-width submit button that shows the request in progress after the email passes validation — `type`, `loading`, `fullWidth`. |
 
 ## Mistakes
@@ -199,6 +232,9 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 - `tone="error"` / `variant="primary"` → `tone="danger"`, `variant="solid"`.
 - A toggle drawn by switching `variant` or `tone` → `pressed`: it sets `aria-pressed` and the selected look; changing the label instead («Закрепить» / «Открепить») is a plain action, without `pressed`.
 - Putting a `<Spinner />` inside a loading button → just set `loading`; the button places it.
+- A page number styled by a host CSS override (padding, tabular figures, a current fill) → `density="tight"` and `current`.
+- A Button recolored to glass or resized by a host class → `variant="glass"`, and the host height through `--prime-control-height`.
+- `asChild` with `progress` or `holdToConfirm` → the type refuses it: a link has no fill or hold; use a `<button>`.
 - `<a>` inside `<Button.Root>` → use `asChild` so there is one interactive element.
 - Submit button without `type="submit"` → the default is `"button"` and will not submit.
 - A destructive `holdToConfirm` action in `onClick` → it fires on any click; put it in `onConfirm`.
@@ -207,5 +243,5 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 - Rebuilding a progress label with a new word every tick («Загрузка…» / «Скачивание…») → keep the words, change only the number; digits update in place, words morph.
 
 ## Related
-- **Built from:** [Spinner](../spinner/COMPONENT.md), `internal/ring` (the circle's progress ring), `internal/glyphSwap` (the icon cross-fade), `internal/MorphText` (the label morph)
+- **Built from:** [Spinner](../spinner/COMPONENT.md), `internal/ring` (the circle's progress ring), `internal/glyphSwap` (the icon and spinner cross-fade), `internal/MorphText` (the label morph), `internal/interactiveElement` (`asChild`), `internal/press` (press feedback), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ButtonGroup](../button-group/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md)

package/dist/skill/reference/components/button/examples/align.tsx

@@ -0,0 +1,25 @@
+/** A column of export actions reads from the start edge, every row the full width — `align`, `fullWidth`. */
+import { Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EXPORTS = [
+  { icon: "object.document", label: "Счёт в PDF" },
+  { icon: "object.chart", label: "Отчёт в Excel" },
+  { icon: "action.send", label: "Отправить бухгалтеру" },
+] as const;
+
+export default function ButtonAlignExample() {
+  return (
+    <div className={styles.column}>
+      {EXPORTS.map((item) => (
+        <Button.Root key={item.label} variant="ghost" tone="neutral" align="start" fullWidth>
+          <Button.Icon>
+            <Icon name={item.icon} />
+          </Button.Icon>
+          {item.label}
+        </Button.Root>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/button/examples/controlled.tsx

@@ -0,0 +1,21 @@
+/** A toggle whose state the screen owns: pinning an order shows the note under it — `pressed`, `onPressedChange`. */
+import { Button, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function ButtonControlledExample() {
+  const [pinned, setPinned] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root variant="ghost" tone="neutral" pressed={pinned} onPressedChange={setPinned}>
+        <Button.Icon>
+          <Icon name="action.pin" />
+        </Button.Icon>
+        Закрепить заказ
+      </Button.Root>
+      <Typography variant="body-s" tone="muted">
+        {pinned ? "Заказ № 4815 закреплён вверху списка" : "Заказ № 4815 в общем списке"}
+      </Typography>
+    </>
+  );
+}

package/dist/skill/reference/components/button/examples/density.tsx

@@ -0,0 +1,45 @@
+/** Page numbers stay square and the current one takes the selected look; a speed chip sits inside a caption line — `density`, `current`. */
+import { Button, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PAGES = [1, 2, 3, 4, 12] as const;
+const SPEEDS = ["1×", "1,5×", "2×"] as const;
+
+export default function ButtonDensityExample() {
+  const [page, setPage] = React.useState<number>(3);
+  const [speed, setSpeed] = React.useState(0);
+
+  return (
+    <>
+      <nav aria-label="Страницы счетов" className={styles.row}>
+        {PAGES.map((item) => (
+          <Button.Root
+            key={item}
+            variant="ghost"
+            tone="neutral"
+            density="tight"
+            current={item === page}
+            aria-label={`Страница ${item}`}
+            onClick={() => setPage(item)}
+          >
+            {item}
+          </Button.Root>
+        ))}
+      </nav>
+      <Typography variant="caption" tone="muted">
+        Голосовое сообщение · 0:42 ·{" "}
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          density="inline"
+          aria-label={`Скорость ${SPEEDS[speed]}`}
+          onClick={() => setSpeed((speed + 1) % SPEEDS.length)}
+        >
+          {SPEEDS[speed]}
+        </Button.Root>
+      </Typography>
+    </>
+  );
+}

package/dist/skill/reference/components/button/examples/examples.module.css

@@ -6,26 +6,6 @@
   gap: var(--prime-space-5);
 }
 
-/* A colored strip: buttons with tone="inherit" take its text color. */
-.accentHost,
-.inverseHost {
-  display: flex;
-  align-items: center;
-  gap: var(--prime-space-2);
-  padding: var(--prime-space-2) var(--prime-space-2) var(--prime-space-2) var(--prime-space-4);
-  border-radius: var(--prime-radius-l);
-}
-
-.accentHost {
-  background: var(--prime-color-accent-default);
-  color: var(--prime-color-accent-fg);
-}
-
-.inverseHost {
-  background: var(--prime-color-bg-inverse);
-  color: var(--prime-color-text-inverse);
-}
-
 /* A row of round buttons. */
 .row {
   display: flex;
@@ -34,7 +14,14 @@
   gap: var(--prime-space-3);
 }
 
-/* A listing cover with its round actions at the top end. */
+/* align.tsx: a column of full-width actions, as wide as a side panel. */
+.column {
+  display: grid;
+  gap: var(--prime-space-1);
+  width: min(100%, var(--prime-layout-form-width-s));
+}
+
+/* A listing cover with its round actions at the top end and a glass action at the bottom. */
 .cover {
   position: relative;
 }
@@ -43,12 +30,14 @@
   position: absolute;
   inset-block-start: var(--prime-space-2);
   inset-inline-end: var(--prime-space-2);
-  z-index: 1;
+  z-index: var(--prime-z-raised);
   display: flex;
   gap: var(--prime-space-2);
 }
 
-.hostText {
-  flex: 1;
-  min-width: 0;
+.coverGallery {
+  position: absolute;
+  inset-block-end: var(--prime-space-2);
+  inset-inline-start: var(--prime-space-2);
+  z-index: var(--prime-z-raised);
 }

package/dist/skill/reference/components/button/examples/label-morph.tsx

@@ -1,4 +1,4 @@
-/** A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `children`, `loading`, `tone`. */
+/** A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `loading`, `tone`. */
 import { Button } from "prime-ui-kit";
 import * as React from "react";
 

package/dist/skill/reference/components/button/examples/on-colored-host.tsx

@@ -1,28 +1,28 @@
-/** Actions on a colored strip take its text color: a ghost icon close and a soft action — `tone="inherit"`. */
-import { Button, Icon } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Actions on a solid banner take its text color: a soft action and a ghost one beside it — `tone="inherit"`. */
+import { Banner, Button } from "prime-ui-kit";
 
 const HOSTS = [
-  { className: styles.accentHost, text: "Доступна новая версия редактора" },
-  { className: styles.inverseHost, text: "Режим только для чтения" },
-];
+  { tone: "accent", text: "Доступна новая версия редактора", action: "Обновить", later: "Позже" },
+  { tone: "neutral", text: "Режим только для чтения", action: "Запросить доступ", later: "Скрыть" },
+] as const;
 
 export default function ButtonOnColoredHostExample() {
   return (
     <>
-      {HOSTS.map(({ className, text }) => (
-        <div key={text} className={className}>
-          <span className={styles.hostText}>{text}</span>
-          <Button.Root variant="soft" tone="inherit" size="s">
-            Обновить
-          </Button.Root>
-          <Button.Root variant="ghost" tone="inherit" size="s" aria-label="Закрыть">
-            <Button.Icon>
-              <Icon name="action.close" />
-            </Button.Icon>
-          </Button.Root>
-        </div>
+      {HOSTS.map(({ tone, text, action, later }) => (
+        <Banner.Root key={text} variant="solid" tone={tone}>
+          <Banner.Content>
+            <Banner.Title>{text}</Banner.Title>
+          </Banner.Content>
+          <Banner.Actions>
+            <Button.Root variant="soft" tone="inherit">
+              {action}
+            </Button.Root>
+            <Button.Root variant="ghost" tone="inherit">
+              {later}
+            </Button.Root>
+          </Banner.Actions>
+        </Banner.Root>
       ))}
     </>
   );

package/dist/skill/reference/components/button/examples/over-media.tsx

@@ -1,4 +1,4 @@
-/** Buttons over a listing's cover stand on the media shade; a failed upload turns its disk danger — `variant`, `shape`, `tone`. */
+/** Buttons over a listing's cover: round actions on the media shade, a labelled one on glass; a failed upload turns its disk danger — `variant`, `shape`, `tone`. */
 import { Button, Icon, Thumbnail } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -31,6 +31,12 @@ export default function ButtonOverMediaExample() {
           </Button.Icon>
         </Button.Root>
       </div>
+      <Button.Root variant="glass" tone="neutral" className={styles.coverGallery}>
+        <Button.Icon>
+          <Icon name="object.image" />
+        </Button.Icon>
+        Все 12 фото
+      </Button.Root>
     </div>
   );
 }

package/dist/skill/reference/components/button/examples/toggle.tsx

@@ -1,17 +1,9 @@
-/** A toggle in a toolbar: the favourite mark turns the button on with the selected fill and back off — `pressed`. */
+/** A toggle in a toolbar keeps its own state: the favourite mark turns the button on with the selected fill and back off — `defaultPressed`. */
 import { Button, Icon } from "prime-ui-kit";
-import * as React from "react";
 
 export default function ButtonToggleExample() {
-  const [favorite, setFavorite] = React.useState(true);
-
   return (
-    <Button.Root
-      variant="ghost"
-      tone="neutral"
-      pressed={favorite}
-      onClick={() => setFavorite((value) => !value)}
-    >
+    <Button.Root variant="ghost" tone="neutral" defaultPressed>
       <Button.Icon>
         <Icon name="status.favorite" />
       </Button.Icon>

package/dist/skill/reference/components/button-group/COMPONENT.md

@@ -25,7 +25,7 @@ import { ButtonGroup } from "prime-ui-kit";
 ## Anatomy
 ```
 ButtonGroup.Root            field frame: label row · group · support row (hint | error)
-└─ (group)                  <div role="group">; size and orientation for every segment
+└─ (group)                  <div role="group">: a row is the switcher row, a column stacks
    └─ ButtonGroup.Item      one segment, a native <button>; optional pressed toggle
       └─ ButtonGroup.Icon   decorative icon wrapper (aria-hidden), sized to the tier
 ```
@@ -36,13 +36,13 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### ButtonGroup.Root
-`ref` → `HTMLDivElement` (the field frame). The field: label · `<div role="group">` with the segments · support row; sets the tier and orientation of every segment and passes the tier to nested icons. The frame hugs the group unless `fullWidth`.
+`ref` → `HTMLDivElement` (the field frame). The field: label · `<div role="group">` with the segments (a row scrolls as a switcher, a column stacks) · support row; sets the tier and orientation of every segment. The frame hugs the group unless `fullWidth`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier of every segment: height 28 · 32 · 36 · 40 · 48, padding, text, icon. Without it the tier of its host (a toolbar, a panel), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier of every segment: height 28 · 32 · 36 · 40 · 48, padding, text, icon. Without it the tier of its host (a toolbar, a panel), else `m`. |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the segments; `vertical` stretches them to the widest. |
-| `fullWidth` | `boolean` | — | Stretches the group; horizontal segments share the width equally. |
+| `fullWidth` | `boolean` | — | Stretches the group; horizontal segments tend to equal widths but never get narrower than their label (the row scrolls instead). |
 | `label` | `ReactNode` | — | Heading above the control; names the `group` (`aria-labelledby`). Without it give the root an `aria-label`. |
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `group`. |
 | `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
@@ -61,10 +61,9 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `pressed` | `boolean` | — | Toggle state: `aria-pressed` and `data-state="active" \| "inactive"`. Leave it out for a plain action segment. |
-| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type. |
 | `disabled` | `boolean` | — | Native disabled; a disabled `Fieldset` around the group sets it too. |
 | `children` | `ReactNode` | — | Label and `ButtonGroup.Icon`. Only icons → square segment; give it `aria-label`. |
-| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `className`, `aria-*` and the other button attributes. |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `type` (`"button"` unless set: `"submit"` / `"reset"` in a form), `onClick`, `className`, `aria-*` and the other button attributes. |
 
 ### ButtonGroup.Icon
 `ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the group tier.
@@ -96,7 +95,7 @@ A group lines up with Button, Input, Select and SegmentedControl of the same `si
 ### pressed
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| — (omitted) | `fill-muted` fill, secondary text; hover `fill-muted-hover` + primary text; active `fill-strong` | plain actions | yes |
+| — (omitted) | `fill-muted` fill, secondary text; hover `fill-muted-hover` + primary text | plain actions | yes |
 | `true` | `accent-soft` fill, accent text | the active toggle / selected option | |
 | `false` | same as plain, but `aria-pressed="false"` | the non-active members of a toggle set | |
 
@@ -105,7 +104,7 @@ Segments have no borders: they sit on the neutral fill and are separated by a 1p
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `fullWidth` | group fills the row, segments `flex: 1` | plan pickers in narrow columns | off |
+| `fullWidth` | group fills the row; segments tend to equal widths (`flex: 1 1 0`) but never get narrower than their label, the row scrolls instead | plan pickers in narrow columns | off |
 | icon-only (only `ButtonGroup.Icon` inside an Item) | square segment, width = height | toolbars; needs `aria-label` | — |
 
 Do not mix action segments and toggle segments in one group, and do not put the primary action inside the group — place a [Button](../button/COMPONENT.md) of the same size next to it.
@@ -113,28 +112,35 @@ Do not mix action segments and toggle segments in one group, and do not put the
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| hover / active | pointer | hover `fill-muted-hover` + primary text; active `fill-strong` + `scale(var(--prime-motion-press-scale))` (`-compact` for icon-only segments); disabled never scales |
-| pressed | `pressed` | `aria-pressed`, `data-state="active" \| "inactive"` |
+| hover / press | pointer | hover `fill-muted-hover` + primary text; a press scales the segment to `--prime-motion-press-scale` (`-compact` for icon-only segments, `internal/press`) and keeps its fill; disabled never scales |
+| pressed | `pressed` | `aria-pressed` (the look is styled from it), `data-state="active" \| "inactive"` |
 | disabled | `disabled` on an Item, or a disabled `Fieldset` around the group | native `:disabled`: `fill-muted` + `text-disabled`, `cursor: not-allowed` |
-| focus-visible | keyboard | outer focus ring, the segment is raised above neighbours (`z-index: 1`) |
+| focus-visible | keyboard | in a row the ring is inside the segment (the row scrolls, it clips); in a column the outer ring; the segment is raised above its neighbours |
 | invalid | `invalid` or non-empty `error` | group `data-invalid="true"` + `aria-invalid="true"`, an inset danger ring on every segment; the error replaces the hint; the segments shake once when an error arrives |
 | required | `required` | red `*` after the label, `aria-required="true"` on the group |
+| optional | `optional` | a muted `labels.optional` marker after the label |
+| support row reserved | `reserveSupportRow` | the support row stays rendered while empty, so an error arriving shifts nothing |
+| overflow | a row wider than its container | the row scrolls inside itself with faded edges (`data-overflow-start` / `data-overflow-end`), never wraps or truncates |
 
 Group attributes: `data-size`, `data-orientation="vertical"` (only when vertical), `data-full-width`. Item attributes: `data-icon-only`, `data-leading-icon`, `data-trailing-icon` (optical padding `padX − 4px` on the icon side). Selection is always owned by the parent: keep the value in state and set `pressed`.
 
 ## Layout & spacing
-- Groups in a toolbar: `gap: var(--prime-space-3)`; push the primary Button to the end with a flexible spacer.
-- `max-width: 100%`; labels do not wrap. Use `fullWidth` in narrow columns.
+- Groups in a toolbar: one tier gap between controls; push the primary Button to the end with a flexible spacer.
+- A row is a switcher (foundation §9): `max-width: 100%`, labels never wrap or truncate, and segments that do not fit scroll inside the row. Its host gives it a bounded width (`min-width: 0` on a flex child). Use `fullWidth` in narrow columns.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus between segments; a disabled one is skipped. |
 | `Enter` · `Space` | Presses the segment (native `<button>`). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The group element is `role="group"`, named by `label` (`aria-labelledby`); without a label give the root `aria-label`. Set `role="toolbar"` on the outer container of several groups.
 - Hint and error are linked through `aria-describedby`; an error sets `aria-invalid="true"`, `required` sets `aria-required="true"`.
 - Toggle segments expose `aria-pressed`; in a toggle set pass `pressed={false}` to the inactive ones.
@@ -156,7 +162,7 @@ Group attributes: `data-size`, `data-orientation="vertical"` (only when vertical
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments — `ButtonGroup.Icon`, `aria-label`. |
 | [orientation.tsx](examples/orientation.tsx) | A row of segments and a column of related options — `orientation`. |
 | [full-width.tsx](examples/full-width.tsx) | The group fills its column and the segments share the width equally — `fullWidth`. |
-| [controlled.tsx](examples/controlled.tsx) | One of several: the active segment lives in parent state and gets `pressed`. |
+| [controlled.tsx](examples/controlled.tsx) | One of several: the active segment lives in parent state — `pressed`. |
 | [in-form.tsx](examples/in-form.tsx) | A task form: the priority toggles are a labelled field checked on submit, an optional reminder, and native submit and reset segments in one group — `label`, `required`, `hint`, `error`, `optional`, `type`. |
 
 ## Mistakes
@@ -168,5 +174,5 @@ Group attributes: `data-size`, `data-orientation="vertical"` (only when vertical
 - A `Label` + `Hint` pair wired by hand around a toggle set in a form → `label`, `hint`, `error` on the root.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, a row), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md); `internal/press`
 - **See also:** [Button](../button/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Tabs](../tabs/COMPONENT.md)

package/dist/skill/reference/components/button-group/examples/controlled.tsx

@@ -1,4 +1,4 @@
-/** One of several: the active segment lives in parent state and gets `pressed`. */
+/** One of several: the active segment lives in parent state — `pressed`. */
 import { ButtonGroup } from "prime-ui-kit";
 import * as React from "react";