prime-ui-kit 0.7.13 → 0.9.1

package/src/components/radio/COMPONENT.md

@@ -1,137 +1,165 @@
 # Radio
 
-**Default `size`:** use **`m`** for the size axis unless the screen or field explicitly needs another tier.
+**Category:** selection
+**Kind:** control
 
-## Canonical
+> Radio buttons for choosing exactly one option out of a small visible set.
 
-- **`Radio`** — compound choice control: **`Radio.Root`** (field wrapper `.field`, `data-size`, `data-variant`, `data-disabled`, `data-invalid`), **`Radio.Label`** (native `input type="radio"` + marker + optional text), optional **`Radio.Hint`** and **`Radio.Error`** (wired into `aria-describedby` and invalid styling).
-- **`variant`:** **`default`** or **`error`** on **`Radio.Root`**; mounting **`Radio.Error`** also drives invalid / `aria-invalid` for that instance.
-- **`size`:** **`s` | `m` | `l` | `xl`** on **`Radio.Root`** — marker, label, and hint/error scale via context (`ControlSizeProvider`).
-- **Groups:** several **`Radio.Root`** nodes share the same **`name`** (and optionally **`value` / `checked` / `onChange`**) — there is **no** separate **`RadioGroup`**; behavior is native HTML or your controlled state.
-- **`Radio.Root` `ref`** is forwarded to the **native `<input type="radio">`**.
-- **DOM `type`** is always **`radio`**; the design-system **`size`** prop is **not** the HTML `size` attribute (that key is omitted from input props).
+## When to use
+- One choice out of 2–7 visible options where the user benefits from seeing all of them at once: plan, payment method, delivery slot.
+- Options that need a description under the text (`hint` on `Radio.Root`) or a reason why one is unavailable.
+- A required one-of-many question in a form.
 
-## Extended
-
-### About
-
-A compound radio field: wrapper, label row with a native radio and decorative rings, plus optional hint and error text aligned under the label column.
-
-- **When to use** — exactly one choice from mutually exclusive options that submit with the form (`name`, `value`, `required`); native group semantics with the same **`name`** on each **`Radio.Root`**; short helper or validation copy per option via **`Radio.Hint`** / **`Radio.Error`**.
-- **When not to use** — multiple independent toggles or “select many” (prefer [Checkbox](../checkbox/COMPONENT.md)).
-- **When not to use** — a single binary on/off where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)).
-- **When not to use** — a compact segmented bar of modes in one control (prefer [Segmented control](../segmented-control/COMPONENT.md)).
-- **When not to use** — fully custom markup or `asChild`; the marker and label row are fixed by the implementation.
-
-### Playground snippets
-
-Demos match **`playground/sections/RadioSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/radio/`**:
-
-| Block | File | What it shows |
-|-------|------|----------------|
-| **Sizes** | [`sizes.tsx`](../../../playground/snippets/radio/sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** at **`variant="default"`**; separate **`name`** per row so previews do not clash. |
-| **Variants** | [`variants.tsx`](../../../playground/snippets/radio/variants.tsx) | **`variant="default"`** with **`Radio.Hint`** vs **`variant="error"`** with **`Radio.Error`** and **`aria-invalid`**. |
-| **States** | [`states.tsx`](../../../playground/snippets/radio/states.tsx) | Unchecked, selected, **`disabled`** (off/on), row with **`Radio.Hint`** and **`aria-describedby`**. |
-| **Controlled** | [`controlled.tsx`](../../../playground/snippets/radio/controlled.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | Same **`name`**, **`checked`** + **`onChange`** with **`e.currentTarget.checked`**; summary line. |
-| **Composition** | [`composition.tsx`](../../../playground/snippets/radio/composition.tsx) | Two options, shared **`name`**, **`Radio.Hint`** under each (payment-style block). |
-| **Full width** | [`full-width.tsx`](../../../playground/snippets/radio/full-width.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | Narrow column (`previewBannerNarrowColumn` in playground): root stretches **`width: 100%`**, label uses remaining space. |
-| **Specific** | [`form-group.tsx`](../../../playground/snippets/radio/form-group.tsx) (+ [`radio-snippets.module.css`](../../../playground/snippets/radio/radio-snippets.module.css)) | **`fieldset`** / **`legend`**, **`required`**, **`FormData`** on submit. |
-
-### Scenarios (recipes)
-
-| Scenario | Approach |
-|----------|----------|
-| Shipping method | **`fieldset`** + **`legend`**; shared **`name`**; **`Radio.Hint`** for delivery copy per option. → [`examples/shipping-method.tsx`](examples/shipping-method.tsx) |
-| Plan picker | Controlled group: **`checked`** + **`onChange`**, same **`name`**, optional summary line. → [`examples/plan-picker.tsx`](examples/plan-picker.tsx) |
-| Settings group | Themed or preference block; **`disabled`** on tier-gated options. → [`examples/settings-group.tsx`](examples/settings-group.tsx) |
-| Single primary channel | One-notice policy (email vs SMS vs app); still radios, not checkboxes. → [`examples/notification-channel.tsx`](examples/notification-channel.tsx) |
-
-Runnable recipe examples use **`prime-ui-kit`** imports under **`examples/`**. Snippet-level demos (internal `@/` imports) are listed in **Playground snippets** above.
-
-### Composition
-
-- **`Radio.Root`** — provides context (`inputId`, hint/error ids, `describedBy`, hint/error registration) and wraps children in a **`div`** with class **`field`**.
-- **`Radio.Label`** — [Label](../label/COMPONENT.md) with **`htmlFor`** tied to the input; contains the **`input`**, SVG marker, and optional **`children`** text.
-- **`Radio.Hint`** — optional; registers so its id is merged into **`aria-describedby`**; uses the disabled hint variant when the root is **`disabled`**.
-- **`Radio.Error`** — optional; error-styled **`Hint.Root`** and registers invalid state (same effect as **`variant="error"`** on the root for styling).
-- **Order:** **`Radio.Root`** → **`Radio.Label`** → **`Radio.Hint`** and/or **`Radio.Error`** when needed. Public API: **`Radio.Root`**, **`Radio.Label`**, **`Radio.Hint`**, **`Radio.Error`**.
-
-### Minimal example
+## When not to use
+- 2–4 short view modes or filters that apply instantly → use [SegmentedControl](../segmented-control/COMPONENT.md) instead.
+- A long list (8+ options) or limited space → use [Select](../select/COMPONENT.md) instead.
+- Independent yes/no options → use [Checkbox](../checkbox/COMPONENT.md) instead.
+- A single on/off setting → use [Switch](../switch/COMPONENT.md) instead.
 
+## Import
 ```tsx
 import { Radio } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Radio.Root name="option" value="a">
-      <Radio.Label>Option</Radio.Label>
-    </Radio.Root>
-  );
-}
 ```
 
-### Rules
-
-- Support **controlled** (`checked` + `onChange`) and **uncontrolled** (`defaultChecked`); use standard input change semantics from the native radio.
-- Build a **group** with multiple **`Radio.Root`** instances sharing the same **`name`**; wrap in **`fieldset`** / **`legend`** when the group needs a visible or programmatic heading.
-- **`variant="error"`** or a mounted **`Radio.Error`** sets **`aria-invalid`** on the input and error styling on that root; **`disabled`** disables the input and dims the label/hint treatment.
-- **`aria-describedby`** on **`Radio.Root`** is merged with hint and error ids when those slots mount.
-- Set **`aria-label`** or ensure visible label text when **`Radio.Label`** has no readable children (icon-only or empty label).
+## Anatomy
+```
+Radio.Group             field: group label → role="radiogroup" → hint | error; value, name, size, flags
+└─ Radio.Root           one option (value): the <label> row with the input and the circle, its hint
+   └─ Radio.Label       the visible text of the option
+```
+`Radio.Root` must be inside `Radio.Group`.
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Radio.Group
+`ref` → `HTMLDivElement` (the field frame). Owns the value, the shared `name` and size; renders the group label above and the hint / error below the options. Field-root rule: `className`, `ref` and the rest go to the frame; `id`, `aria-label`, `aria-labelledby` and `aria-describedby` to the `role="radiogroup"` element.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Controlled value (the `value` of the chosen `Radio.Root`). |
+| `defaultValue` | `string` | — | Initial value when uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Called with the value of the newly chosen option. |
+| `name` | `string` | — | Native `name` shared by the radios; generated when omitted. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of every circle, text, the label and the hint. Without it the group takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
+| `label` | `ReactNode` | — | Group heading above the options; names the radiogroup through `aria-labelledby`. Without it, pass `aria-label`. |
+| `required` | `boolean` | `false` | Red `*` after the label, native `required` on the radios and `aria-required` on the group. |
+| `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the options. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message under the options; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger ring on the unchecked circles and `aria-invalid` on the group and the inputs. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disables every option. |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | `vertical` stacks the options; `horizontal` lays them out in a wrapping row. Sets `aria-orientation`. |
+| `labels` | `Partial<RadioGroupLabels>` | — | Built-in strings, see Labels. |
+| `id` | `string` | — | Id of the `role="radiogroup"` element (generated when omitted); also the default `name`. |
+| `aria-label / aria-labelledby / aria-describedby` | `string` | — | Name and description of the radiogroup (`aria-describedby` is merged before the hint / error ids). |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `className`, `data-*` and the other attributes of the field frame `<div>`. |
+
 ### Radio.Root
+`ref` → `HTMLInputElement` (the native radio). One option inside `Radio.Group`: the `<label>` row with the input and the circle, and its hint; native input props go to the input.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| variant | `"default" \| "error"` | `"default"` | no | Error styling and `data-invalid` when `error` or when `Radio.Error` is mounted. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Marker, typography, and hint/error scale from one control token tier. |
-| id | `string` | auto (`useId`) | no | Input id; paired with `Radio.Label` via `htmlFor`. |
-| className | `string` | — | no | Class on the field wrapper (`.field` around Label, Hint, Error slots). |
-| disabled | `boolean` | — | no | Disables the input and label row; stays in sync with label visuals. |
-| aria-describedby | `string` | — | no | Combined with hint and error ids when `Radio.Hint` / `Radio.Error` mount. |
-| children | `React.ReactNode` | — | no | Typically `Label`, optional `Hint` / `Error`. |
-| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native radio input. |
-| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | no | Other native attributes on the `input` (e.g. `name`, `value`, `checked`, `defaultChecked`, `onChange`, `required`, `readOnly`, `form`). `type` is always `radio`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Value reported to the group when this option is chosen. |
+| `hint` | `ReactNode` | — | Description under the option text, linked through `aria-describedby`. |
+| `disabled` | `boolean` | `false` | Disables this option only. |
+| `children` | `ReactNode` | — | `Radio.Label`. Without it only the circle renders — give the root an `aria-label`. |
+| `className` | `string` | — | Class on the option `<div>`. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange" \| "name" \| "value">` | — | `id`, `aria-label`, `aria-describedby`, `onBlur`… on the native input. |
 
 ### Radio.Label
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Label text beside the marker; omit only if an accessible name is set on the root input via remaining root props (e.g. `aria-label`). |
-| className | `string` | — | no | Class on the label row (`Label.Root`). |
-| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; `htmlFor` and `size` come from context. |
-
-### Radio.Hint
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Supplementary text below the label. |
-| className | `string` | — | no | Additional class on the hint slot (offset under the marker column). |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
-
-### Radio.Error
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Error message text; registers invalid context (`aria-invalid` on input). |
-| className | `string` | — | no | Additional class on the error slot. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
+`ref` → `HTMLSpanElement`. The visible text in the text column of the option row. Native `<span>` props.
+
+## Variants
+No `variant` / `tone` / `color`.
+
+### size (Radio.Group)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 14px circle, 4px gap, 12/16 text | dense filters and tables | |
+| `s` | 16px circle, 8px gap, 13/20 text | compact forms and side panels | |
+| `m` | 18px circle, 8px gap, 14/20 text | regular forms | yes |
+| `l` | 20px circle, 8px gap, 16/24 text | spacious forms, onboarding | |
+| `xl` | 24px circle, 12px gap, 16/24 text | touch-first screens | |
+
+**Sizes:** match the form — `m` radios next to `m` inputs and buttons. The circle is centred on the first text line; the group label and hint take the same tier.
+
+### orientation (Radio.Group)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `vertical` | options stacked, gap `--prime-space-2` | options with descriptions, more than 3 options | yes |
+| `horizontal` | options in a wrapping row, column gap `--prime-space-5`, row gap `--prime-space-2` | 2–4 short labels without hints | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `required` | red `*` after the group label | the question must be answered | `false` |
+| `optional` | muted «необязательно» after the group label | most questions are required | `false` |
+| `invalid` | danger ring on the unselected circles | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `disabled` | muted circles and text | the whole question or one option is unavailable | `false` |
+
+**Combinations**
+- `orientation="horizontal"` with option hints → avoid: descriptions break the row; use vertical.
+- One error per question: `error` on `Radio.Group`, never per option.
+- `required` and `optional` together are pointless.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| unselected | group `value` ≠ option `value` | `data-state="unchecked"` on the option; circle `fill-strong`, hover `fill-strong-hover` |
+| selected | group `value` = option `value` | `data-state="checked"`; accent circle with a thumb-coloured dot that grows in |
+| invalid | `invalid` or a non-empty `error` on the group | `data-invalid="true"`, `aria-invalid` on the group and the inputs; danger ring on unselected circles |
+| disabled | group or option `disabled` | `data-disabled="true"`, native `disabled` on every radio; `fill-muted` circle, `cursor: not-allowed` |
+| pressed | pointer press | the circle scales to the compact press scale |
+| focus-visible | keyboard | outer focus ring around the circle |
+
+The radiogroup carries `data-size`, `data-orientation`, `aria-orientation`, `aria-required`; options carry `data-size`, `data-state`, `data-invalid`, `data-disabled`. Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue`.
+
+## Layout & spacing
+- Group label → options: the tier `label-gap`; options → hint / error: the tier `hint-gap` (the same rhythm as fields).
+- Options inside a group: gap `--prime-space-2`; group → group: `--prime-space-8`.
+- An option hint aligns with the text column, not with the circle.
+- Long labels wrap; horizontal rows wrap at narrow widths.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the selected option (or the first one when nothing is selected). |
+| `ArrowDown` · `ArrowRight` · `ArrowUp` · `ArrowLeft` | Selects the next or previous option of the group (native radio behaviour). |
+| `Space` | Selects the focused option. |
+
+### ARIA
+- `Radio.Group` is `role="radiogroup"`, named by its `label` through `aria-labelledby`, or by `aria-label`.
+- `aria-required`, `aria-invalid` and `aria-orientation` sit on the group; the group hint or error is in its `aria-describedby`.
+- Every option is a native `<input type="radio">` with the shared `name`; an option `hint` is linked through `aria-describedby`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the group label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled group of options with one chosen by default — `label`, `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the circle and the text follow the group tier — `size`. |
+| [states.tsx](examples/states.tsx) | Every state, each in its own group and labelled by its prop — `value`, `invalid`, `disabled`. |
+| [group.tsx](examples/group.tsx) | A required group with option descriptions and the group's error under the options — `label`, `required`, `hint`, `error`. |
+| [orientation.tsx](examples/orientation.tsx) | Options stacked in a column and laid out in a wrapping row — `orientation`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the chosen plan and shows it in the hint — `value`, `onValueChange`. |
+
+## Mistakes
+- `Radio.Root` outside `Radio.Group` → it throws; every option needs the group.
+- A heading made of `Typography` + `aria-labelledby` → pass `label` to `Radio.Group`.
+- An error under one option → pass `error` to `Radio.Group`.
+- Radios for an instant view switch → use `SegmentedControl`.
+- Eight or more options → use `Select`.
 
 ## Related
-
-- [Checkbox](../checkbox/COMPONENT.md) — independent or multi-select toggles.
-- [Switch](../switch/COMPONENT.md) — binary setting with a different control pattern.
-- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives used inside Radio; pair with [Input](../input/COMPONENT.md) in larger forms.
-- [Segmented control](../segmented-control/COMPONENT.md) — compact mode switching in one bar.
-
-## LLM note
-
-- Export: **`import { Radio } from "prime-ui-kit"`** — use **`Radio.Root`**, **`Radio.Label`**, **`Radio.Hint`**, **`Radio.Error`** only; there is **no** `RadioGroup`.
-- **`RadioRootProps`**: extends **`Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size">`** plus **`variant?`**, **`size?`**, **`className?`**, **`children?`**; **`ref`** → **`<input type="radio">`**.
-- **`variant`** literals: **`default`**, **`error`** — error semantics also activate when **`Radio.Error`** mounts inside that **`Radio.Root`**.
-- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
-- Grouping: repeat **`Radio.Root`** with the same **`name`**; for controlled mode, set **`checked`/`onChange`** (or **`defaultChecked`**) consistently across the group.
-- Do not invent a **`Radio.Group`** wrapper — it is not part of the API.
-- Per-root context: **`Radio.Error`** / **`variant="error"`** affect **that** instance’s input **`aria-invalid`** and wrapper **`data-invalid`**; for a whole-group message, either mirror **`variant="error"`** on each root in the group or add separate page-level copy as required by your form pattern.
-- **Playground demos** live under **`playground/snippets/radio/`** and are wired from **`playground/sections/RadioSection.tsx`**. **Recipes** under **`src/components/radio/examples/`** import **`prime-ui-kit`** for copy-paste after **`npm install prime-ui-kit`**.
+- **Built from:** [Label](../label/COMPONENT.md) (group label, option rows), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md)

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

@@ -0,0 +1,30 @@
+/** The parent owns the chosen plan and shows it in the hint — `value`, `onValueChange`. */
+import { Radio } from "prime-ui-kit";
+import * as React from "react";
+
+const PLANS = [
+  { value: "start", label: "Старт", hint: "До 5 участников, базовые отчёты" },
+  { value: "team", label: "Команда", hint: "Общие проекты, SSO и журнал действий" },
+  { value: "business", label: "Бизнес", hint: "Выделенная поддержка и хранение данных в РФ" },
+];
+
+export default function RadioControlledExample() {
+  const [plan, setPlan] = React.useState("team");
+  const current = PLANS.find((item) => item.value === plan);
+
+  return (
+    <Radio.Group
+      label="Тариф рабочего пространства"
+      name="plan"
+      value={plan}
+      onValueChange={setPlan}
+      hint={`Будет подключён тариф «${current?.label}»`}
+    >
+      {PLANS.map((item) => (
+        <Radio.Root key={item.value} value={item.value} hint={item.hint}>
+          <Radio.Label>{item.label}</Radio.Label>
+        </Radio.Root>
+      ))}
+    </Radio.Group>
+  );
+}

package/src/components/radio/examples/group.tsx

@@ -0,0 +1,23 @@
+/** A required group with option descriptions and the group's error under the options — `label`, `required`, `hint`, `error`. */
+import { Radio } from "prime-ui-kit";
+
+export default function RadioGroupExample() {
+  return (
+    <Radio.Group
+      label="Способ оплаты"
+      name="payment"
+      required
+      error="Выберите способ оплаты, чтобы оформить заказ"
+    >
+      <Radio.Root value="card" hint="Списание сразу после подтверждения заказа">
+        <Radio.Label>Банковская карта</Radio.Label>
+      </Radio.Root>
+      <Radio.Root value="invoice" hint="Реквизиты придут на почту в течение рабочего дня">
+        <Radio.Label>Счёт для юрлица</Radio.Label>
+      </Radio.Root>
+      <Radio.Root value="sbp" disabled hint="Подключается в настройках магазина">
+        <Radio.Label>СБП</Radio.Label>
+      </Radio.Root>
+    </Radio.Group>
+  );
+}

package/src/components/radio/examples/orientation.tsx

@@ -0,0 +1,34 @@
+/** Options stacked in a column and laid out in a wrapping row — `orientation`. */
+import { Radio } from "prime-ui-kit";
+
+const PERIODS = [
+  { value: "week", label: "Неделя" },
+  { value: "month", label: "Месяц" },
+  { value: "quarter", label: "Квартал" },
+];
+
+export default function RadioOrientationExample() {
+  return (
+    <>
+      <Radio.Group label="vertical" name="period-vertical" defaultValue="month">
+        {PERIODS.map((period) => (
+          <Radio.Root key={period.value} value={period.value}>
+            <Radio.Label>{period.label}</Radio.Label>
+          </Radio.Root>
+        ))}
+      </Radio.Group>
+      <Radio.Group
+        label="horizontal"
+        name="period-horizontal"
+        defaultValue="month"
+        orientation="horizontal"
+      >
+        {PERIODS.map((period) => (
+          <Radio.Root key={period.value} value={period.value}>
+            <Radio.Label>{period.label}</Radio.Label>
+          </Radio.Root>
+        ))}
+      </Radio.Group>
+    </>
+  );
+}

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

@@ -0,0 +1,18 @@
+/** A labelled group of options with one chosen by default — `label`, `defaultValue`. */
+import { Radio } from "prime-ui-kit";
+
+export default function RadioOverviewExample() {
+  return (
+    <Radio.Group label="Доставка" name="delivery" defaultValue="courier">
+      <Radio.Root value="courier">
+        <Radio.Label>Курьером</Radio.Label>
+      </Radio.Root>
+      <Radio.Root value="pickup">
+        <Radio.Label>Самовывоз из пункта выдачи</Radio.Label>
+      </Radio.Root>
+      <Radio.Root value="post">
+        <Radio.Label>Почтой России</Radio.Label>
+      </Radio.Root>
+    </Radio.Group>
+  );
+}

package/src/components/radio/examples/sizes.tsx

@@ -0,0 +1,20 @@
+/** Every size; the circle and the text follow the group tier — `size`. */
+import { Radio } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function RadioSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Radio.Group size={size} defaultValue={size} aria-label={`Размер ${size}`}>
+            <Radio.Root value={size}>
+              <Radio.Label>{size}</Radio.Label>
+            </Radio.Root>
+          </Radio.Group>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,48 @@
+/** Every state, each in its own group and labelled by its prop — `value`, `invalid`, `disabled`. */
+import { Radio } from "prime-ui-kit";
+
+export default function RadioStatesExample() {
+  return (
+    <>
+      <div>
+        <div>
+          <Radio.Group aria-label="unchecked">
+            <Radio.Root value="unchecked">
+              <Radio.Label>unchecked</Radio.Label>
+            </Radio.Root>
+          </Radio.Group>
+        </div>
+        <div>
+          <Radio.Group defaultValue="checked" aria-label="checked">
+            <Radio.Root value="checked">
+              <Radio.Label>checked</Radio.Label>
+            </Radio.Root>
+          </Radio.Group>
+        </div>
+        <div>
+          <Radio.Group invalid aria-label="invalid">
+            <Radio.Root value="invalid">
+              <Radio.Label>invalid</Radio.Label>
+            </Radio.Root>
+          </Radio.Group>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Radio.Group disabled aria-label="disabled">
+            <Radio.Root value="disabled">
+              <Radio.Label>disabled</Radio.Label>
+            </Radio.Root>
+          </Radio.Group>
+        </div>
+        <div>
+          <Radio.Group disabled defaultValue="checked" aria-label="disabled · checked">
+            <Radio.Root value="checked">
+              <Radio.Label>disabled · checked</Radio.Label>
+            </Radio.Root>
+          </Radio.Group>
+        </div>
+      </div>
+    </>
+  );
+}

package/src/components/scroll-container/COMPONENT.md

@@ -0,0 +1,118 @@
+# ScrollContainer
+
+**Category:** layout
+**Kind:** layout
+
+> A scroll region with the kit's thin scrollbar that shrinks correctly inside flex and grid parents.
+
+## When to use
+- A list, feed or panel body with a fixed height that must scroll on its own.
+- A horizontal strip of chips or filters that may overflow the row (`axis="horizontal"`).
+- A row whose overflow must be hinted without a scrollbar (`fade`, `scrollbar="hidden"`): tab rows, segment rows, chip strips.
+- A custom panel or page column that needs the same scrollbar and overscroll rules as the kit's own overlays.
+
+## When not to use
+- Modal / Drawer body, Select / Dropdown / Popover panels, CommandMenu list, DataTable viewport → they already scroll through ScrollContainer; do not wrap them again ([Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Popover](../popover/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)).
+- The main page column inside the app shell → `AppShell.Main` is already a ScrollContainer ([AppShell](../../layout/app-shell/COMPONENT.md)).
+- Content that should simply grow with the page → no scroll container at all.
+
+## Import
+```tsx
+import { ScrollContainer } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+ScrollContainer   <div> (or the `as` tag); thin scrollbar, optional edge fade
+└─ children       the scrolling content
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ScrollContainer
+`ref` → `HTMLElement`. A scroll region with the kit's thin scrollbar that shrinks inside flex and grid parents; no padding of its own.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `axis` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | Scroll axis; the other axis is clipped (except `both`). |
+| `fade` | `boolean` | `false` | Fades the edge where more content is hidden (`--prime-space-8` mask): horizontal for `axis="horizontal"`, vertical otherwise. Follows scroll and size changes. |
+| `scrollbar` | `"thin" \| "hidden"` | `"thin"` | `thin` — the kit's quiet scrollbar; `hidden` — no scrollbar, only together with `fade` so the overflow stays visible. |
+| `overscrollBehavior` | `"auto" \| "contain" \| "none"` | `"contain"` | CSS `overscroll-behavior`; `contain` stops scroll chaining into the page. |
+| `as` | `"div" \| "main" \| "aside" \| "section" \| "nav" \| "article"` | `"div"` | Root element; a landmark tag when the region is one. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` (height, padding), `aria-label`, `tabIndex`, `role`, event handlers and the other attributes. |
+
+## Variants
+
+### axis
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `vertical` | `overflow-y: auto`, `overflow-x: hidden`, thin vertical thumb | Lists, feeds, panel bodies | yes |
+| `horizontal` | `overflow-x: auto`, `overflow-y: hidden`, thin horizontal thumb | Chip / filter strips, wide rows | |
+| `both` | `overflow: auto` on both axes | Wide tables or canvases that also scroll vertically | |
+
+### overscrollBehavior
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `contain` | Reaching the end does not scroll the page behind | Nested panels, lists inside a page | yes |
+| `auto` | Browser default: scroll chains to the parent | The region is the page's main scroller and should hand off | |
+| `none` | No chaining and no overscroll glow / bounce | Full-screen app regions | |
+
+### scrollbar
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `thin` | quiet `fill-strong` thumb on a transparent track | most regions | yes |
+| `hidden` | no scrollbar; content still scrolls by wheel, touch and keyboard focus | together with `fade`, where a scrollbar would cut a compact row | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fade` | the hidden edge dissolves into the surface; appears and disappears with the scroll position, without animation | strips and lists whose overflow must be hinted | off |
+
+`scrollbar="hidden"` without `fade` makes the overflow invisible — avoid it. `as="main"` only for the one main column of a page.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| fade on | `fade` | `data-fade="vertical" \| "horizontal"` |
+| content hidden before / after | scroll position (with `fade`), re-measured on resize and when children are added; logical in RTL | `data-overflow-start="true"`, `data-overflow-end="true"` |
+
+The scrollbar thumb uses `fill-strong`, darkening to `fill-strong-hover` on hover (WebKit). The fade mask follows the scroll at once: scrolling is high-frequency, so nothing animates.
+
+## Layout & spacing
+- Sets `min-width: 0` and `min-height: 0`, so it shrinks inside a flex or grid parent; give the parent (or the container) a height.
+- Has **no padding of its own** (foundation §7): the host either pads the scrolling element by at least `--prime-focus-space` so focus rings are not clipped, or keeps content full-bleed and uses inset focus rings. Put side padding on the scrolling element itself (through `className`), never on an outer wrapper.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Renders a plain element; add `tabIndex={0}` and `aria-label` when the region has no focusable content but must scroll from the keyboard.
+- Choose a semantic `as` (`main`, `nav`, `aside`) when the region is a landmark.
+- `fade` is only a mask: content under it stays reachable and scrolls by wheel, touch and focus.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar. |
+| [variants.tsx](examples/variants.tsx) | A strip that scrolls sideways and a wide schedule that scrolls both ways — `axis`. |
+| [edge-fade.tsx](examples/edge-fade.tsx) | Edges fade where more content is hidden; the horizontal strip also hides its scrollbar — `fade`, `scrollbar`. |
+| [overscroll.tsx](examples/overscroll.tsx) | At the end of the list the scroll passes on to the page instead of stopping — `overscrollBehavior`. |
+
+## Mistakes
+- `overflow: auto` on a plain `div` inside a flex column that never shrinks → use ScrollContainer (it sets `min-height: 0`).
+- Padding on a wrapper around the scroller → put the padding on the ScrollContainer itself.
+- A hand-made edge-fade mask or hidden scrollbar → `fade` and `scrollbar="hidden"`.
+- Wrapping a Modal body or Dropdown panel in another ScrollContainer → they already scroll.
+
+## Related
+- **Built from:** —
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Tabs](../tabs/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)