prime-ui-kit 0.9.0 → 0.9.1

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

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

package/src/components/scroll-container/examples/edge-fade.tsx

@@ -0,0 +1,53 @@
+/** Edges fade where more content is hidden; the horizontal strip also hides its scrollbar — `fade`, `scrollbar`. */
+import { Badge, Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  "Заказ № 1040 оплачен",
+  "Счёт № 318 выставлен",
+  "Заказ № 1041 передан в доставку",
+  "Возврат по заказу № 1032 одобрен",
+  "Заказ № 1042 оплачен",
+  "Акт № 77 подписан",
+  "Заказ № 1043 отменён клиентом",
+  "Счёт № 319 оплачен",
+  "Заказ № 1044 собран на складе",
+  "Заказ № 1045 оплачен",
+];
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+
+export default function ScrollContainerEdgeFadeExample() {
+  return (
+    <div className={styles.layout}>
+      <Card.Root role="region" className={styles.card} aria-label="Лента событий">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          Лента событий
+        </Typography>
+        <ScrollContainer fade>
+          <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>
+      <Card.Root role="region" className={styles.card} aria-label="Фильтры">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          Фильтры
+        </Typography>
+        <ScrollContainer axis="horizontal" fade scrollbar="hidden">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag}>{tag}</Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+    </div>
+  );
+}

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

@@ -1,4 +1,4 @@
-/* Layout for the ScrollContainer examples: layout and card surface only, text goes through Typography. */
+/* Layout of the ScrollContainer scenarios: a fixed-height card that owns the scroll region. */
 
 .layout {
   display: grid;
@@ -7,14 +7,14 @@
   width: 100%;
 }
 
+/* The Card's size: a fixed height, so the region inside scrolls. */
 .card {
-  display: flex;
-  flex-direction: column;
+  width: min(100%, calc(var(--prime-space-24) * 4));
   height: calc(var(--prime-space-24) * 2.5);
-  overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
+}
+
+.layout > .card {
+  width: auto;
 }
 
 .cardTitle {

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

@@ -0,0 +1,27 @@
+/** At the end of the list the scroll passes on to the page instead of stopping — `overscrollBehavior`. */
+import { Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const HOURS = Array.from({ length: 12 }, (_, index) => `${String(9 + index).padStart(2, "0")}:00`);
+
+export default function ScrollContainerOverscrollExample() {
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Журнал">
+      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+        Журнал выгрузок
+      </Typography>
+      <ScrollContainer overscrollBehavior="auto" tabIndex={0} aria-label="Журнал выгрузок">
+        <ul className={styles.list}>
+          {HOURS.map((hour) => (
+            <li key={hour}>
+              <Typography as="span" variant="body-m" tone="secondary">
+                {hour} — отчёт выгружен
+              </Typography>
+            </li>
+          ))}
+        </ul>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,27 @@
+/** A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar. */
+import { Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = Array.from({ length: 16 }, (_, index) => `Заказ № ${1040 + index} оплачен`);
+
+export default function ScrollContainerOverviewExample() {
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Лента событий">
+      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+        Лента событий
+      </Typography>
+      <ScrollContainer>
+        <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>
+  );
+}

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

@@ -0,0 +1,54 @@
+/** A strip that scrolls sideways and a wide schedule that scrolls both ways — `axis`. */
+import { Badge, Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+const HOURS = Array.from({ length: 12 }, (_, index) => `${String(9 + index).padStart(2, "0")}:00`);
+const ROOMS = Array.from({ length: 16 }, (_, index) => `Зал ${index + 1}`);
+
+export default function ScrollContainerVariantsExample() {
+  return (
+    <div className={styles.layout}>
+      <Card.Root role="region" className={styles.card} aria-label="Фильтры">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          horizontal
+        </Typography>
+        <ScrollContainer axis="horizontal">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag}>{tag}</Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+      <Card.Root role="region" className={styles.card} aria-label="Расписание залов">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          both
+        </Typography>
+        <ScrollContainer
+          axis="both"
+          tabIndex={0}
+          aria-label="Сетка расписания"
+          className={styles.canvas}
+        >
+          <div className={styles.grid}>
+            {ROOMS.flatMap((room) =>
+              HOURS.map((hour) => (
+                <Typography
+                  key={`${room}-${hour}`}
+                  as="div"
+                  variant="caption"
+                  tone="secondary"
+                  className={styles.cell}
+                >
+                  {room} · {hour}
+                </Typography>
+              )),
+            )}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/segmented-control/COMPONENT.md

@@ -1,20 +1,21 @@
 # SegmentedControl
 
 **Category:** selection
+**Kind:** control
 
 > A switch between 2–5 mutually exclusive options or modes that takes effect immediately.
 
 ## When to use
-- Choosing one value or view mode with an instant effect: report period, list/board/calendar view, theme.
+- Choosing one value or view mode with an instant effect: report period, list / board / calendar view, theme.
 - A compact one-of-many choice inside a toolbar, next to inputs and buttons of the same size.
 - A status picker where each option has its own palette hue (`color` on the item).
 - A status overview where each option carries a metric (two-line segments with `Count` and `Description`).
 
 ## When not to use
-- Switching between panels of content (navigation) → use [Tabs](../tabs/COMPONENT.md) instead.
-- One choice with descriptions in a form, or more than 5 options → use [Radio](../radio/COMPONENT.md) or [Select](../select/COMPONENT.md) instead.
-- A single on/off setting → use [Switch](../switch/COMPONENT.md) instead.
-- Several actions in a row (not a selection) → use [ButtonGroup](../button-group/COMPONENT.md) instead.
+- Switching between panels of content (navigation) → use [Tabs](../tabs/COMPONENT.md).
+- One choice with descriptions in a form, or more than 5 options → use [Radio](../radio/COMPONENT.md) or [Select](../select/COMPONENT.md).
+- A single on/off setting → use [Switch](../switch/COMPONENT.md).
+- Several actions in a row (not a selection) → use [ButtonGroup](../button-group/COMPONENT.md).
 
 ## Import
 ```tsx
@@ -23,102 +24,95 @@ import { SegmentedControl } from "prime-ui-kit";
 
 ## Anatomy
 ```
-SegmentedControl.Root                 role="radiogroup"; track + sliding thumb, keyboard handling
+SegmentedControl.Root                 role="radiogroup"; track + sliding thumb, scrolling row, keyboard
 └─ SegmentedControl.Item              role="radio" button, one option
    ├─ SegmentedControl.Icon           icon slot (optional; icon-only → square segment)
    ├─ SegmentedControl.Label          title, truncates (optional; plain text is wrapped automatically)
-   ├─ SegmentedControl.Count          counter badge after the label (optional)
+   ├─ SegmentedControl.Count          counter Badge after the label (optional)
    └─ SegmentedControl.Description    second line; makes the segment two-line (optional)
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### SegmentedControl.Root
+`ref` → `HTMLDivElement`. `<div role="radiogroup">`: the track with the sliding thumb, keyboard handling and a horizontally scrolling `ScrollContainer` row.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | — | Controlled selected value; use with `onValueChange`. |
-| `defaultValue` | `string` | `""` | Initial value in uncontrolled mode; `""` = nothing selected. |
-| `onValueChange` | `(value: string) => void` | — | Called when the selection changes (click or keyboard). |
+| `value` | `string` | — | Selected value (controlled). |
+| `defaultValue` | `string` | `""` | Initial value (uncontrolled); `""` — nothing selected. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new value on click or arrow keys. |
 | `disabled` | `boolean` | `false` | Disables the whole group. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size tier; outer height equals the control height of the tier. |
-| `fullWidth` | `boolean` | `false` | Stretch to the container; single-line segments share the width equally and truncate. |
-| `aria-label` | `string` | — | Accessible name of the radiogroup. |
-| `aria-labelledby` | `string` | — | Id of the element that names the group. |
-| `children` | `ReactNode` | — (required) | `SegmentedControl.Item` elements (may be wrapped, e.g. in `Tooltip.Trigger`). |
-| `className` | `string` | — | Class on the root `div`. |
-
-No other native props, no ref forwarding.
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier; the outer height equals the control height 28 · 32 · 36 · 40 · 48. Without it the tier of its host (a toolbar, a panel with a size), else `m`. |
+| `fullWidth` | `boolean` | `false` | Fills the container; single-line segments share the width equally and truncate. |
+| `children` | `ReactNode` | — | `SegmentedControl.Item`s (may be wrapped, e.g. in `Tooltip.Trigger`). |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange">` | — | `aria-label` / `aria-labelledby` (name the group), `className` and the other div attributes. |
 
 ### SegmentedControl.Item
+`ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped to truncate.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — (required) | Option value compared with the root value. |
-| `disabled` | `boolean` | `false` | Disables this option; skipped by arrow keys. |
-| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | — | Palette hue: a dot before the content; when selected the thumb takes a soft fill of the hue with a ring of it. |
-| `children` | `ReactNode` | — (required) | Text, `Icon`, `Label`, `Count`, `Description`. |
-| `className` | `string` | — | Class on the `<button>`. |
-
-+ native `<button>` props except `value`, `children`, `type`, `role` (`aria-label`, `onClick`, …; `onClick` runs first and can `preventDefault()` the selection).
-Ref: `forwardRef` → `HTMLButtonElement`.
+| `disabled` | `boolean` | `false` | Disables this option; arrow keys skip it. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | — | Palette hue: a dot before the content; while selected the thumb takes a soft fill of the hue with a ring of it. |
+| `children` | `ReactNode` | — (required) | Text, `Icon`, `Label`, `Count`, `Description`. Only an icon → square segment; give it `aria-label`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "type" \| "role">` | — | `aria-label`, `onClick` (runs first and can `preventDefault()` the selection), `className` and the other button attributes. |
 
 ### SegmentedControl.Icon
+`ref` → `HTMLSpanElement`. Decorative icon (`aria-hidden`) sized to the tier.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | The icon; sized to the tier icon size, `aria-hidden`. |
-| `className` | `string` | — | Class on the `<span>`. |
-
-+ native `<span>` props except `children`.
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="theme.light" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Label
+`ref` → `HTMLSpanElement`. Segment title; truncates with an ellipsis. Plain text is wrapped automatically.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Segment title; truncates with an ellipsis. |
-| `className` | `string` | — | Class on the `<span>`. |
-
-+ native `<span>` props except `children`.
+| `children` | `ReactNode` | — (required) | Title text. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Count
+`ref` → `HTMLSpanElement`. Counter `Badge` after the label, one tier below the control, tabular numbers.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Badge hue. |
-| `children` | `ReactNode` | — (required) | The number (tabular nums). |
-| `className` | `string` | — | Class on the badge. |
-
-Renders a soft `Badge` one tier below the control (`m` → `s`). No other props.
+| `children` | `ReactNode` | — (required) | The number. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Description
+`ref` → `HTMLSpanElement`. Muted second line; makes the segment two-line and becomes its `aria-describedby`.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Muted second line; wrap the key value in `<strong>` to emphasize it. |
-| `className` | `string` | — | Class on the `<span>`. |
-
-+ native `<span>` props except `children`.
+| `children` | `ReactNode` | — (required) | Second-line text; wrap a key value in `<strong>`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ## Variants
-No `variant`/`tone`. Axes: `size` (Root), `fullWidth` (Root), `color` (Item, Count), structural content (icon-only, two-line).
+No `variant` / `tone`. Axes: `size` and `fullWidth` (Root), `color` (Item, Count), structural content (icon-only, two-line).
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 28px track, 4px padding, track radius 8, 12/16 text | dense table toolbars next to `xs` controls | |
+| `xs` | 28px track, radius 8, 12/16 text | dense table toolbars next to `xs` controls | |
 | `s` | 32px track, radius 10, 13/20 text | compact toolbars and filters | |
 | `m` | 36px track, radius 12, 14/20 text | default toolbars and page headers | yes |
 | `l` | 40px track, radius 12, 16/24 text | spacious headers next to `l` controls | |
 | `xl` | 48px track, radius 16, 16/24 text | touch-first screens, hero filters | |
 
-Track is `fill-muted` with a faint 1px ring; the selected segment is a floating thumb (`control-selected`, faint ring, `shadow-raised`); segment radius = track radius − 4px.
-
-### fullWidth
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `false` | group as wide as its segments; in a narrow container it scrolls horizontally with edge fades | toolbars, inline filters | yes |
-| `true` | group fills the container; single-line segments are equal and truncate, two-line segments grow from their content | modals, mobile panels, overview strips | |
+Track is `fill-muted` with a faint 1px ring; the selected segment is a floating thumb (`control-selected`, faint ring, `shadow-raised`); segment radius = track radius − padding. A single-line group is as tall as Button, Input, Select and Datepicker trigger of the same size.
 
 ### color (Item)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | none | no dot; selected thumb is neutral | ordinary modes and periods | yes |
-| `gray` · `blue` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | dot of the hue before the content; selected thumb gets the hue's soft fill and a ring of the hue text | statuses where each value has a meaning (ok/attention/broken) | |
+| `gray` · `blue` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | dot of the hue before the content; selected thumb gets the hue's soft fill and a ring of the hue text | statuses where each value has a meaning | |
 
 ### color (Count)
 | Value | Looks like | Use when | Default |
@@ -126,76 +120,67 @@ Track is `fill-muted` with a faint 1px ring; the selected segment is a floating
 | `gray` | neutral soft badge (text wash so it reads on track and thumb) | plain counters | yes |
 | other palette hues | soft badge of the hue | the count has a status meaning | |
 
-### Structural content
+### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| text / icon + text | single-line segment, tier height minus padding | most cases | yes |
-| icon only | square segment (`data-icon-only`) | toolbar view toggles; add `aria-label` and a Tooltip | |
-| two-line (`Description`) | label (+count) on line 1, muted description on line 2; track grows to content (`data-two-line`) | overview strips with metrics | |
-
-**Combinations**
-- Item `color` + Count `color` of the same hue → redundant; use one.
-- Item `color` mixing coloured and plain items in one group → avoid; colour all or none.
-- Icon-only without `aria-label` → forbidden (no accessible name).
-- `fullWidth` with many long single-line labels → labels truncate; prefer content width or two-line segments.
-
-**Sizes** — single-line group height = `--prime-control-<tier>-height` (28 · 32 · 36 · 40 · 48), so it lines up with Button, Input, Select and Datepicker trigger of the same size in one row.
+| `fullWidth` | fills the container; single-line segments are equal and truncate, two-line segments grow from their content | modals, mobile panels, overview strips | off |
+| `disabled` | every segment disabled, thumb `fill-muted-hover` without shadow | the choice is temporarily unavailable | off |
+| icon-only (only `SegmentedControl.Icon`) | square segment (`data-icon-only`) | toolbar view toggles; needs `aria-label` | — |
 
-**Hierarchy** — one segmented control per decision; in a toolbar keep all controls at one size (see [toolbar.tsx](examples/toolbar.tsx)).
+Colour all items or none; do not give an item and its Count the same hue; prefer content width or two-line segments over `fullWidth` with many long labels.
 
 ## States
-| State | Driven by | DOM | Looks like |
-|---|---|---|---|
-| selected | root `value` = item `value` | `aria-checked="true"`, `data-state="checked"` | thumb under the segment, text `text-primary` |
-| unselected | — | `aria-checked="false"`, `data-state="unchecked"` | text `text-secondary`; hover → `text-primary` (no fill) |
-| no selection | `value` / `defaultValue` = `""` | thumb hidden | first enabled segment takes Tab focus |
-| item disabled | item `disabled` | `data-disabled="true"`, native `disabled` | text `text-disabled`, skipped by arrows |
-| group disabled | root `disabled` | root `data-disabled="true"`, `aria-disabled` | all segments disabled, thumb `fill-muted-hover` without shadow |
-| focus-visible | keyboard | — | focus ring on the segment |
+| State | Driven by | DOM |
+|---|---|---|
+| selected | root `value` = item `value` | `aria-checked="true"`, `data-state="checked"`; thumb under the segment, `text-primary` |
+| unselected | — | `aria-checked="false"`, `data-state="unchecked"`; `text-secondary`, hover → `text-primary` (no fill) |
+| no selection | `value` / `defaultValue` = `""` | thumb hidden; the first enabled segment takes Tab focus |
+| item disabled | item `disabled` | `data-disabled="true"`, native `disabled`, `text-disabled`, skipped by arrows |
+| group disabled | root `disabled` | root `data-disabled="true"`, `aria-disabled`; every segment disabled |
+| focus-visible | keyboard | focus ring inside the segment |
+| overflow | row wider than the container | root `data-overflow-start` / `data-overflow-end`: edge fades in the track color |
 
-Root DOM: `data-size`, `data-disabled`, `data-full-width`; scroller `data-overflow-start` / `data-overflow-end` (edge fades). Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb slides only after a user change (`data-animate`), and not under `prefers-reduced-motion`.
-Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue`.
+Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb glides (`emphasized` + `base`, `data-animate`) only into a user's choice (click, arrows); a value set from outside and layout changes snap it; it stays still under `prefers-reduced-motion`. It sits inside the segment track, which clips it, so moving the selection never changes the row's scroll area; when the row scrolls, the chosen segment is scrolled into view.
 
 ## Layout & spacing
 - Width is content-based by default; segments never wrap. In a narrow container the row scrolls horizontally with fading edges.
-- In a toolbar: gap `--prime-space-3` between controls; wrap the toolbar (`flex-wrap`) on narrow screens.
+- In a toolbar: gap `--prime-space-3` between controls; keep every control at one size.
 - Caption under a group: gap `--prime-space-2`.
 - `fullWidth` inside modals and mobile sheets.
 
 ## Accessibility
-- Root `role="radiogroup"` (always name it with `aria-label` / `aria-labelledby`), `aria-disabled` when disabled.
-- Items are `<button role="radio" aria-checked>` with roving `tabIndex`: Tab focuses the selected item (or the first enabled one).
-- Keyboard: ←/↑ previous, →/↓ next (wraps, skips disabled), Home / End first / last; moving focus also selects and scrolls the item into view.
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowRight` · `ArrowDown` | Next option, wrapping and skipping disabled ones; focus and selection move together. |
+| `ArrowLeft` · `ArrowUp` | Previous option. |
+| `Home` · `End` | First and last enabled option. |
+| `Tab` | Enters the group on the selected option (or the first enabled one) and leaves it. |
+
+### ARIA
+- Root `role="radiogroup"` — always name it with `aria-label` / `aria-labelledby`; `aria-disabled` when disabled.
+- Items are `<button role="radio" aria-checked>` with roving `tabIndex`.
 - Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description.
-- Icons are `aria-hidden`; icon-only items need `aria-label`.
-- No `labels` keys.
+- Icons are `aria-hidden`; icon-only items need `aria-label` (and a Tooltip for sighted users).
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | All tiers in a row with Input and Button | Aligning with other controls |
-| [item-content.tsx](examples/item-content.tsx) | Icon + text, icon-only with Tooltip, Count | Choosing segment content |
-| [two-line.tsx](examples/two-line.tsx) | `fullWidth` two-line segments with Label, Count (colours), Description | Status overview with metrics |
-| [full-width.tsx](examples/full-width.tsx) | Content width vs `fullWidth` vs scrolling in a narrow container | Deciding how the group fills its container |
-| [surfaces.tsx](examples/surfaces.tsx) | Canvas, card, nested card, modal | Checking contrast on any host |
-| [colors.tsx](examples/colors.tsx) | Item `color` with tinted thumb | Status picker |
-| [states.tsx](examples/states.tsx) | Selected, no selection, disabled item, disabled group | Reference for every state |
-| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` | Selection drives other content |
-| [toolbar.tsx](examples/toolbar.tsx) | Search, view and period switches, export button at size `m` | Toolbars |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { SegmentedControl } from "prime-ui-kit";
+No `labels`.
 
-export function PeriodSwitch() {
-  return (
-    <SegmentedControl.Root defaultValue="week" aria-label="Период">
-      <SegmentedControl.Item value="day">День</SegmentedControl.Item>
-      <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
-      <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
-    </SegmentedControl.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | One value out of a few, with a sliding thumb on the chosen segment — `defaultValue`, `aria-label`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; the outer height equals the control height of the same tier — `size`. |
+| [states.tsx](examples/states.tsx) | No selection yet, a disabled segment and a disabled group next to the default — `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments named for screen readers — `SegmentedControl.Icon`, `aria-label`. |
+| [colors.tsx](examples/colors.tsx) | A status per option: a dot of its hue before the label and a tinted thumb when chosen — `color`. |
+| [full-width.tsx](examples/full-width.tsx) | The group fills its column; segments share the width equally and truncate long labels — `fullWidth`. |
+| [scroll.tsx](examples/scroll.tsx) | Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view. |
+| [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a metric on the second — `SegmentedControl.Label`, `SegmentedControl.Count`, `SegmentedControl.Description`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the choice and updates other content from it — `value`, `onValueChange`. |
 
 ## Mistakes
 - Using it as tabs that show different panels → use `Tabs`.
@@ -206,4 +191,5 @@ export function PeriodSwitch() {
 - Expecting segments to wrap on narrow screens → they scroll; use `fullWidth` or fewer options.
 
 ## Related
-[Tabs](../tabs/COMPONENT.md) · [Radio](../radio/COMPONENT.md) · [Switch](../switch/COMPONENT.md) · [Badge](../badge/COMPONENT.md) · [Tooltip](../tooltip/COMPONENT.md)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md)
+- **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)