prime-ui-kit 0.9.0 → 0.9.2

package/src/components/card/examples/flat.tsx

@@ -1,5 +1,4 @@
-/** Default `shadow-raised` versus `flat` (no shadow). Use `flat` for dense grids of tiles where shadows add noise. */
-
+/** A flat tile without the raised shadow next to the default one, for dense grids — `flat`. */
 import { Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -8,22 +7,18 @@ export default function CardFlatExample() {
   return (
     <div className={styles.grid}>
       <Card.Root variant="mini">
-        <Card.IconBox>
+        <Card.Icon>
           <Icon name="field.email" strokeWidth={2} />
-        </Card.IconBox>
-        <Card.Stack>
-          <Card.Label>С тенью (по умолчанию)</Card.Label>
-          <Card.Value>42</Card.Value>
-        </Card.Stack>
+        </Card.Icon>
+        <Card.Label>С тенью (по умолчанию)</Card.Label>
+        <Card.Value>42</Card.Value>
       </Card.Root>
       <Card.Root variant="mini" flat>
-        <Card.IconBox>
+        <Card.Icon>
           <Icon name="field.email" strokeWidth={2} />
-        </Card.IconBox>
-        <Card.Stack>
-          <Card.Label>flat</Card.Label>
-          <Card.Value>42</Card.Value>
-        </Card.Stack>
+        </Card.Icon>
+        <Card.Label>flat</Card.Label>
+        <Card.Value>42</Card.Value>
       </Card.Root>
     </div>
   );

package/src/components/card/examples/kpi-media.tsx

@@ -0,0 +1,42 @@
+/** A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. */
+import { Card, Icon, ProgressBar } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SPARKLINE = "M0 32 L15 28 L30 30 L45 18 L60 22 L75 12 L90 16 L105 8 L120 4";
+
+export default function CardKpiMediaExample() {
+  return (
+    <div className={styles.grid}>
+      <Card.Root variant="mini">
+        <Card.Icon>
+          <Icon name="object.activity" />
+        </Card.Icon>
+        <Card.Label>Запросы в минуту</Card.Label>
+        <Card.Value>12 840</Card.Value>
+        <Card.Media>
+          {/* The SVG stretches to the card width; CSS sets its height, not the viewBox. */}
+          <svg
+            className={styles.spark}
+            viewBox="0 0 120 40"
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <path d={SPARKLINE} className={styles.chartLine} />
+          </svg>
+        </Card.Media>
+      </Card.Root>
+
+      <Card.Root variant="mini">
+        <Card.Icon>
+          <Icon name="object.storage" />
+        </Card.Icon>
+        <Card.Label>Хранилище</Card.Label>
+        <Card.Value>72 из 100 ГБ</Card.Value>
+        <Card.Media>
+          <ProgressBar value={72} size="s" label="Занято" showValue />
+        </Card.Media>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/card/examples/narrow.tsx

@@ -0,0 +1,47 @@
+/** The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem. */
+import { Card, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WIDTHS = [
+  { id: "narrow", className: styles.w18 },
+  { id: "wide", className: styles.w40 },
+];
+
+export default function CardNarrowExample() {
+  return (
+    <div className={styles.stack}>
+      {WIDTHS.map((width) => (
+        <div key={width.id} className={styles.stack}>
+          <div className={width.className}>
+            <Card.Root variant="split">
+              <Card.Body>
+                <div>
+                  <Card.Icon>
+                    <Icon name="object.cart" />
+                  </Card.Icon>
+                  <Card.Label>Конверсия</Card.Label>
+                  <Card.Value>3,8%</Card.Value>
+                </div>
+                <div>
+                  <Card.Icon>
+                    <Icon name="object.wallet" />
+                  </Card.Icon>
+                  <Card.Label>Средний чек</Card.Label>
+                  <Card.Value>₽ 2 450</Card.Value>
+                </div>
+              </Card.Body>
+            </Card.Root>
+          </div>
+          <div className={width.className}>
+            <Card.Root variant="stat-trend">
+              <Card.Label>Выручка</Card.Label>
+              <Card.Value>₽ 4,2 млн</Card.Value>
+              <Card.Delta tone="success">+18% к прошлому месяцу</Card.Delta>
+            </Card.Root>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/card/examples/{settings.tsx → overview.tsx}

@@ -1,16 +1,15 @@
-/** Settings card: fields inside a card switch to the `field-bg-surface` fill, 20px between fields, actions in the footer on the right. Use for settings and profile forms. */
-
+/** A company settings panel: a header, fields on the surface fill and buttons in the footer — `Card.Header`, `Card.Body`, `Card.Footer`. */
 import { Button, Card, Input, Switch } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-export default function CardSettingsExample() {
+export default function CardOverviewExample() {
   return (
     <div className={styles.panel}>
       <Card.Root variant="panel">
-        <Card.SectionHeader>
-          <Card.SectionTitle>Профиль компании</Card.SectionTitle>
-        </Card.SectionHeader>
+        <Card.Header>
+          <Card.Title>Профиль компании</Card.Title>
+        </Card.Header>
         <Card.Body>
           <div className={styles.form}>
             <Input.Root label="Название" required>
@@ -28,12 +27,12 @@ export default function CardSettingsExample() {
             </Switch.Root>
           </div>
         </Card.Body>
-        <Card.Actions>
+        <Card.Footer>
           <Button.Root variant="ghost" tone="neutral">
             Отмена
           </Button.Root>
           <Button.Root>Сохранить</Button.Root>
-        </Card.Actions>
+        </Card.Footer>
       </Card.Root>
     </div>
   );

package/src/components/card/examples/panel-chart.tsx

@@ -1,50 +1,42 @@
-/** `panel`: a section header with a period switch, text in `Card.Body` and an edge-to-edge chart in `Card.Chart`. Use for chart widgets on dashboards. */
-
+/** A chart widget: a header with a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Media`. */
 import { Card, SegmentedControl, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const points = [42, 48, 45, 60, 58, 72, 66, 80, 76, 88, 84, 96];
+const POINTS = [42, 48, 45, 60, 58, 72, 66, 80, 76, 88, 84, 96];
 
-/** An area chart without libraries: stretches over the whole `Card.Chart`. */
-function AreaChart() {
-  const max = 100;
-  const step = 100 / (points.length - 1);
-  const line = points.map((v, i) => `${i === 0 ? "M" : "L"}${i * step} ${max - v}`).join(" ");
-  return (
-    <svg
-      className={styles.chart}
-      viewBox="0 0 100 100"
-      preserveAspectRatio="none"
-      aria-hidden="true"
-    >
-      <path className={styles.chartFill} d={`${line} L100 100 L0 100 Z`} />
-      <path className={styles.chartLine} d={line} />
-    </svg>
-  );
-}
+/** An area chart path in a 100 × 100 box; the SVG stretches over the whole `Card.Media`. */
+const LINE = POINTS.map(
+  (value, i) => `${i === 0 ? "M" : "L"}${(i * 100) / (POINTS.length - 1)} ${100 - value}`,
+).join(" ");
 
 export default function CardPanelChartExample() {
   return (
     <div className={styles.panel}>
       <Card.Root variant="panel">
-        <Card.SectionHeader>
-          <Card.SectionTitle>Выручка</Card.SectionTitle>
-          <Card.SectionTrailing>
-            <SegmentedControl.Root size="xs" defaultValue="month" aria-label="Период">
-              <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
-              <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
-            </SegmentedControl.Root>
-          </Card.SectionTrailing>
-        </Card.SectionHeader>
+        <Card.Header>
+          <Card.Title>Выручка</Card.Title>
+          <SegmentedControl.Root size="xs" defaultValue="month" aria-label="Период">
+            <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+            <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+          </SegmentedControl.Root>
+        </Card.Header>
         <Card.Body>
-          <Typography.Root variant="body-s" tone="secondary">
+          <Typography variant="body-s" tone="secondary">
             С начала квартала: ₽ 12,6 млн, план выполнен на 84%.
-          </Typography.Root>
+          </Typography>
         </Card.Body>
-        <Card.Chart>
-          <AreaChart />
-        </Card.Chart>
+        <Card.Media>
+          <svg
+            className={styles.chart}
+            viewBox="0 0 100 100"
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <path className={styles.chartFill} d={`${LINE} L100 100 L0 100 Z`} />
+            <path className={styles.chartLine} d={LINE} />
+          </svg>
+        </Card.Media>
       </Card.Root>
     </div>
   );

package/src/components/card/examples/{metrics.tsx → variants.tsx}

@@ -1,30 +1,24 @@
-/** Metric cards: `mini` (icon + title-l value), `metric` (badge + heading-m value), `stat-trend` (large value + delta colored by `tone`). Use for KPI rows on dashboards. */
-
-import { Users } from "lucide-react";
-import { Badge, Card } from "prime-ui-kit";
+/** KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change — `variant`, `Card.Delta`. */
+import { Badge, Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-export default function CardMetricsExample() {
+export default function CardVariantsExample() {
   return (
     <div className={styles.grid}>
       <Card.Root variant="mini">
-        <Card.IconBox>
-          <Users aria-hidden />
-        </Card.IconBox>
-        <Card.Stack>
-          <Card.Label>Активные сессии</Card.Label>
-          <Card.Value>1 248</Card.Value>
-        </Card.Stack>
+        <Card.Icon>
+          <Icon name="object.users" />
+        </Card.Icon>
+        <Card.Label>Активные сессии</Card.Label>
+        <Card.Value>1 248</Card.Value>
       </Card.Root>
 
-      <Card.Root variant="metric">
-        <Card.HeaderRow>
-          <Card.Lead>
-            <Badge.Root color="green">SLA</Badge.Root>
-          </Card.Lead>
+      <Card.Root variant="stat-trend">
+        <Card.Header>
+          <Badge.Root color="green">SLA</Badge.Root>
           <Card.Value>99,95%</Card.Value>
-        </Card.HeaderRow>
+        </Card.Header>
         <Card.Description>Доступность API за 30 дней</Card.Description>
       </Card.Root>
 

package/src/components/checkbox/COMPONENT.md

@@ -1,8 +1,9 @@
 # Checkbox
 
 **Category:** selection
+**Kind:** control
 
-> A checkbox for an independent yes/no choice that submits with a form: checked, indeterminate, groups.
+> A checkbox for an independent yes/no choice that submits with a form: checked, indeterminate, with a hint or an error.
 
 ## When to use
 - Independent on/off options that are saved together with a form (consents, sets of options).
@@ -13,6 +14,7 @@
 - One choice out of several mutually exclusive options → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md) instead.
 - A setting that applies immediately, without a submit → use [Switch](../switch/COMPONENT.md) instead.
 - Picking several values from a long list in a compact field → use [TagSelect](../tag-select/COMPONENT.md) or [Select](../select/COMPONENT.md) with `multiple` instead.
+- A checkbox look inside an option or menu row that carries `aria-selected` itself → `Checkbox.Indicator`, never a nested `Checkbox.Root`.
 
 ## Import
 ```tsx
@@ -21,61 +23,56 @@ import { Checkbox } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Checkbox.Root          wrapper grid + context; ref and input props go to the hidden native input
-├─ Checkbox.Label      clickable row: renders the native input, the box and the text
-├─ Checkbox.Hint       description under the text column (optional)
-└─ Checkbox.Error      error message under the text column (optional, makes the field invalid)
+Checkbox.Root          field grid; ref and input props go to the native input
+├─ <label> row         the native input, the box and the text (rendered by Root)
+│  └─ Checkbox.Label   the visible text (optional)
+└─ hint | error        support text under the text column (`hint`, `error`)
+
+Checkbox.Indicator     the box alone, no input — a mark inside option / menu rows (used without Root)
 ```
-The native `input type="checkbox"` is rendered inside `Checkbox.Label`, so `Checkbox.Label` is required even without visible text.
+`<Checkbox.Root aria-label="…" />` without `Checkbox.Label` is a valid bare control (table rows).
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Checkbox.Root
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `checked` | `boolean` | — | Controlled checked state; use with `onCheckedChange`. |
-| `defaultChecked` | `boolean` | `false` | Initial state in uncontrolled mode. |
-| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on click or Space. |
-| `indeterminate` | `boolean` | `false` | Mixed state (partial «select all»); wins over `checked` visually and is synced to `input.indeterminate`. |
-| `invalid` | `boolean` | `false` | Invalid look and `aria-invalid`; also set automatically while `Checkbox.Error` is mounted. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size tier of the box, gap and label text. |
-| `fullWidth` | `boolean` | `false` | Stretch to the container width; by default the field is as wide as its content. |
-| `disabled` | `boolean` | `false` | Disables the input; dims box, label and hint. |
-| `id` | `string` | auto (`useId`) | Id of the native input; hint/error ids derive from it. |
-| `aria-describedby` | `string` | — | Extra description ids; merged with the mounted hint and error ids. |
-| `className` | `string` | — | Class on the wrapper `div`. |
-| `children` | `ReactNode` | — | `Checkbox.Label`, `Checkbox.Hint`, `Checkbox.Error`. |
-
-+ native `<input>` props except `type`, `size`, `checked`, `defaultChecked`, `onChange`, `children` (`name`, `value`, `required`, `aria-label`, `onBlur`, `style`, …) — they are applied to the hidden native input, not to the wrapper.
-Ref: `forwardRef` → `HTMLInputElement`. No `asChild`.
+`ref` → `HTMLInputElement` (the native checkbox). Renders the field `<div>`, the `<label>` row with the input and the box, and the support row. Field-root rule for a leaf: `className` goes to the field `<div>`; `id`, `ref` and native input props to the input.
 
-### Checkbox.Label
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — | Label text. Empty → only the box is rendered; then set `aria-label` on `Checkbox.Root`. |
-| `className` | `string` | — | Class on the `<label>` row. |
-
-+ native `<label>` HTML attributes except `htmlFor` and `size` (wired from context).
-Ref: `forwardRef` → `HTMLLabelElement`.
+| `checked` | `boolean` | — | Controlled checked state. |
+| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on every toggle (not while `readOnly`). |
+| `indeterminate` | `boolean` | `false` | Mixed state (a partial «select all»): a bar instead of the check; wins over `checked` visually and sets the native `indeterminate`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the box, the text and the gap. Without it the tier of its host (a form, a panel, a table), else `m`. |
+| `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger ring on the unchecked box and `aria-invalid`. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disabled fill, dimmed label and hint, no toggling. |
+| `readOnly` | `boolean` | `false` | The state is shown and focusable but does not change (`aria-readonly`); no hover or press. The native checkbox ignores `readOnly`, so the root guards the toggle. |
+| `id` | `string` | — | Id of the input (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `children` | `ReactNode` | — | `Checkbox.Label`. Without it only the box renders — give the root an `aria-label`. |
+| `className` | `string` | — | Class on the field `<div>`. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required`, `aria-label`, `onBlur`… on the native input. |
 
-### Checkbox.Hint
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | — (required) | Description text, aligned with the text column; added to `aria-describedby`. |
-| `className` | `string` | — | Class on the `<p>`. |
+### Checkbox.Label
+`ref` → `HTMLSpanElement`. The visible text in the text column of the label row. Native `<span>` props.
 
-+ native `<p>` props except `id` (fixed to `<inputId>-hint`). No ref.
+### Checkbox.Indicator
+`ref` → `HTMLSpanElement`. The box alone, without an input (`aria-hidden`, no focus or clicks) for rows that carry the state themselves: `role="option"` + `aria-selected`, `role="menuitemcheckbox"` + `aria-checked`.
 
-### Checkbox.Error
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Error text in `danger-text`; while mounted the field is invalid. |
-| `className` | `string` | — | Class on the `<p>`. |
-
-+ native `<p>` props except `id` (fixed to `<inputId>-error`). No ref.
+| `checked` | `boolean` | `false` | Shows the check. |
+| `indeterminate` | `boolean` | `false` | Shows the bar; wins over `checked`. |
+| `disabled` | `boolean` | `false` | Disabled fill. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Box tier; without it the nearest control size (the Select or menu it sits in), else `m`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className`, `data-*` and the other span attributes. |
 
 ## Variants
-Checkbox has no `variant`/`tone`/`color`. Axes: `size`, `fullWidth`.
+Checkbox has no `variant` / `tone` / `color`.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -86,79 +83,78 @@ Checkbox has no `variant`/`tone`/`color`. Axes: `size`, `fullWidth`.
 | `l` | 20px box, 8px gap, 16/24 text | spacious forms, onboarding | |
 | `xl` | 24px box (radius 6), 12px gap, 16/24 text | touch-first screens | |
 
-### fullWidth
+**Sizes:** the box is optically centred on the first text line; the text follows the tier text size (12 · 13 · 14 · 16 · 16). Match the checkbox `size` to the fields and buttons of the same form.
+
+### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `false` | field shrinks to its content, text wraps inside the container | choices placed side by side or in a list | yes |
-| `true` | field stretches to 100% of the container | the label row must fill a grid cell or a card row | |
+| `indeterminate` | accent box with a horizontal bar | a parent checkbox over a partially selected group | `false` |
+| `invalid` | danger ring on the unchecked box | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `disabled` | muted box, dimmed text and hint | the option is unavailable | `false` |
 
 **Combinations**
-- Match the checkbox `size` to the fields and buttons of the same form (`m` with `m`).
 - `indeterminate` only on a parent checkbox that controls a group; leaf options never use it.
-- `invalid` together with a `Checkbox.Error` text is redundant — the error already sets it. Use bare `invalid` only when the message is shown elsewhere.
-
-**Sizes** — the box is optically centred on the first text line; label text follows the tier text size (12 · 13 · 14 · 16 · 16).
-
-**Hierarchy** — a parent checkbox sits above its children; nested options are indented by the box width plus the gap so they align with the parent text (see [settings-card.tsx](examples/settings-card.tsx)).
+- `invalid` together with `error` is redundant — the error already sets it.
+- Nested options are indented by the box width plus the gap so they align with the parent text.
 
 ## States
-| State | Driven by | DOM | Looks like |
-|---|---|---|---|
-| unchecked | `checked={false}` / default | `data-state="unchecked"` | box `fill-strong`, hover `fill-strong-hover` |
-| checked | `checked` / `defaultChecked` | `data-state="checked"` | box `accent-default` (hover `accent-hover`), check mark in `accent-fg` drawn in with a stroke reveal |
-| indeterminate | `indeterminate` | `data-state="indeterminate"`, `input.indeterminate` | accent box with a horizontal bar |
-| invalid | `invalid` or mounted `Checkbox.Error` | `data-invalid="true"`, `aria-invalid` on input | unchecked box gets a `danger-border` inset ring; focus ring turns `danger-border` |
-| disabled | `disabled` | `data-disabled="true"` on root and label | box `fill-muted`, mark `text-disabled`, `cursor: not-allowed`, hint dimmed |
-| active | pointer press | — | box scales to 92% |
-| focus-visible | keyboard focus | — | outer focus ring around the box |
+| State | Driven by | DOM |
+|---|---|---|
+| unchecked | `checked={false}` / default | `data-state="unchecked"`; box `fill-strong`, hover `fill-strong-hover` |
+| checked | `checked` / `defaultChecked` | `data-state="checked"`; accent box, the check draws in |
+| indeterminate | `indeterminate` | `data-state="indeterminate"`, `input.indeterminate`; accent box with a bar |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid` on the input; danger ring on the unchecked box and on focus |
+| disabled | `disabled` | `data-disabled="true"` on the root; `fill-muted` box, disabled text, `cursor: not-allowed` |
+| read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the root; the state stays, no hover or press, default cursor |
+| pressed | pointer press | the box scales to the compact press scale |
+| focus-visible | keyboard focus | outer focus ring around the box |
 
-Root also carries `data-size` and `data-full-width="true"` when `fullWidth`.
-Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked` (+ optional `onCheckedChange`). There is no native `onChange` prop.
+Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked` (+ optional `onCheckedChange`). There is no native `onChange` prop.
 
 ## Layout & spacing
-- Grid `[box][text]`; `Checkbox.Hint` / `Checkbox.Error` sit under the text column, not under the box.
-- Checkboxes in a vertical list: gap `--prime-space-3` (12px); separate fields/groups: `--prime-space-5` (20px); group → group `--prime-space-8`.
-- Group several checkboxes in a `role="group"` container named by a `Typography.Root` heading via `aria-labelledby` (gap on the container, no margins); nested options indent by `calc(var(--prime-control-m-choice) + var(--prime-control-m-gap))`.
-- Long labels wrap (`overflow-wrap: anywhere`); the field is `max-width: 100%` and works from 320px.
+- Grid `[box][text]`; the hint or error sits under the text column, not under the box.
+- Checkboxes in a vertical list: gap `--prime-space-3`; separate fields: `--prime-space-5`; group → actions `--prime-space-8`.
+- Long labels wrap (`overflow-wrap: anywhere`); the field shrinks to its content with `max-width: 100%`.
 
 ## Accessibility
-- Native `<input type="checkbox">` (visually hidden, still in the box for validation bubbles), associated with the `<label>` via `htmlFor`.
-- Keyboard: Tab focuses, Space toggles.
-- `aria-invalid` is set when invalid; `aria-describedby` = your ids + hint id + error id (only mounted parts).
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the checkbox. |
+| `Space` | Toggles it. |
+
+### ARIA
+- A native `<input type="checkbox">` (visually hidden over the box, so validation bubbles point at it), wrapped by the `<label>` row.
+- `aria-invalid` is set when invalid; `aria-describedby` = your ids + the hint or the error id.
 - Without visible text, pass `aria-label` on `Checkbox.Root` (it lands on the input).
-- `required` goes to the native input; no visual asterisk is drawn — state it in the label text or a hint.
-- No `labels` keys.
+- `required` goes to the native input; no asterisk is drawn — state it in the text or the hint.
+- `Checkbox.Indicator` is `aria-hidden`; the host row carries `aria-selected` / `aria-checked`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | All size tiers | Choosing the tier next to other controls |
-| [states.tsx](examples/states.tsx) | Unchecked, checked, indeterminate, invalid, disabled | Reference for every state |
-| [hint-error.tsx](examples/hint-error.tsx) | `Checkbox.Hint` and `Checkbox.Error` | Consents and options that need an explanation or validation |
-| [select-all.tsx](examples/select-all.tsx) | Controlled «select all» with `indeterminate` | Bulk selection in lists |
-| [settings-card.tsx](examples/settings-card.tsx) | Named group with parent and nested options, disabled option with hint, inside a Card with `Card.Actions` (primary last) | Grouped preferences in a settings form |
-| [without-label.tsx](examples/without-label.tsx) | Empty `Checkbox.Label` + `aria-label`, `name`/`value` | Row selection in tables |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { Checkbox } from "prime-ui-kit";
+No `labels`.
 
-export function TermsCheckbox() {
-  return (
-    <Checkbox.Root name="terms" required>
-      <Checkbox.Label>Принимаю условия оферты</Checkbox.Label>
-      <Checkbox.Hint>Без этого мы не сможем оформить заказ.</Checkbox.Hint>
-    </Checkbox.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A checkbox with its label; a click anywhere on the row toggles it. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the box and the text follow the control tier — `size`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `invalid`, `disabled`. |
+| [without-label.tsx](examples/without-label.tsx) | Bare boxes in table rows, named by `aria-label` and submitted with `name` and `value`. |
+| [indicator.tsx](examples/indicator.tsx) | The box alone in a multi-select list: the option row carries `aria-selected`, the box only shows it — `Checkbox.Indicator`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. |
+| [in-form.tsx](examples/in-form.tsx) | Consent in a sign-up form: a hint under the text, an error after a submit without the tick — `required`, `hint`, `error`. |
 
 ## Mistakes
 - `<Checkbox.Root onChange={…}>` → use `onCheckedChange={(checked) => …}`.
-- `<Checkbox.Root>Текст</Checkbox.Root>` → wrap the text in `Checkbox.Label`; without it no input is rendered.
-- `invalid` plus `Checkbox.Error` → just mount `Checkbox.Error`.
-- Several checkboxes for one-of-many → use `Radio.Root` with items.
-- Checkbox that saves instantly («Тёмная тема») → use `Switch`.
-- `style` on `Checkbox.Root` expecting to style the wrapper → it goes to the hidden input; use `className`.
+- `<Checkbox.Root>Текст</Checkbox.Root>` → wrap the text in `Checkbox.Label`, so it sits in the text column.
+- `invalid` plus `error` → just pass `error`.
+- Several checkboxes for one-of-many → use `Radio.Group`.
+- A checkbox that saves instantly («Тёмная тема») → use `Switch`.
+- `style` on `Checkbox.Root` expecting to style the field → it goes to the hidden input; use `className`.
 
 ## Related
-[Radio](../radio/COMPONENT.md) · [Switch](../switch/COMPONENT.md) · [SegmentedControl](../segmented-control/COMPONENT.md) · [Label](../label/COMPONENT.md) · [Hint](../hint/COMPONENT.md)
+- **Built from:** [Label](../label/COMPONENT.md) (the row), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/checkbox/examples/controlled.tsx

@@ -0,0 +1,41 @@
+/** The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. */
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const DOCUMENTS = ["Договор поставки.pdf", "Счёт-фактура №418.pdf", "Акт сверки.xlsx"];
+
+export default function CheckboxControlledExample() {
+  const [selected, setSelected] = React.useState<string[]>([DOCUMENTS[0]]);
+  const all = selected.length === DOCUMENTS.length;
+
+  return (
+    <div className={styles.list}>
+      <Checkbox.Root
+        checked={all}
+        indeterminate={selected.length > 0 && !all}
+        onCheckedChange={(checked) => setSelected(checked ? DOCUMENTS : [])}
+      >
+        <Checkbox.Label>
+          Выбрать все ({selected.length} из {DOCUMENTS.length})
+        </Checkbox.Label>
+      </Checkbox.Root>
+      <div className={styles.nested}>
+        {DOCUMENTS.map((document) => (
+          <Checkbox.Root
+            key={document}
+            checked={selected.includes(document)}
+            onCheckedChange={(checked) =>
+              setSelected((current) =>
+                checked ? [...current, document] : current.filter((item) => item !== document),
+              )
+            }
+          >
+            <Checkbox.Label>{document}</Checkbox.Label>
+          </Checkbox.Root>
+        ))}
+      </div>
+    </div>
+  );
+}