prime-ui-kit 0.9.3 → 0.11.0

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

@@ -9,12 +9,14 @@
 - Compact metrics and goals in cards and dashboards (84% of plan).
 - Progress where horizontal space is short: table cells, list rows.
 - A value on a custom scale shown as a ring («7/12»).
-- A compact breakdown of a whole: tasks by status, storage by type (`segments`).
+- A compact breakdown of a whole: tasks by status, storage by type (`segments`); categories in their chart colors (`color`) with a `legend` beside the ring.
+- A named process whose share is not known yet (`value={null}`) or that turns while its share grows (`spin`), with an icon in the center that changes with its state.
 
 ## When not to use
 - Progress with a label and width to spare (uploads, imports) → use [ProgressBar](../progress-bar/COMPONENT.md).
 - A breakdown with many parts or long labels → [ProgressBar](../progress-bar/COMPONENT.md) with `segments`.
-- Unknown duration → use [Spinner](../spinner/COMPONENT.md); ProgressCircle is always determinate.
+- An anonymous «busy» mark inside a control or a region (a button, a select, a list) → [Spinner](../spinner/COMPONENT.md): it sizes like an icon and is a `status`.
+- A ring you can press (cancel, retry, download) → [Button](../button/COMPONENT.md) `shape="circle"` with `progress`; ProgressCircle is never interactive.
 
 ## Import
 ```tsx
@@ -23,10 +25,15 @@ import { ProgressCircle, type ProgressSegment } from "prime-ui-kit";
 
 ## Anatomy
 ```
-ProgressCircle           <div>; size, tone (value mode), children in the center
-├─ svg                   role="progressbar" (value) or role="group" (segments); track + arcs
-├─ description           visually hidden distribution (segments with aria-label)
-└─ inner                 children in the hole of the ring (not on xs / s)
+ProgressCircle           <div>; size, tone (value mode), children in the center, aria-busy while loading
+├─ svg                   the kit ring (internal/ring, data weight); role="progressbar" (value) or
+│                        role="group" (segments); track + arcs
+│                        (loading: a Skeleton ring of the same diameter and stroke)
+├─ description           visually hidden distribution (segments with aria-label, no legend)
+└─ inner                 children in the hole of the ring, a changed icon cross-fades
+                         (not on xs, text not on s, not while loading)
+
+with legend:             <div data-legend> — a row: the ring box + <ul> legend (swatch · name · value · share)
 ```
 
 ## API
@@ -39,27 +46,31 @@ ProgressCircle           <div>; size, tone (value mode), children in the center
 | 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. |
-| `children` | `ReactNode` | — | Content in the center (number, percent, `Icon`). Not rendered on `xs` / `s`; a string or number stays available as `aria-valuetext`. |
+| `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`. |
 | `…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.
+The svg is `role="progressbar"`: a track and one round-capped arc from 12 o'clock.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `number` | — (required) | The current value, clamped to `0…max`. |
+| `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"` | `"accent"` | Arc color, telling the outcome. |
+| `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 distribution text.
+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? }` (`tone` default `accent`); each part's length is its share of `max`. |
+| `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
@@ -68,12 +79,12 @@ The svg is `role="group"`: parts clockwise from the top, described by the distri
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `xs` | 24 diameter, no inner content | inline in text or table cells | |
-| `s` | 32 diameter, no inner content | list rows, compact cards | |
-| `m` | 48 diameter, inner text 12/16 | KPI tiles | yes |
-| `l` | 64 diameter, inner text 16/24 | dashboard cards | |
-| `xl` | 80 diameter, inner text 18/24 | hero metrics, breakdowns | |
+| `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 |
+| `l` | 64 diameter, inner text 16/24, icon 24 | dashboard cards | |
+| `xl` | 80 diameter, inner text 18/24, icon 32 | hero metrics, breakdowns | |
 
-The stroke is always 1/12 of the diameter.
+The stroke is always 1/12 of the diameter (the kit ring's `data` weight). These diameters are a data scale, separate from the control heights of a circle Button.
 
 ### tone (value mode or each segment)
 | Value | Looks like | Use when | Default |
@@ -84,6 +95,21 @@ The stroke is always 1/12 of the diameter.
 | `warning` | warning arc | at risk, quota almost used | |
 | `danger` | danger arc | failed, overdue share | |
 | `info` | info arc | informational processes (sync, indexing) | |
+| `inherit` (value mode) | the arc in the host's text color over a 32% track of it; the center text inherits it too | a ring on a colored host or over media | |
+
+### color (each segment, instead of tone)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `blue` · `orange` · `teal` · `yellow` · `pink` · `green` · `purple` · `red` | the hue's step of the chart palette (`--prime-color-chart-1…8`) | categories: channels, sources, regions — the color they have in charts | |
+| `gray` | `--prime-color-chart-other` | the «Прочее» share | |
+| `sky` | the palette's sky solid (no chart step) | only when the category is sky elsewhere | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `spin` (value mode) | the ring turns at any share, the arc never under 8% | a process whose share grows while it runs (a sync) | `false` |
+| `legend` | swatch · name · value · share rows beside the ring, below it when narrow | a breakdown read in numbers | `false` |
+| `loading` | a Skeleton ring (and legend lines) of the same geometry | the data is on its way | `false` |
 
 ### segmentGap
 | Value | Looks like | Use when | Default |
@@ -96,15 +122,23 @@ The stroke is always 1/12 of the diameter.
 |---|---|---|
 | size / tone | props | `data-size`, `data-tone` (value mode) on the root |
 | empty | `value` 0, or `segments` empty / all 0 | arc hidden, track only |
-| value | `value`, `max` | `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax`; the arc glides by `stroke-dashoffset` over `slow` |
-| segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the svg, `data-tone` on every arc and cap; arcs glide by dash, caps by `rotate` |
-| reduced motion | `prefers-reduced-motion` | arcs change instantly |
+| value | `value`, `max` | `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax`; `--ring-value` on the svg, the arc glides by `stroke-dashoffset` over `base` |
+| share unknown | `value={null}` | no `aria-valuenow`; `data-spin` on the svg: a quarter arc turning (one turn = 3 × `--prime-motion-loop`); a share that arrives glides out of the quarter |
+| spinning | `spin` | `data-spin` on the svg: the whole svg turns (a compositor transform) while the share glides on its own; the arc is at least 8% |
+| 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`) |
+| 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; a caption sits next to it with `--prime-space-3` or under it with `--prime-space-2`.
-- Diameters sit on the 4px grid (`--prime-space-6…20`); the ring geometry is in viewBox units.
+- `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`.
+- 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.
+- `hairline` arcs are ¾ of the stroke apart; arcs start at 12 o'clock and run clockwise.
 
 ## Accessibility
 
@@ -112,8 +146,11 @@ Always controlled: pass the current `value` or `segments`.
 No keyboard interaction.
 
 ### ARIA
-- Value mode: the svg is `role="progressbar"` with `aria-valuenow` / `-min` / `-max`; a string or number child becomes `aria-valuetext`.
-- Segments mode: the svg is `role="group"`; with `aria-label` it is described by the distribution («Видео: 38%, Документы: 21%»), without it the distribution is its name.
+- 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.
+- 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.
 - The inner text is `aria-hidden` when it is already the `aria-valuetext`.
 
@@ -131,16 +168,22 @@ No keyboard interaction.
 | [overview.tsx](examples/overview.tsx) | A plan ring with the percentage in the center, named for screen readers — `value`, `aria-label`. |
 | [variants.tsx](examples/variants.tsx) | Every arc color; the tone tells the outcome, not the progress — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Diameters 24 to 80 px; the center text is not rendered on `xs` and `s` — `size`. |
+| [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`. |
+| [legend.tsx](examples/legend.tsx) | A ring of category shares with a legend beside it, in the categories' chart colors — `color`, `legend`, `formatValue`. |
 
 ## Mistakes
 - No `aria-label` (even with a visible caption) → screen readers get an unnamed progressbar.
-- Text inside an `xs` / `s` ring → it is not rendered; show it outside.
+- Text inside an `xs` / `s` ring → it is not rendered; show it outside (an icon shows from `s`).
+- A fake indeterminate ring (`value={25}` plus a CSS rotation) → `value={null}`.
+- `onClick` on the ring to cancel → a [Button](../button/COMPONENT.md) `shape="circle"` with `progress`.
 - `value` and `segments` together → a type error; pick one mode.
 - `tone` on the root with `segments` → set `tone` on each segment.
 - Long text inside the ring → it is clipped to the inner circle.
+- Categories painted with `tone` → use `color`; a hand-built legend beside the ring → `legend`.
 
 ## Related
-- **Built from:** —
-- **See also:** [ProgressBar](../progress-bar/COMPONENT.md), [Card](../card/COMPONENT.md), [Spinner](../spinner/COMPONENT.md)
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/ring` (the ring drawing, shared with Spinner and the circle Button), `internal/glyphSwap` (the center cross-fade)
+- **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

@@ -9,6 +9,11 @@
   gap: var(--prime-space-6);
 }
 
+/* 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));
+}
+
 .item {
   display: flex;
   flex-direction: column;

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

@@ -0,0 +1,33 @@
+/** A ring of category shares with a legend beside it, in the categories' chart colors — `color`, `legend`, `formatValue`. */
+import { Card, ProgressCircle, type ProgressSegment } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TRAFFIC: ProgressSegment[] = [
+  { value: 18_420, label: "Поиск", color: "blue" },
+  { value: 9_310, label: "Реклама", color: "orange" },
+  { value: 6_050, label: "Соцсети", color: "pink" },
+  { value: 2_870, label: "Рассылки", color: "purple" },
+  { value: 1_240, label: "Прочее", color: "gray" },
+];
+
+const formatVisits = (value: number) => value.toLocaleString("ru-RU");
+
+export default function ProgressCircleLegendExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <ProgressCircle
+          size="xl"
+          segments={TRAFFIC}
+          segmentGap="hairline"
+          legend
+          formatValue={formatVisits}
+          aria-label="Визиты по каналам"
+        >
+          37,9 тыс.
+        </ProgressCircle>
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,25 @@
+/** Loading is a Skeleton ring of the same diameter and stroke; the number in the centre waits for the data — `loading`. */
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+export default function ProgressCircleStatesExample() {
+  return (
+    <div>
+      <div>
+        <ProgressCircle value={72} size="l" aria-label="План продаж">
+          72%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          value
+        </Typography>
+      </div>
+      <div>
+        <ProgressCircle value={0} size="l" aria-label="План продаж" loading>
+          0%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/under-way.tsx

@@ -0,0 +1,54 @@
+/** 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`. */
+import { Icon, ProgressCircle, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Orders synced at each tick, out of `ORDERS`. */
+const SYNCED = [0, 18, 41, 57, 74, 96, 118, 131, 140];
+const ORDERS = 140;
+
+/** Steps of the invoice import: unknown while the file is read, then the share. */
+const IMPORT: (number | null)[] = [null, null, null, 24, 52, 81, 100];
+
+export default function ProgressCircleUnderWayExample() {
+  const [step, setStep] = React.useState(0);
+
+  React.useEffect(() => {
+    // Runs again from the start after a pause on the finished state.
+    const timer = window.setTimeout(() => setStep((step + 1) % (SYNCED.length + 4)), 700);
+    return () => window.clearTimeout(timer);
+  }, [step]);
+
+  const imported = IMPORT[Math.min(step, IMPORT.length - 1)];
+  const synced = SYNCED[Math.min(step, SYNCED.length - 1)];
+  const syncing = synced < ORDERS;
+
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={imported} aria-label="Импорт счетов">
+          <Icon name={imported === 100 ? "action.check" : "action.download"} />
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Импорт счетов
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle
+          size="l"
+          value={synced}
+          max={ORDERS}
+          spin={syncing}
+          tone={syncing ? "accent" : "success"}
+          aria-label="Синхронизация заказов"
+        >
+          {`${synced}`}
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Заказы
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/radio/COMPONENT.md

@@ -27,14 +27,14 @@ Radio.Group             field: group label → role="radiogroup" → hint | erro
 └─ 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`.
+`className`, `ref` and the rest of `Radio.Group` go to the field frame; `id`, `aria-label`, `aria-labelledby` and `aria-describedby` to the `role="radiogroup"` element. `Radio.Root` must be inside `Radio.Group`. Without `Radio.Label` only the circle renders — give the option an `aria-label`.
 
 ## 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.
+`ref` → `HTMLDivElement` (the field frame). Owns the value, the shared `name` and size; renders the group label and the hint / error. `id` and the `aria-*` naming props go to the `role="radiogroup"` element.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -109,7 +109,7 @@ No `variant` / `tone` / `color`.
 |---|---|---|
 | 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 |
+| 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; the control shakes once when an error arrives (`data-shake` on the frame) |
 | 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 |
@@ -161,5 +161,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, option rows), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [Label](../label/COMPONENT.md) (group label), [Hint](../hint/COMPONENT.md) (`hint`, `error`, option hints); 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/scroll-container/COMPONENT.md

@@ -3,18 +3,21 @@
 **Category:** page
 **Kind:** layout
 
-> A scroll region with the kit's thin scrollbar that shrinks correctly inside flex and grid parents.
+> The kit's one scroll region: a thin scrollbar, soft edges wherever content is hidden, and correct shrinking 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.
+- Anything that scrolls: a list, feed or panel body with a fixed height, a strip of chips or tiles (`axis="horizontal"`), a wide canvas (`axis="both"`). Every scroll region of the kit is one.
+- 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 feed that loads the next page near its end (`onReachEnd`).
 
 ## 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)).
+- 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 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
 ```tsx
@@ -23,7 +26,7 @@ import { ScrollContainer } from "prime-ui-kit";
 
 ## Anatomy
 ```
-ScrollContainer   <div> (or the `as` tag); thin scrollbar, optional edge fade
+ScrollContainer   <div> (or the `as` tag); thin scrollbar, soft hidden edges
 └─ children       the scrolling content
 ```
 
@@ -32,13 +35,18 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, optional edge fade
 <!-- 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.
+`ref` → `HTMLElement`. The kit's one scroll region: thin scrollbar, soft edges where content is hidden, shrinks inside flex and grid parents; no padding of its own. Scroll it from code with the element's own `scrollTo` / `scrollBy`.
 
 | 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. |
+| `axis` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | Scroll axis; the other axis is clipped (except `both`). On `horizontal` a vertical mouse wheel scrolls the strip sideways. |
+| `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"`. |
+| `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. |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` (height, padding), `aria-label`, `tabIndex`, `role`, event handlers and the other attributes. |
@@ -59,26 +67,61 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, optional edge fade
 | `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 | |
 
+### edges
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fade` | the content dissolves toward every edge that hides more, as deep as the hidden part (`--prime-space-8` at most): the fade grows and melts with the scroll, never switches; an alpha mask, so it works over any background | lists, strips, panel bodies — anything without a fill of its own | yes |
+| `shadow` | a soft `bg.edgeShadow` shadow falls over an edge once content hides behind it; the region paints `--prime-color-layer-current` (pure CSS: covers scroll with the content over shadows fixed to the view) | the region is itself a filled surface (a floating panel, a code well) — a mask would dissolve its fill and shadow | |
+| `none` | plain edges | the page column; a table or chart that draws its own edge shadows from its sticky parts; a chat with sticky date chips | |
+
 ### 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 | |
+| `hidden` | no scrollbar; content still scrolls by wheel, touch and keyboard focus | strips where a bar would cut a compact row; the edges show the overflow | |
+
+### anchor
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | opens at the start; the browser keeps the view when content changes (with `onReachStart` the kit does) | lists, feeds, panels | yes |
+| `end` | opens at the end and follows new content while the person is at the end; scrolled away, the view holds still | chats, live logs, comment threads | |
+
+Only the reader scrolling back unpins the end: content that keeps growing (an animated height, a picture loading) stays followed. The visible entry is the first element under the top edge, found by a binary search over the children (a list of thousands reads a dozen boxes); a sticky element or a spacer of a virtual list (`data-scroll-skip`) is never it. The region also serves its content: `Chat.Messages` inside asks it to glide to the end — the kit's own glide, one position per frame toward the end as it is on that frame, so rows that render on the way never stop it short; from far away it lands one view before the end first, and the reader's wheel, touch or key stops it — to bring a replied or found message to its middle, to hold its anchoring while a message changes size in place (the message keeps the view itself: its bottom stays and the rows above glide, or a transcript grows past the edge instead of pushing the list; the hold's end records the place afresh), and follows whether the reader is at the end for its «к последним» button. The region scrolls only itself, never the page.
 
 ### 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 |
+| `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 |
 
-`scrollbar="hidden"` without `fade` makes the overflow invisible — avoid it. `as="main"` only for the one main column of a page.
+### 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.
+- A gesture held near an edge — a Dnd drag, a Gantt bar moved or drawn, a drag that paints a selection over table rows or messages — scrolls the region toward it, faster the closer the pointer (`src/internal/edgeAutoScroll`, one speed curve for the kit). A `lock`ed region or one whose content fits never moves.
+
+### Edge events
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `onReachStart` | fires within 120 px of the start; content added above keeps the view in place | history in a chat, older log entries | — |
+| `onReachEnd` | fires within 120 px of the end | the next page of a feed | — |
+
+Each fires once per approach — again after the position leaves the zone or the content grows (a short first page asks again). A returned promise blocks repeat calls and sets `aria-busy` until it settles; the content shows its own loading (a `Skeleton` where the entries will appear).
+
+`scrollbar="hidden"` with `edges="none"` 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.
+| 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 |
+| locked | `lock` | `data-lock`, `overflow: hidden` |
+| snapping | `snap` | `data-snap`, `scroll-snap-type: <axis> proximity`; `scroll-snap-align: start` on the children |
+| 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.
 
 ## 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.
@@ -87,12 +130,18 @@ The scrollbar thumb uses `fill-strong`, darkening to `fill-strong-hover` on hove
 ## Accessibility
 
 ### Keyboard
-No keyboard interaction.
+| Key | Action |
+|---|---|
+| `↑` · `↓` · `←` · `→` | Scroll the focused region (with `tabIndex={0}`) by a step |
+| `PageUp` · `PageDown` · `Space` | Scroll by a screen |
+| `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.
+- 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).
 - 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.
+- `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.
+- While an edge load is pending the region is `aria-busy`; announcing new entries is the feed's job (a polite status or `aria-live` on a counter), so a busy chat does not read every message aloud.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -104,15 +153,27 @@ No `labels`.
 |---|---|
 | [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`. |
+| [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`. |
+| [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`. |
 
 ## 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"`.
+- `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`.
+- `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).
+- `flex-direction: column-reverse` to keep a chat at the bottom → it reverses the reading and Tab order; use `anchor="end"`.
+- An IntersectionObserver sentinel for history or the next page → `onReachStart` / `onReachEnd`, which also keep the view in place and stop repeat calls.
 
 ## 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)
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Tabs](../tabs/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Dnd](../dnd/COMPONENT.md) — edge auto-scroll, [Chat](../chat/COMPONENT.md) — a chat list in `anchor="end"`

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

@@ -0,0 +1,52 @@
+/** A task dragged to the top or bottom edge of a scrolling list scrolls it, faster the closer it comes — `ScrollContainer`, `Dnd.Sortable`. */
+import { Card, Dnd, moveBefore, ScrollContainer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TASKS = [
+  { id: "brief", title: "Согласовать бриф" },
+  { id: "budget", title: "Утвердить бюджет" },
+  { id: "design", title: "Макеты главной страницы" },
+  { id: "copy", title: "Тексты для каталога" },
+  { id: "build", title: "Вёрстка и интеграция" },
+  { id: "payments", title: "Подключить оплату" },
+  { id: "review", title: "Ревью и правки" },
+  { id: "qa", title: "Проверка на телефонах" },
+  { id: "launch", title: "Запуск" },
+  { id: "report", title: "Отчёт клиенту" },
+];
+
+export default function ScrollContainerAutoScrollExample() {
+  const [tasks, setTasks] = React.useState(TASKS);
+
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="План проекта">
+      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+        План проекта
+      </Typography>
+      <ScrollContainer>
+        <Dnd.Root>
+          <Dnd.Sortable
+            as="ul"
+            aria-label="Задачи"
+            className={styles.sortable}
+            items={tasks}
+            getId={(task) => task.id}
+            getLabel={(task) => task.title}
+            onReorder={(id, beforeId) =>
+              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>
+            )}
+          />
+        </Dnd.Root>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}