prime-ui-kit 0.10.0 → 0.11.0

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 |
 |---|---|---|---|
@@ -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>
+  );
+}

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

@@ -0,0 +1,101 @@
+/** 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`. */
+import { Button, Card, Icon, Input, ScrollContainer, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Message = { id: number; author: string; text: string };
+
+const HISTORY: Message[] = [
+  "Добрый день! Счёт № 4821 пришёл без НДС.",
+  "Здравствуйте, проверю реквизиты и вернусь.",
+  "Спасибо, ждём — нужно провести до пятницы.",
+  "Нашла: в карточке клиента стояла ставка 0 %.",
+  "Исправили ставку, выставляю счёт заново.",
+  "Новый счёт № 4830 отправлен на почту бухгалтерии.",
+  "Получили, всё верно. Оплатим сегодня.",
+  "Отлично! Закрывающие документы пришлём после оплаты.",
+  "Оплата прошла, платёжка во вложении.",
+  "Вижу поступление, спасибо. Акт отправим завтра.",
+  "Подскажите, можно ли подключить ЭДО?",
+  "Да, пришлите идентификатор в Диадоке.",
+].map((text, index) => ({ id: index + 1, author: index % 2 === 0 ? "Клиент" : "Поддержка", text }));
+
+const PAGE = 4;
+
+export default function ScrollContainerChatExample() {
+  // The newest messages first; older pages arrive when the reader scrolls up.
+  const [shown, setShown] = React.useState(PAGE);
+  const [loading, setLoading] = React.useState(false);
+  const [sent, setSent] = React.useState<Message[]>([]);
+  const [draft, setDraft] = React.useState("");
+  const messages = [...HISTORY.slice(-shown), ...sent];
+
+  const loadOlder = () => {
+    if (shown >= HISTORY.length) return;
+    setLoading(true);
+    // The promise keeps the region `aria-busy` and stops repeat calls until it settles.
+    return new Promise<void>((resolve) => {
+      window.setTimeout(() => {
+        setShown((count) => Math.min(count + PAGE, HISTORY.length));
+        setLoading(false);
+        resolve();
+      }, 800);
+    });
+  };
+
+  const send = (event: React.FormEvent) => {
+    event.preventDefault();
+    const text = draft.trim();
+    if (!text) return;
+    setSent((list) => [
+      ...list,
+      { id: HISTORY.length + list.length + 1, author: "Поддержка", text },
+    ]);
+    setDraft("");
+  };
+
+  return (
+    <Card.Root className={styles.chat}>
+      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+        ООО «Гранит» · счёт № 4821
+      </Typography>
+      <ScrollContainer
+        anchor="end"
+        onReachStart={loadOlder}
+        tabIndex={0}
+        aria-label="Сообщения"
+        className={styles.messages}
+      >
+        {loading ? <Skeleton lines={2} className={styles.older} /> : null}
+        <ul className={styles.list}>
+          {messages.map((message) => (
+            <li key={message.id}>
+              <Typography as="span" variant="caption" tone="muted">
+                {message.author}
+              </Typography>
+              <Typography variant="body-m">{message.text}</Typography>
+            </li>
+          ))}
+        </ul>
+      </ScrollContainer>
+      <form className={styles.composer} onSubmit={send}>
+        <Input.Root className={styles.composerField}>
+          <Input.Wrapper>
+            <Input.Field
+              aria-label="Сообщение"
+              placeholder="Ответить клиенту"
+              value={draft}
+              onValueChange={setDraft}
+            />
+          </Input.Wrapper>
+        </Input.Root>
+        <Button.Root type="submit" aria-label="Отправить">
+          <Button.Icon>
+            <Icon name="action.send" />
+          </Button.Icon>
+        </Button.Root>
+      </form>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,43 @@
+/** Hidden edges fade over any background, take a soft shadow on a filled surface, or stay plain — `edges`. */
+import { Card, ScrollContainer, type ScrollContainerEdges, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  "Заказ № 1040 оплачен",
+  "Счёт № 318 выставлен",
+  "Заказ № 1041 передан в доставку",
+  "Возврат по заказу № 1032 одобрен",
+  "Заказ № 1042 оплачен",
+  "Акт № 77 подписан",
+  "Заказ № 1043 отменён клиентом",
+  "Счёт № 319 оплачен",
+  "Заказ № 1044 собран на складе",
+  "Заказ № 1045 оплачен",
+];
+const EDGES: ScrollContainerEdges[] = ["fade", "shadow", "none"];
+
+export default function ScrollContainerEdgesExample() {
+  return (
+    <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>
+          <ScrollContainer edges={edges}>
+            <ul className={styles.list}>
+              {EVENTS.map((event) => (
+                <li key={event}>
+                  <Typography as="span" variant="body-m" tone="secondary">
+                    {event}
+                  </Typography>
+                </li>
+              ))}
+            </ul>
+          </ScrollContainer>
+        </Card.Root>
+      ))}
+    </div>
+  );
+}

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

@@ -39,6 +39,35 @@
   border-bottom: 0;
 }
 
+/* chat.tsx: title, the scrolling messages and the composer in a fixed-height card. */
+.chat {
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  height: calc(var(--prime-space-24) * 3.5);
+}
+
+.messages {
+  padding-top: var(--prime-space-2);
+}
+
+/* Older messages loading: lines in the messages' 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);
@@ -64,3 +93,47 @@
   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. */
+.tiles {
+  display: flex;
+  gap: var(--prime-space-3);
+  width: max-content;
+  margin: 0;
+  padding: var(--prime-space-1);
+  list-style: none;
+}
+
+.tile {
+  inline-size: calc(var(--prime-space-24) * 2);
+  scroll-snap-align: start;
+}
+
+/* auto-scroll.tsx: draggable task rows. */
+.sortable {
+  display: flex;
+  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;
+}