prime-ui-kit 0.14.0 → 0.16.0

package/src/components/progress-circle/COMPONENT.md

@@ -41,38 +41,25 @@ with legend:             <div data-legend> — a row: the ring box + <ul> legend
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### ProgressCircle
-`ref` → `HTMLDivElement` (the root). Props of both modes; pass either `value` (value mode) or `segments` (segments mode), never both.
+`ref` → `HTMLDivElement` (the root). Pass `value` (value mode: the svg is `role="progressbar"`, a track and one round-capped arc from the top) or `segments` (segments mode: the svg is `role="group"`, parts clockwise from the top), never both.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Diameter 24 · 32 · 48 · 64 · 80 px; the stroke is 1/12 of it. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Diameter 24 · 32 · 48 · 64 · 80 px; the stroke is 1/12 of it. Without it the ring takes the tier of a sized host. |
 | `children` | `ReactNode` | — | Content in the center (number, percent, `Icon`): text from `m`, an icon from `s`, nothing on `xs`. A string or number also becomes `aria-valuetext`. |
 | `aria-label` | `string` | — | Accessible name of the ring (set on the svg). Always pass it. |
 | `loading` | `boolean` | `false` | The data is on its way: a Skeleton ring of the same diameter and stroke (and legend lines) that cross-fades into the data; the inner content waits, the root is `aria-busy`. |
+| `value` | `number \| null` | — | Value mode: the current value, clamped to `0…max`; it glides to a new value (`base`). `null` — under way, the share unknown: a quarter arc that always turns, no `aria-valuenow`. |
+| `spin` | `boolean` | `false` | Value mode: the ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns. |
+| `max` | `number` | `100` (value mode), the sum of the parts (segments mode) | Value mode: top of the scale. Segments mode: total capacity; the sum of the parts closes the ring, a larger `max` leaves the rest as track. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info" \| "inherit"` | `"accent"` | Value mode: arc color, telling the outcome. `inherit` — the arc in the host's text color over a 32% track of it, for a ring on a colored host or over media. |
+| `segments` | `ProgressSegment[]` | — | Segments mode: parts in order, `{ value, label?, tone? \| color? }`: `tone` names a meaning (default `accent`), `color` a category — its step of the chart palette. Each part's length is its share of `max`. |
+| `segmentGap` | `"none" \| "hairline"` | `"none"` | Segments mode: `none` — one continuous ring; `hairline` — every part and the rest are separate round arcs. |
+| `legend` | `boolean` | `false` | Segments mode: a legend beside the ring (below it when narrow), one row per part: color · name · value · share; with `aria-label` it becomes the group's description. The root turns into the row of ring and legend. |
+| `formatValue` | `(value: number) => string` | Russian digit groups | Segments mode: display of a part's value in the legend («38 ГБ»). |
+| `labels` | `Partial<ProgressCircleLabels>` | — | Segments mode: built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
 
-### ProgressCircle · value mode
-The svg is `role="progressbar"`: a track and one round-capped arc from 12 o'clock.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `value` | `number \| null` | — (required) | The current value, clamped to `0…max`; it glides to a new value (`base`). `null` — under way, the share unknown: a quarter arc that always turns, no `aria-valuenow`. |
-| `spin` | `boolean` | `false` | The ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns. |
-| `max` | `number` | `100` | Top of the scale. |
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info" \| "inherit"` | `"accent"` | Arc color, telling the outcome. `inherit` — the arc in the host's text color over a 32% track of it, for a ring on a colored host or over media. |
-
-### ProgressCircle · segments mode
-The svg is `role="group"`: parts clockwise from the top, described by the legend or the distribution text.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? \| color? }`: `tone` names a meaning (default `accent`), `color` a category — its step of the chart palette. Each part's length is its share of `max`. |
-| `max` | `number` | — | Total capacity. Default: the sum of the parts (they close the ring); a larger `max` leaves the rest as track. |
-| `segmentGap` | `"none" \| "hairline"` | `"none"` | `none` — one continuous ring; `hairline` — every part and the rest are separate round arcs. |
-| `legend` | `boolean` | `false` | A legend beside the ring (below it when the row is narrow), one row per part: color · name · value · share; it becomes the group's description. The root turns into the row of ring and legend. |
-| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a part's value in the legend («38 ГБ»). |
-| `labels` | `Partial<ProgressCircleLabels>` | — | Built-in strings, see Labels. |
-
 ## Variants
 
 ### size
@@ -80,7 +67,7 @@ The svg is `role="group"`: parts clockwise from the top, described by the legend
 |---|---|---|---|
 | `xs` | 24 diameter, no inner content | inline in text or table cells | |
 | `s` | 32 diameter, an icon 16 in the center, no text | list rows, compact cards | |
-| `m` | 48 diameter, inner text 12/16, icon 20 | KPI tiles | yes |
+| `m` | 48 diameter, inner text 12/16, icon 20 | KPI tiles | the host tier, else `m` |
 | `l` | 64 diameter, inner text 16/24, icon 24 | dashboard cards | |
 | `xl` | 80 diameter, inner text 18/24, icon 32 | hero metrics, breakdowns | |
 
@@ -128,13 +115,13 @@ The stroke is always 1/12 of the diameter (the kit ring's `data` weight). These
 | icon change | a new icon in `children` (another `name`) | the old one shrinks to 0.6 and fades, the new one grows in (`fast`) and plays its gesture once; a changing number updates in place |
 | segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the svg, `data-tone` or `data-color` on every arc and cap; arcs glide by dash, caps by `rotate` |
 | legend | `legend` | `data-legend` on the root, which becomes a wrapping row of the ring and the `<ul>` |
-| loading | `loading` | `aria-busy` on the root; a Skeleton ring (mask of the stroke) and legend lines; the data cross-fades in (`swapMotion`) |
+| loading | `loading` | `aria-busy` on the root; a Skeleton ring (mask of the stroke) and legend lines; the data cross-fades in (`RegionSwap`) |
 | reduced motion | `prefers-reduced-motion` | arcs and icons change instantly; a turning ring turns twice as slow and never stops |
 
 Always controlled: pass the current `value` or `segments`.
 
 ## Layout & spacing
-- `display: inline-flex`, never shrinks (with `legend` the root is a block `flex` row); a caption sits next to it with `--prime-space-3` or under it with `--prime-space-2`.
+- `display: inline-flex`, never shrinks (with `legend` the root is a block `flex` row); a caption sits 12 beside it or 8 under it (a gap on their parent).
 - Diameters sit on the 4px grid (`--prime-space-6…20`); the ring is placed in CSS (an svg without a viewBox), lengths along it are percent of the circle.
 - Inner content sits in the hole (5/6 of the diameter, clipped), primary, medium weight, tabular numbers.
 - With `legend` the root is a wrapping row: the ring and the legend `--prime-space-5` (20) apart; the legend takes the rest of the row (basis 192) and drops below the ring when that does not fit.
@@ -143,12 +130,16 @@ Always controlled: pass the current `value` or `segments`.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Value mode: the svg is `role="progressbar"` with `aria-valuenow` / `-min` / `-max`; a string or number child becomes `aria-valuetext`. With `value={null}` there is no `aria-valuenow` — the share is unknown.
 - The turn never stops under reduced motion (twice as slow): it is the only sign the work goes on.
-- Segments mode: the svg is `role="group"`; with `aria-label` it is described by the distribution («Видео: 38%, Документы: 21%») or by the legend, without it the distribution is its name.
+- Segments mode: the svg is `role="group"`; with `aria-label` it is named by it and the text in the centre («Хранилище, 72%») and described by the distribution («Видео: 38%, Документы: 21%») or by the legend, without it the distribution is its name.
 - A category color always sits beside its name in the legend, so color is never the only cue.
 - While `loading` the root is `aria-busy` and the Skeletons are `aria-hidden`.
 - Always pass `aria-label`: a caption next to the ring is not linked to it.
@@ -171,8 +162,9 @@ No keyboard interaction.
 | [states.tsx](examples/states.tsx) | Loading is a Skeleton ring of the same diameter and stroke; the number in the centre waits for the data — `loading`. |
 | [inner-content.tsx](examples/inner-content.tsx) | The center holds a percentage, a count on its own scale or an icon — `children`, `max`. |
 | [under-way.tsx](examples/under-way.tsx) | An import whose share is not known yet turns a quarter arc, then fills and swaps its icon; a sync turns while its share grows — `value`, `spin`, `children`. |
-| [segments.tsx](examples/segments.tsx) | Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list — `segments`, `segmentGap`. |
+| [segments.tsx](examples/segments.tsx) | Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list with its own spoken text — `segments`, `segmentGap`, `labels`. |
 | [legend.tsx](examples/legend.tsx) | A ring of category shares with a legend beside it, in the categories' chart colors — `color`, `legend`, `formatValue`. |
+| [on-color.tsx](examples/on-color.tsx) | A ring on a colored host takes the host's text color — `tone`. |
 
 ## Mistakes
 - No `aria-label` (even with a visible caption) → screen readers get an unnamed progressbar.
@@ -185,5 +177,5 @@ No keyboard interaction.
 - Categories painted with `tone` → use `color`; a hand-built legend beside the ring → `legend`.
 
 ## Related
-- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/ring` (the ring drawing, shared with Spinner and the circle Button), `internal/glyphSwap` (the center cross-fade)
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/ring` (the ring drawing, shared with Spinner and the circle Button), `internal/glyphSwap` (the center cross-fade), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ProgressBar](../progress-bar/COMPONENT.md), [Card](../card/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [Button](../button/COMPONENT.md)

package/src/components/progress-circle/examples/examples.module.css

@@ -11,7 +11,7 @@
 
 /* A dashboard card as wide as a short form: the legend sits beside the ring or drops under it. */
 .card {
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 .item {

package/src/components/progress-circle/examples/on-color.tsx

@@ -0,0 +1,16 @@
+/** A ring on a colored host takes the host's text color — `tone`. */
+import { Banner, ProgressCircle } from "prime-ui-kit";
+
+export default function ProgressCircleOnColorExample() {
+  return (
+    <Banner.Root variant="solid" tone="info">
+      <Banner.Content>
+        <Banner.Icon>
+          <ProgressCircle size="xs" value={64} tone="inherit" aria-label="Экспорт отчёта" />
+        </Banner.Icon>
+        <Banner.Title>Экспорт отчёта за квартал</Banner.Title>
+        <Banner.Description>Готово 64%, файл придёт на почту.</Banner.Description>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}

package/src/components/progress-circle/examples/segments.tsx

@@ -1,4 +1,4 @@
-/** Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list — `segments`, `segmentGap`. */
+/** Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list with its own spoken text — `segments`, `segmentGap`, `labels`. */
 import { ProgressCircle, type ProgressSegment, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -54,9 +54,14 @@ export default function ProgressCircleSegmentsExample() {
         </Typography>
       </div>
       <div className={styles.item}>
-        <ProgressCircle size="xl" segments={[]} aria-label="Нет данных" />
+        <ProgressCircle
+          size="xl"
+          segments={[]}
+          aria-label="Заявки за ноябрь"
+          labels={{ empty: "Заявок пока нет" }}
+        />
         <Typography as="span" variant="caption" tone="muted">
-          Нет данных
+          Заявки за ноябрь
         </Typography>
       </div>
     </div>

package/src/components/progress-circle/examples/variants.tsx

@@ -8,6 +8,7 @@ const TONES = [
   { tone: "danger", label: "Сбой импорта", value: 20 },
   { tone: "info", label: "Синхронизация", value: 30 },
   { tone: "neutral", label: "Индексация", value: 55 },
+  { tone: "inherit", label: "Экспорт", value: 64 },
 ] as const;
 
 export default function ProgressCircleVariantsExample() {

package/src/components/radio/COMPONENT.md

@@ -11,7 +11,7 @@
 - A required one-of-many question in a form.
 
 ## When not to use
-- 2–4 short view modes or filters that apply instantly → use [SegmentedControl](../segmented-control/COMPONENT.md) instead.
+- 2–5 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.
@@ -42,7 +42,7 @@ Radio.Group             field: group label → role="radiogroup" → hint | erro
 | `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`. |
+| `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`). |
@@ -54,6 +54,7 @@ Radio.Group             field: group label → role="radiogroup" → hint | erro
 | `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). |
+| `children` | `ReactNode` | — | The `Radio.Root` options. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `className`, `data-*` and the other attributes of the field frame `<div>`. |
 
 ### Radio.Root
@@ -71,6 +72,10 @@ Radio.Group             field: group label → role="radiogroup" → hint | erro
 ### Radio.Label
 `ref` → `HTMLSpanElement`. The visible text in the text column of the option row. Native `<span>` props.
 
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
 ## Variants
 No `variant` / `tone` / `color`.
 
@@ -118,13 +123,15 @@ The radiogroup carries `data-size`, `data-orientation`, `aria-orientation`, `ari
 
 ## 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`.
+- Options inside a group: gap `--prime-space-2`; groups in a form stand in a [Fieldset](../fieldset/COMPONENT.md), which sets the rhythm between them.
 - An option hint aligns with the text column, not with the circle.
 - Long labels wrap; horizontal rows wrap at narrow widths.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Focuses the selected option (or the first one when nothing is selected). |
@@ -132,6 +139,8 @@ The radiogroup carries `data-size`, `data-orientation`, `aria-orientation`, `ari
 | `Space` | Selects the focused option. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `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`.
@@ -152,6 +161,7 @@ The radiogroup carries `data-size`, `data-orientation`, `aria-orientation`, `ari
 | [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`. |
+| [in-form.tsx](examples/in-form.tsx) | Choices of an order form: a required group shows its error after a submit without a choice, an optional one is marked — `name`, `required`, `optional`, `error`. |
 
 ## Mistakes
 - `Radio.Root` outside `Radio.Group` → it throws; every option needs the group.
@@ -161,5 +171,5 @@ The radiogroup carries `data-size`, `data-orientation`, `aria-orientation`, `ari
 - Eight or more options → use `Select`.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (group label), [Hint](../hint/COMPONENT.md) (`hint`, `error`, option hints); option rows are native `<label>` elements
+- **Built from:** [Label](../label/COMPONENT.md) (group label), [Hint](../hint/COMPONENT.md) (`hint`, `error`, option hints), [VisuallyHidden](../visually-hidden/COMPONENT.md); option rows are native `<label>` elements
 - **See also:** [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md)

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

@@ -0,0 +1,14 @@
+/* Layout of the Radio scenarios: semantic tokens only. */
+
+/* in-form.tsx: groups, then actions (group → actions 32). */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-6);
+  width: min(100%, var(--prime-layout-form-width-s));
+}
+
+.formActions {
+  display: flex;
+  margin-top: var(--prime-space-2);
+}

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

@@ -0,0 +1,45 @@
+/** Choices of an order form: a required group shows its error after a submit without a choice, an optional one is marked — `name`, `required`, `optional`, `error`. */
+import { Button, Radio } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function RadioInFormExample() {
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const chosen = new FormData(event.currentTarget).get("delivery");
+    setError(chosen ? undefined : "Выберите способ доставки");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Radio.Group
+        label="Способ доставки"
+        name="delivery"
+        required
+        error={error}
+        onValueChange={() => setError(undefined)}
+      >
+        <Radio.Root value="courier">
+          <Radio.Label>Курьером до склада</Radio.Label>
+        </Radio.Root>
+        <Radio.Root value="pickup">
+          <Radio.Label>Самовывоз с терминала</Radio.Label>
+        </Radio.Root>
+      </Radio.Group>
+      <Radio.Group label="Упаковка" name="packing" optional>
+        <Radio.Root value="pallet">
+          <Radio.Label>На паллетах</Radio.Label>
+        </Radio.Root>
+        <Radio.Root value="crate">
+          <Radio.Label>В обрешётке</Radio.Label>
+        </Radio.Root>
+      </Radio.Group>
+      <div className={styles.formActions}>
+        <Button.Root type="submit">Оформить заказ</Button.Root>
+      </div>
+    </form>
+  );
+}

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

@@ -10,13 +10,14 @@
 - A strip whose overflow must be hinted without a scrollbar (`scrollbar="hidden"` with the default `edges="fade"`): tab rows, chip strips, attachment trays; add `snap` for tiles and cards.
 - A region that is itself a filled surface (a floating panel, a code well): `edges="shadow"`.
 - A list that must hold still for a while (an open review, a gesture that must not move it): `lock`.
-- A chat or a live log that stays at its newest entry (`anchor="end"`) and loads history while scrolling back (`onReachStart`).
+- A live log that stays at its newest entry (`anchor="end"`) and loads history while scrolling back (`onReachStart`).
 - A feed that loads the next page near its end (`onReachEnd`).
 
 ## When not to use
 - Modal / Drawer / Sheet body, Select / Dropdown / Popover / TagSelect panels, CommandMenu list, Tabs and SegmentedControl rows, DataTable and Gantt viewports, Kanban, Sidebar, the Composer tray → 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.
+- A chat → use [Chat](../chat/COMPONENT.md) (`Chat.Messages` keeps its own scroll region, selection and jumps).
 - A long list of thousands of rows → ScrollContainer scrolls it, the host renders only the rows in view (DataTable `paging="infinite"`, `Chat.Messages`, Gantt); ScrollContainer has no virtual mode of its own.
 
 ## Import
@@ -43,12 +44,12 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, soft hidden edges
 | `edges` | `"fade" \| "shadow" \| "none"` | `"fade"` | Edges that hide content: `fade` dissolves them over any background; `shadow` — a soft shadow on the region's own fill (a floating panel, a code well); `none` — plain edges. |
 | `scrollbar` | `"thin" \| "hidden"` | `"thin"` | `thin` — the kit's quiet scrollbar; `hidden` — no scrollbar, keep `edges` on so the overflow stays visible. |
 | `lock` | `boolean` | `false` | The person cannot scroll the region (wheel, touch, keys, a drag's auto-scroll); code still can. Sets `data-lock`. |
-| `snap` | `boolean` | `false` | Scrolling comes to rest on the start of a child (proximity snapping). For strips of tiles and cards; not with `anchor="end"`. |
+| `snap` | `boolean \| "mandatory"` | `false` | Scrolling comes to rest on the start of a child: `true` near one (strips of tiles and cards), `"mandatory"` always on one (board columns, a carousel). A Dnd drag inside turns it off; not with `anchor="end"`. |
 | `anchor` | `"start" \| "end"` | `"start"` | `end` — a chat or a log: opens at the end and follows new content while the person is at the end; scrolled away, the view holds still. |
 | `onReachStart` | `() => void \| Promise<void>` | — | Fires within 120 px of the start, once per approach: load older content. A returned promise blocks repeats and sets `aria-busy`; content added above keeps the view. |
 | `onReachEnd` | `() => void \| Promise<void>` | — | The scroll position came within 120 px of the end: load the next page. Same once-per-approach and promise rules as `onReachStart`. |
 | `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. |
+| `as` | `"div" \| "main" \| "aside" \| "section" \| "nav" \| "article" \| "pre"` | `"div"` | Root element; a landmark tag when the region is one, `pre` for preformatted text (CodeBlock). |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` (height, padding), `aria-label`, `tabIndex`, `role`, event handlers and the other attributes. |
 
 ## Variants
@@ -92,7 +93,8 @@ Only the reader scrolling back unpins the end: content that keeps growing (an an
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `lock` | nothing the person does scrolls the region (wheel, touch, keys, a drag's edge auto-scroll); the position stays, and code may still set it | a list behind an open review, a gesture that must not move it | off |
-| `snap` | a scroll comes to rest on the start of a direct child (proximity snapping); a host aligns deeper items itself | strips of tiles or cards | off |
+| `snap` | a scroll comes to rest on the start of a direct child near one (proximity); a host aligns deeper items itself | strips of tiles or cards | off |
+| `snap="mandatory"` | a scroll always comes to rest on the start of a child | board columns, a carousel of cards | off |
 
 ### Wheel and auto-scroll
 - `axis="horizontal"`: a vertical mouse wheel scrolls the strip sideways while it can move, gliding to an accumulated target (instant under reduced motion). A trackpad's sideways swipe and Shift + wheel stay native; a wheel gesture that began outside the strip keeps scrolling the page; at the strip's edge the wheel chains to the page. There is no drag-to-scroll: a press-and-drag in a strip belongs to its items (reordering tiles, tabs); touch pans natively.
@@ -112,16 +114,16 @@ Each fires once per approach — again after the position leaves the zone or the
 | State | Driven by | DOM |
 |---|---|---|
 | edge treatment | `edges` | `data-edges="fade" \| "shadow"` (none for `none`) |
-| content hidden at an edge | scroll position (with `edges="fade"`), measured at most once per frame on scroll, on resize of the region or a child and when children are added; only the scroll axes; logical in RTL | `data-overflow-top`, `data-overflow-bottom`, `data-overflow-start`, `data-overflow-end` = `"true"`; `--edge-*` depths written only while they change (within the last `--prime-space-8` of an edge), on non-inherited properties |
+| content hidden at an edge | scroll position (with `edges="fade"`), measured at most once per frame on scroll, on resize of the region or a child and when children are added; only the scroll axes; logical in RTL | `data-overflow-top`, `data-overflow-bottom`, `data-overflow-start`, `data-overflow-end` = `"true"`; `--edge-*` depths written only while they change (within the last fade depth of an edge, `--scroll-fade-depth`), on non-inherited properties |
 | locked | `lock` | `data-lock`, `overflow: hidden` |
-| snapping | `snap` | `data-snap`, `scroll-snap-type: <axis> proximity`; `scroll-snap-align: start` on the children |
+| snapping | `snap` | `data-snap="proximity" \| "mandatory"`, `scroll-snap-type: <axis> <strictness>`; `scroll-snap-align: start` on the children; off while a Dnd list inside carries an item (`data-dnd-carrying`) |
 | kit anchoring | `anchor="end"` or `onReachStart` | `data-anchor="end" \| "start"`, `overflow-anchor: none`: the kit keeps the visible entry in place (or the end, while pinned) before paint, the same in every browser |
 | pinned to the end | `anchor="end"` and the position within 4 px of the end | content changes scroll to the new end at once (high-frequency: no animation) |
 | loading at an edge | a pending promise from `onReachStart` / `onReachEnd` | `aria-busy="true"` |
 | content fits | the content is no larger than the region along its axis (re-measured on resize of the region or a child, and when children change); never with `anchor="end"`, `onReachStart` or `onReachEnd` — a region that follows its content always stays a scroller | `data-fits`, `overflow: hidden`: a region that cannot scroll is no scroller, so the browser never composites a layer for a sub-pixel overflow; text or inline content straight inside keeps it a scroller |
 | keyboard focus | `tabIndex={0}` on a region without focusable content | inset focus ring (`--prime-focus-offset-inset`) |
 
-The scrollbar thumb uses `fill-strong`, darkening to `fill-strong-hover` on hover (WebKit). The fade and the shadow follow the scroll at once: scrolling is high-frequency, so nothing animates. A fade region sets `scroll-padding` of the fade depth on its scroll axes, so focus, `scrollIntoView` and a snapped child land clear of the fade.
+The scrollbar thumb uses `fill-strong` and stays still on hover in every engine. The fade and the shadow follow the scroll at once: scrolling is high-frequency, so nothing animates. A fade region sets `scroll-padding` of the fade depth on its scroll axes, so focus, `scrollIntoView` and a snapped child land clear of the fade. The depth is `--scroll-fade-depth` (`--prime-space-8`), the one public hook of the region: a switcher that draws its own edge overlays sets it to their width.
 
 ## 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.
@@ -130,6 +132,8 @@ The scrollbar thumb uses `fill-strong`, darkening to `fill-strong-hover` on hove
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `↑` · `↓` · `←` · `→` | Scroll the focused region (with `tabIndex={0}`) by a step |
@@ -137,7 +141,9 @@ The scrollbar thumb uses `fill-strong`, darkening to `fill-strong-hover` on hove
 | `Home` · `End` | To the start and to the end |
 
 ### ARIA
-- Renders a plain element; add `tabIndex={0}` and `aria-label` when the region has no focusable content but must scroll from the keyboard (the browser scrolls it; the ring is inset).
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- Renders a plain element; a region named by `aria-label` / `aria-labelledby` becomes `role="region"` (a `role` of its own wins, e.g. `log`). Add `tabIndex={0}` and a name when the region has no focusable content but must scroll from the keyboard (the browser scrolls it; the ring is inset).
 - Choose a semantic `as` (`main`, `nav`, `aside`) when the region is a landmark.
 - `edges` is only decoration: content under a fade or a shadow stays reachable and scrolls by wheel, touch and focus; focus and `scrollIntoView` stop clear of a fade.
 - `lock` keeps the content in the focus order: a locked region does not scroll, its items stay reachable.
@@ -151,15 +157,16 @@ 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. |
+| [overview.tsx](examples/overview.tsx) | A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar — `ScrollContainer`. |
 | [variants.tsx](examples/variants.tsx) | A strip that scrolls sideways and a wide schedule that scrolls both ways — `axis`. |
 | [edges.tsx](examples/edges.tsx) | Hidden edges fade over any background, take a soft shadow on a filled surface, or stay plain — `edges`. |
 | [scrollbar.tsx](examples/scrollbar.tsx) | The kit's quiet thin bar on a list and no bar on a strip of chips, where the faded edges show the overflow — `scrollbar`. |
-| [snap.tsx](examples/snap.tsx) | A strip of warehouse cards that comes to rest on a card's start, scrolled by touch, a trackpad or the mouse wheel — `snap`, `axis`. |
+| [snap.tsx](examples/snap.tsx) | A strip of warehouse cards that always comes to rest on a card's start, scrolled by touch, a trackpad or the mouse wheel — `snap`, `axis`. |
 | [lock.tsx](examples/lock.tsx) | While an order is opened for review, the queue behind it holds still: no wheel, touch, key or drag moves it — `lock`. |
 | [auto-scroll.tsx](examples/auto-scroll.tsx) | A task dragged to the top or bottom edge of a scrolling list scrolls it, faster the closer it comes — `ScrollContainer`, `Dnd.Sortable`. |
 | [overscroll.tsx](examples/overscroll.tsx) | At the end of the list the scroll passes on to the page instead of stopping — `overscrollBehavior`. |
-| [chat.tsx](examples/chat.tsx) | A support chat pinned to its last message: a sent message keeps it at the end, scrolling up loads older ones without moving what is on screen — `anchor`, `onReachStart`. |
+| [log.tsx](examples/log.tsx) | A live exchange log pinned to its last entry: a new entry keeps it at the end, scrolling up loads older ones without moving what is on screen — `anchor`, `onReachStart`. |
+| [load-more.tsx](examples/load-more.tsx) | An order log that loads the next page as the reader nears its end, with loading lines in the rows' place — `onReachEnd`. |
 
 ## Mistakes
 - `overflow: auto` on a plain `div` inside a flex column that never shrinks → use ScrollContainer (it sets `min-height: 0`).
@@ -167,7 +174,7 @@ No `labels`.
 - `overflow: auto` anywhere in a kit component → a ScrollContainer (`src/styles/scroll.test.ts` fails on a raw scroller).
 - A hand-made edge-fade mask, edge shadow or hidden scrollbar → `edges` and `scrollbar="hidden"`.
 - `edges="fade"` on a region that paints its own fill or shadow → the mask dissolves them; use `edges="shadow"`.
-- A hand-made edge auto-scroll loop for a drag → `autoScrollStep` / `edgeSpeed` from `src/internal/edgeAutoScroll`.
+- A hand-made edge auto-scroll loop for a drag → `createEdgeAutoScroll` from `src/internal/edgeAutoScroll`.
 - `snap` together with `anchor="end"` → snapping fights the pin to the end.
 - Wrapping a Modal body or Dropdown panel in another ScrollContainer → they already scroll.
 - `scrollTop = scrollHeight` in an effect after every message → `anchor="end"` (it also leaves a reader who scrolled up alone).

package/src/components/scroll-container/examples/auto-scroll.tsx

@@ -22,9 +22,9 @@ export default function ScrollContainerAutoScrollExample() {
 
   return (
     <Card.Root role="region" className={styles.card} aria-label="План проекта">
-      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
-        План проекта
-      </Typography>
+      <Card.Header>
+        <Card.Title>План проекта</Card.Title>
+      </Card.Header>
       <ScrollContainer>
         <Dnd.Root>
           <Dnd.Sortable
@@ -38,10 +38,14 @@ export default function ScrollContainerAutoScrollExample() {
               setTasks((current) => moveBefore(current, id, beforeId, (task) => task.id))
             }
             renderItem={(task) => (
-              <Dnd.SortableItem id={task.id} className={styles.task}>
-                <Typography as="span" variant="body-m" truncate>
-                  {task.title}
-                </Typography>
+              <Dnd.SortableItem id={task.id}>
+                <Card.Root>
+                  <Card.Body>
+                    <Typography as="span" variant="body-m" truncate>
+                      {task.title}
+                    </Typography>
+                  </Card.Body>
+                </Card.Root>
               </Dnd.SortableItem>
             )}
           />

package/src/components/scroll-container/examples/edges.tsx

@@ -22,19 +22,22 @@ export default function ScrollContainerEdgesExample() {
     <div className={styles.layout}>
       {EDGES.map((edges) => (
         <Card.Root key={edges} role="region" className={styles.card} aria-label={`Лента: ${edges}`}>
-          <Typography as="h3" variant="title-s" className={styles.cardTitle}>
-            {edges}
-          </Typography>
+          <Card.Header>
+            <Card.Title>Лента событий</Card.Title>
+            <Typography as="span" variant="caption" tone="muted">
+              {edges}
+            </Typography>
+          </Card.Header>
           <ScrollContainer edges={edges}>
-            <ul className={styles.list}>
+            <Card.List>
               {EVENTS.map((event) => (
-                <li key={event}>
+                <Card.ListItem key={event}>
                   <Typography as="span" variant="body-m" tone="secondary">
                     {event}
                   </Typography>
-                </li>
+                </Card.ListItem>
               ))}
-            </ul>
+            </Card.List>
           </ScrollContainer>
         </Card.Root>
       ))}

package/src/components/scroll-container/examples/examples.module.css

@@ -17,57 +17,23 @@
   width: auto;
 }
 
-.cardTitle {
-  padding: var(--prime-space-3) var(--prime-space-4);
-}
-
-.list {
-  display: flex;
-  flex-direction: column;
-  margin: 0;
-  padding: 0 var(--prime-space-4) var(--prime-space-3);
-  list-style: none;
-}
-
-.list li {
-  padding-block: var(--prime-space-2);
-  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
-}
-
-/* Dividers only between items. */
-.list li:last-child {
-  border-bottom: 0;
-}
-
-/* chat.tsx: title, the scrolling messages and the composer in a fixed-height card. */
-.chat {
+/* log.tsx: title, the scrolling entries in a fixed-height card. */
+.log {
   display: grid;
-  grid-template-rows: auto minmax(0, 1fr) auto;
+  grid-template-rows: auto minmax(0, 1fr);
   width: min(100%, calc(var(--prime-space-24) * 4));
   height: calc(var(--prime-space-24) * 3.5);
 }
 
-.messages {
-  padding-top: var(--prime-space-2);
+.entries {
+  min-height: 0;
 }
 
-/* Older messages loading: lines in the messages' geometry, at the top where they will appear. */
+/* Older entries loading: lines in the entries' geometry, at the top where they will appear. */
 .older {
   margin: 0 var(--prime-space-4) var(--prime-space-2);
 }
 
-.composer {
-  display: flex;
-  align-items: center;
-  gap: var(--prime-space-2);
-  padding: var(--prime-space-3) var(--prime-space-4);
-}
-
-.composerField {
-  flex: 1 1 auto;
-  min-width: 0;
-}
-
 .strip {
   display: flex;
   gap: var(--prime-space-2);
@@ -77,7 +43,7 @@
 
 /* Two-axis scroller: the side padding lives on the scrolling element itself (foundation §7). */
 .canvas {
-  padding: 0 var(--prime-space-4) var(--prime-space-3);
+  padding: var(--prime-space-3) var(--prime-space-4);
 }
 
 .grid {
@@ -89,28 +55,16 @@
 
 .cell {
   padding: var(--prime-space-2);
-  border-radius: var(--prime-radius-s);
-  background: var(--prime-color-fill-subtle);
-  font-variant-numeric: tabular-nums;
-}
-
-/* lock.tsx: the title and the review button in one row above the queue. */
-.cardHeader {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--prime-space-3);
-  padding: var(--prime-space-3) var(--prime-space-4);
 }
 
-/* snap.tsx: a row of fixed-width cards; the padding keeps the edge cards' rings unclipped. */
+/* snap.tsx: a row of fixed-width cards (a flex row: its items draw no list markers); the padding
+   keeps the edge cards' rings unclipped. */
 .tiles {
   display: flex;
   gap: var(--prime-space-3);
   width: max-content;
   margin: 0;
   padding: var(--prime-space-1);
-  list-style: none;
 }
 
 .tile {
@@ -124,16 +78,5 @@
   flex-direction: column;
   gap: var(--prime-space-1);
   margin: 0;
-  padding: 0 var(--prime-space-3) var(--prime-space-3);
-  list-style: none;
-}
-
-.task {
-  display: flex;
-  align-items: center;
-  min-height: var(--prime-space-10);
-  padding-inline: var(--prime-space-3);
-  border-radius: var(--prime-radius-m);
-  background: var(--prime-color-fill-muted);
-  cursor: grab;
+  padding: var(--prime-space-3);
 }