prime-ui-kit 0.10.0 → 0.11.0

package/src/components/button/COMPONENT.md

@@ -11,6 +11,7 @@
 - Long actions with known progress (downloads, exports): `progress` fills the button itself.
 - 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.
 
 ## When not to use
@@ -29,6 +30,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
 ├─ (label)         text children; a changed label flows in letter by letter
 └─ Button.Icon     decorative icon wrapper (aria-hidden), sized to the tier
@@ -44,19 +46,21 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `"solid" \| "soft" \| "outline" \| "ghost"` | `"solid"` | Visual treatment. |
-| `tone` | `"accent" \| "neutral" \| "success" \| "danger" \| "inherit"` | `"accent"` | Meaning of the action; `danger` for destructive actions; `success` for an action that is done (a payment went through). `inherit` takes the host's text color for an action on a colored host (a solid Banner); it needs `variant` `ghost`, `soft` or `outline`. |
+| `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. |
+| `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`. |
 | `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. |
-| `progress` | `number` | — | Progress of a long action started by the button, `0…1`: a wash of the text color grows inside from the start edge, `aria-busy` is set and the button stays pressable (to cancel). Put the number in the label («Скачивание 42%»); remove the prop when done and the fill fades out. |
-| `holdToConfirm` | `boolean` | `false` | The action needs a held press: the fill runs for 1.2 s (a gesture clock, kept under reduced motion) and `onConfirm` fires at its end. Releasing, leaving or losing focus earlier rolls it back. Space and Enter hold too; the gesture is described to assistive tech by `labels.holdHint`. |
-| `onConfirm` | `() => void` | — | Fires when a `holdToConfirm` press completes; the action goes here, not in `onClick`. |
+| `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. |
+| `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 → square icon-only button; give it `aria-label`. A changed text label flows into the new one letter by letter while the width glides; a change of digits only («58 с» → «57 с», «42%» → «43%») stays in place. |
+| `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. |
 
 ### Button.Icon
@@ -64,7 +68,7 @@ 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. |
+| `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. |
 
 ## Variants
@@ -89,6 +93,8 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `ghost` + `inherit` | transparent, the host's text color, a `currentColor` wash on hover / press | close or icon action on a colored host (solid Banner, accent strip) | |
 | `soft` + `inherit` | `currentColor` wash fill, the host's text color | a labelled action on a colored host | |
 | `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 | |
 
 `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`.
 
@@ -99,17 +105,24 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 |---|---|---|---|
 | `xs` | 28px high, 12/16 text, padX 8, icon 14 | dense tables and chip rows | |
 | `s` | 32px, 13/20, padX 12, icon 16 | compact toolbars, filters | |
-| `m` | 36px, 14/20, padX 16, icon 16 | default UI | yes |
+| `m` | 36px, 14/20, padX 16, icon 16 | default UI | yes (without `size`: the host's tier, else `m`) |
 | `l` | 40px, 16/24, padX 20, icon 20 | prominent forms | |
 | `xl` | 48px, 16/24, padX 24, icon 20 | hero CTA, mobile footers | |
 
 A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedControl and Tabs of the same `size`. The icon side gets optical padding `padX − 4px` (never below 8px); icon→label gap is the tier gap.
 
+### shape
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | |
+
 ### 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) |
 
 **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.
 
@@ -118,14 +131,19 @@ A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedContr
 |---|---|---|
 | hover / active | pointer | hover fill per variant; active `scale(var(--prime-motion-press-scale))` |
 | focus-visible | keyboard | outer focus ring with `--prime-focus-offset`; `tone="inherit"` draws it in `currentColor` |
-| disabled | `disabled` | native `disabled`, `data-disabled="true"`, `fill-muted` + `text-disabled`, `cursor: not-allowed`; ghost stays transparent |
+| 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"`) |
 | 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 |
-| 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 earlier → `data-hold="cancel"`, the fill rolls back (`fast` · exit) |
+| 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 (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 |
 
-Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-width`, `data-icon-only`, `data-leading-icon`, `data-trailing-icon`.
+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`.
 
 ## Layout & spacing
 - Buttons in a row: `gap: var(--prime-space-2)`–`var(--prime-space-3)`; toolbar icon buttons `var(--prime-space-1)`.
@@ -143,6 +161,8 @@ Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-widt
 ### ARIA
 - 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%»).
+- `shape="circle"` requires `aria-label`; its `progress` ring is `aria-hidden`, the share goes in the label or description («Отменить отправку», described by «Отправка 45%»).
 - `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.
@@ -164,7 +184,10 @@ Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-widt
 | [states.tsx](examples/states.tsx) | Disabled and loading next to the default; the spinner keeps the width — `disabled`, `loading`. |
 | [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`. |
-| [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 — `holdToConfirm`, `onConfirm`. |
+| [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`. |
+| [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"`. |
 | [as-child.tsx](examples/as-child.tsx) | The button look on a real link; a disabled link blocks navigation — `asChild`, `disabled`. |
@@ -174,12 +197,15 @@ Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-widt
 - `<Button.Root><Icon name="action.copy" /></Button.Root>` → wrap in `Button.Icon` so the button becomes square and the icon is sized.
 - Icon-only button without `aria-label` → add `aria-label="Копировать"`.
 - `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>` 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`.
+- A round disk drawn by hand (`border-radius: 50%` on a `<button>`, an own ring around it) → `shape="circle"`, with `progress` for the ring.
+- A disk over media recolored with a dark CSS fill → `variant="shade"`.
 - 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)
-- **See also:** [ButtonGroup](../button-group/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md)
+- **Built from:** [Spinner](../spinner/COMPONENT.md), `internal/ring` (the circle's progress ring), `internal/glyphSwap` (the icon cross-fade), `internal/MorphText` (the label morph)
+- **See also:** [ButtonGroup](../button-group/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md)

package/src/components/button/examples/circle.tsx

@@ -0,0 +1,67 @@
+/** Round icon buttons in every treatment, and a disk whose ring tracks an export it can cancel — `shape`, `variant`, `tone`, `progress`. */
+import { Button, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Share of the export done at each tick. */
+const TICKS = [0, 0.12, 0.25, 0.31, 0.47, 0.58, 0.72, 0.86, 1];
+
+export default function ButtonCircleExample() {
+  const [tick, setTick] = React.useState<number | null>(null);
+
+  React.useEffect(() => {
+    if (tick === null) return;
+    const timer = window.setTimeout(
+      () => setTick(tick + 1 < TICKS.length ? tick + 1 : null),
+      tick === 0 ? 900 : 320,
+    );
+    return () => window.clearTimeout(timer);
+  }, [tick]);
+
+  const exporting = tick !== null;
+  // The first tick has no share yet: the ring turns a quarter arc.
+  const progress = tick === null ? undefined : tick === 0 ? null : TICKS[tick];
+
+  return (
+    <div className={styles.row}>
+      <Button.Root shape="circle" aria-label="Новый заказ">
+        <Button.Icon>
+          <Icon name="action.add" />
+        </Button.Icon>
+      </Button.Root>
+      <Button.Root shape="circle" variant="soft" aria-label="Обновить список">
+        <Button.Icon>
+          <Icon name="action.refresh" />
+        </Button.Icon>
+      </Button.Root>
+      <Button.Root shape="circle" variant="outline" tone="neutral" aria-label="Фильтры">
+        <Button.Icon>
+          <Icon name="action.filter" />
+        </Button.Icon>
+      </Button.Root>
+      <Button.Root shape="circle" variant="ghost" tone="neutral" aria-label="Ещё действия">
+        <Button.Icon>
+          <Icon name="action.more" />
+        </Button.Icon>
+      </Button.Root>
+      <Button.Root shape="circle" variant="soft" tone="danger" aria-label="Удалить заказ">
+        <Button.Icon>
+          <Icon name="action.delete" />
+        </Button.Icon>
+      </Button.Root>
+      <Button.Root
+        shape="circle"
+        size="l"
+        variant={exporting ? "solid" : "soft"}
+        progress={progress}
+        aria-label={exporting ? "Отменить выгрузку заказов" : "Выгрузить заказы"}
+        onClick={() => setTick(exporting ? null : 0)}
+      >
+        <Button.Icon>
+          <Icon name={exporting ? "action.close" : "action.download"} />
+        </Button.Icon>
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -26,6 +26,28 @@
   color: var(--prime-color-text-inverse);
 }
 
+/* A row of round buttons. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+/* A listing cover with its round actions at the top end. */
+.cover {
+  position: relative;
+}
+
+.coverActions {
+  position: absolute;
+  inset-block-start: var(--prime-space-2);
+  inset-inline-end: var(--prime-space-2);
+  z-index: 1;
+  display: flex;
+  gap: var(--prime-space-2);
+}
+
 .hostText {
   flex: 1;
   min-width: 0;

package/src/components/button/examples/hold-to-confirm.tsx

@@ -1,7 +1,10 @@
-/** A destructive action that needs a held press; letting go early rolls the fill back and does nothing — `holdToConfirm`, `onConfirm`. */
+/** 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`. */
 import { Button, Icon } from "prime-ui-kit";
 import * as React from "react";
 
+/** The server deleting the project a beat later. */
+const deleteProject = () => new Promise<void>((resolve) => setTimeout(resolve, 900));
+
 export default function ButtonHoldToConfirmExample() {
   const [deleted, setDeleted] = React.useState(false);
 
@@ -13,7 +16,15 @@ export default function ButtonHoldToConfirmExample() {
       Восстановить проект
     </Button.Root>
   ) : (
-    <Button.Root variant="soft" tone="danger" holdToConfirm onConfirm={() => setDeleted(true)}>
+    <Button.Root
+      variant="soft"
+      tone="danger"
+      holdToConfirm
+      onConfirm={async () => {
+        await deleteProject();
+        setDeleted(true);
+      }}
+    >
       <Button.Icon>
         <Icon name="action.delete" />
       </Button.Icon>

package/src/components/button/examples/over-media.tsx

@@ -0,0 +1,36 @@
+/** Buttons over a listing's cover stand on the media shade; a failed upload turns its disk danger — `variant`, `shape`, `tone`. */
+import { Button, Icon, Thumbnail } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const COVER = "https://picsum.photos/seed/loft-hall/480/320";
+
+export default function ButtonOverMediaExample() {
+  return (
+    <div className={styles.cover}>
+      <Thumbnail.Root ratio="3:2" fullWidth>
+        <Thumbnail.Image src={COVER} />
+        <Thumbnail.Fallback>
+          <Icon name="object.image" />
+        </Thumbnail.Fallback>
+      </Thumbnail.Root>
+      <div className={styles.coverActions}>
+        <Button.Root shape="circle" variant="shade" aria-label="Заменить обложку">
+          <Button.Icon>
+            <Icon name="action.edit" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root
+          shape="circle"
+          variant="shade"
+          tone="danger"
+          aria-label="Повторить загрузку обложки"
+        >
+          <Button.Icon>
+            <Icon name="action.refresh" />
+          </Button.Icon>
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/button/examples/toggle.tsx

@@ -0,0 +1,21 @@
+/** A toggle in a toolbar: the favourite mark turns the button on with the selected fill and back off — `pressed`. */
+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.Icon>
+        <Icon name="status.favorite" />
+      </Button.Icon>
+      В избранном
+    </Button.Root>
+  );
+}

package/src/components/button-group/COMPONENT.md

@@ -24,25 +24,36 @@ import { ButtonGroup } from "prime-ui-kit";
 
 ## Anatomy
 ```
-ButtonGroup.Root         <div role="group">; size and orientation for every segment
-└─ ButtonGroup.Item      one segment, a native <button>; optional pressed toggle
-   └─ ButtonGroup.Icon   decorative icon wrapper (aria-hidden), sized to the tier
+ButtonGroup.Root            field frame: label row · group · support row (hint | error)
+└─ (group)                  <div role="group">; size and orientation for every segment
+   └─ ButtonGroup.Item      one segment, a native <button>; optional pressed toggle
+      └─ ButtonGroup.Icon   decorative icon wrapper (aria-hidden), sized to the tier
 ```
+The root is a field root: `className`, `ref` and the native attributes land on the frame, which hugs the group unless `fullWidth`; `id`, `role` and the `aria-label*` / `aria-describedby` names land on the group element. Without `label`, `hint` and `error` the frame shows only the segments.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### ButtonGroup.Root
-`ref` → `HTMLDivElement`. `<div role="group">`; sets the tier and orientation of every segment and passes the tier to nested icons.
+`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`.
 
 | 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`. |
 | `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. |
+| `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`). |
+| `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid` and `data-invalid` on the `group`; the control shakes once when an error arrives. |
+| `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |
+| `id` | `string` | — | Id of the `group` element (generated when omitted); hint id is `<id>-hint`, error id `<id>-error`. |
+| `labels` | `Partial<ButtonGroupLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `ButtonGroup.Item` segments. |
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `aria-label` (name the group), `role` (e.g. `"toolbar"`), `className` and the other div attributes. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `aria-label` / `aria-labelledby` / `aria-describedby` and `role` (e.g. `"toolbar"`) go to the group element; `className`, `data-*` and the other attributes to the field frame `<div>`. |
 
 ### ButtonGroup.Item
 `ref` → `HTMLButtonElement`. One segment, a native `<button>`.
@@ -51,7 +62,7 @@ ButtonGroup.Root         <div role="group">; size and orientation for every segm
 |---|---|---|---|
 | `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. |
+| `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. |
 
@@ -76,7 +87,7 @@ ButtonGroup.Root         <div role="group">; size and orientation for every segm
 |---|---|---|---|
 | `xs` | 28px high, 12/16 text, padX 8 | dense tables | |
 | `s` | 32px, 13/20, padX 12 | compact toolbars | |
-| `m` | 36px, 14/20, padX 16 | default | yes |
+| `m` | 36px, 14/20, padX 16 | default | yes (without `size`: the host's tier, else `m`) |
 | `l` | 40px, 16/24, padX 20 | prominent forms | |
 | `xl` | 48px, 16/24, padX 24 | hero areas | |
 
@@ -104,10 +115,12 @@ Do not mix action segments and toggle segments in one group, and do not put the
 |---|---|---|
 | 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"` |
-| disabled | `disabled` | native `:disabled`: `fill-muted` + `text-disabled`, `cursor: not-allowed` |
+| 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`) |
+| 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 |
 
-Root 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`.
+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.
@@ -122,14 +135,17 @@ Root attributes: `data-size`, `data-orientation="vertical"` (only when vertical)
 | `Enter` · `Space` | Presses the segment (native `<button>`). |
 
 ### ARIA
-- `Root` is `role="group"` — give it `aria-label`; set `role="toolbar"` on the outer container of several groups.
+- 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.
 - Icon-only segments need `aria-label`; `ButtonGroup.Icon` is `aria-hidden`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
 
 ## Examples
 | Example | Shows |
@@ -141,7 +157,7 @@ No `labels`.
 | [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`. |
-| [in-form.tsx](examples/in-form.tsx) | Segments are native buttons, so submit and reset work in one group — `type`. |
+| [in-form.tsx](examples/in-form.tsx) | A task form: the priority toggles are a labelled field checked on submit, and native submit and reset segments sit in one group — `label`, `required`, `error`, `type`. |
 
 ## Mistakes
 - `size` on each `ButtonGroup.Item` → set `size` once on `Root`.
@@ -149,7 +165,8 @@ No `labels`.
 - Expecting `value` / `onValueChange` → ButtonGroup has none; keep the value in state and set `pressed`, or use SegmentedControl.
 - `pressed` only on the active segment of a toggle set → pass `pressed={false}` to the others so they announce as toggles.
 - Icon-only segment without `aria-label` → add it.
+- A `Label` + `Hint` pair wired by hand around a toggle set in a form → `label`, `hint`, `error` on the root.
 
 ## Related
-- **Built from:** —
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
 - **See also:** [Button](../button/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Tabs](../tabs/COMPONENT.md)

package/src/components/button-group/examples/in-form.tsx

@@ -1,19 +1,54 @@
-/** Segments are native buttons, so submit and reset work in one group — `type`. */
+/** A task form: the priority toggles are a labelled field checked on submit, and native submit and reset segments sit in one group — `label`, `required`, `error`, `type`. */
 import { ButtonGroup, Input } from "prime-ui-kit";
+import * as React from "react";
 
 import styles from "./examples.module.css";
 
+const PRIORITIES = [
+  { value: "low", label: "Низкий" },
+  { value: "normal", label: "Обычный" },
+  { value: "high", label: "Высокий" },
+];
+
 export default function ButtonGroupInFormExample() {
+  const [priority, setPriority] = React.useState("");
+  const [error, setError] = React.useState<string>();
+
   return (
-    <form className={styles.form} onSubmit={(event) => event.preventDefault()}>
-      <Input.Root label="Поиск по заказам">
+    <form
+      className={styles.form}
+      noValidate
+      onSubmit={(event) => {
+        event.preventDefault();
+        setError(priority ? undefined : "Выберите приоритет задачи");
+      }}
+      onReset={() => {
+        setPriority("");
+        setError(undefined);
+      }}
+    >
+      <Input.Root label="Задача" required>
         <Input.Wrapper>
-          <Input.Field name="query" type="search" placeholder="Номер заказа или клиент" />
+          <Input.Field name="title" defaultValue="Подготовить акт сверки для «Северного ветра»" />
         </Input.Wrapper>
       </Input.Root>
-      <ButtonGroup.Root aria-label="Отправить или сбросить поиск">
-        <ButtonGroup.Item type="submit">Найти</ButtonGroup.Item>
-        <ButtonGroup.Item type="reset">Сбросить</ButtonGroup.Item>
+      <ButtonGroup.Root label="Приоритет" required error={error}>
+        {PRIORITIES.map((option) => (
+          <ButtonGroup.Item
+            key={option.value}
+            pressed={priority === option.value}
+            onClick={() => {
+              setPriority(option.value);
+              setError(undefined);
+            }}
+          >
+            {option.label}
+          </ButtonGroup.Item>
+        ))}
+      </ButtonGroup.Root>
+      <ButtonGroup.Root aria-label="Создать задачу или очистить форму">
+        <ButtonGroup.Item type="submit">Создать</ButtonGroup.Item>
+        <ButtonGroup.Item type="reset">Очистить</ButtonGroup.Item>
       </ButtonGroup.Root>
     </form>
   );