prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/components/scroll-container/examples/examples.module.css

@@ -0,0 +1,139 @@
+/* Layout of the ScrollContainer scenarios: a fixed-height card that owns the scroll region. */
+
+.layout {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--prime-space-24) * 2.5), 1fr));
+  gap: var(--prime-space-4);
+  width: 100%;
+}
+
+/* The Card's size: a fixed height, so the region inside scrolls. */
+.card {
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  height: calc(var(--prime-space-24) * 2.5);
+}
+
+.layout > .card {
+  width: auto;
+}
+
+.cardTitle {
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  padding: 0 var(--prime-space-4) var(--prime-space-3);
+  list-style: none;
+}
+
+.list li {
+  padding-block: var(--prime-space-2);
+  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+/* Dividers only between items. */
+.list li:last-child {
+  border-bottom: 0;
+}
+
+/* chat.tsx: title, the scrolling messages and the composer in a fixed-height card. */
+.chat {
+  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);
+  width: max-content;
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+/* Two-axis scroller: the side padding lives on the scrolling element itself (foundation §7). */
+.canvas {
+  padding: 0 var(--prime-space-4) var(--prime-space-3);
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(12, var(--prime-space-24));
+  gap: var(--prime-space-1);
+  width: max-content;
+}
+
+.cell {
+  padding: var(--prime-space-2);
+  border-radius: var(--prime-radius-s);
+  background: var(--prime-color-fill-subtle);
+  font-variant-numeric: tabular-nums;
+}
+
+/* lock.tsx: the title and the review button in one row above the queue. */
+.cardHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+/* snap.tsx: a row of fixed-width cards; the padding keeps the edge cards' rings unclipped. */
+.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;
+}

package/dist/skill/reference/components/scroll-container/examples/lock.tsx

@@ -0,0 +1,49 @@
+/** While an order is opened for review, the queue behind it holds still: no wheel, touch, key or drag moves it — `lock`. */
+import { Button, Card, ScrollContainer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const ORDERS = [
+  "Заказ № 1040 · ООО «Северный склад»",
+  "Заказ № 1041 · АО «Тепломонтаж»",
+  "Заказ № 1042 · ИП Кравцова",
+  "Заказ № 1043 · ООО «Логистик Плюс»",
+  "Заказ № 1044 · ООО «Альфа Ритейл»",
+  "Заказ № 1045 · АО «ПромСнаб»",
+  "Заказ № 1046 · ООО «Городские аптеки»",
+  "Заказ № 1047 · ООО «Вектор»",
+];
+
+export default function ScrollContainerLockExample() {
+  const [reviewing, setReviewing] = React.useState(false);
+
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Очередь заказов">
+      <div className={styles.cardHeader}>
+        <Typography as="h3" variant="title-s">
+          Очередь заказов
+        </Typography>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          pressed={reviewing}
+          onClick={() => setReviewing((current) => !current)}
+        >
+          {reviewing ? "Закрыть проверку" : "Проверить заказ"}
+        </Button.Root>
+      </div>
+      <ScrollContainer lock={reviewing}>
+        <ul className={styles.list}>
+          {ORDERS.map((order) => (
+            <li key={order}>
+              <Typography as="span" variant="body-m">
+                {order}
+              </Typography>
+            </li>
+          ))}
+        </ul>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/components/scroll-container/examples/scrollbar.tsx

@@ -0,0 +1,52 @@
+/** 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`. */
+import { Badge, Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const CLIENTS = [
+  "ООО «Северный склад»",
+  "АО «Тепломонтаж»",
+  "ИП Кравцова",
+  "ООО «Логистик Плюс»",
+  "ООО «Альфа Ритейл»",
+  "АО «ПромСнаб»",
+  "ООО «Городские аптеки»",
+  "ООО «Вектор»",
+  "ИП Сафонов",
+];
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+
+export default function ScrollContainerScrollbarExample() {
+  return (
+    <div className={styles.layout}>
+      <Card.Root role="region" className={styles.card} aria-label="Клиенты">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          thin
+        </Typography>
+        <ScrollContainer>
+          <ul className={styles.list}>
+            {CLIENTS.map((client) => (
+              <li key={client}>
+                <Typography as="span" variant="body-m">
+                  {client}
+                </Typography>
+              </li>
+            ))}
+          </ul>
+        </ScrollContainer>
+      </Card.Root>
+      <Card.Root role="region" className={styles.card} aria-label="Фильтры заказов">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          hidden
+        </Typography>
+        <ScrollContainer axis="horizontal" scrollbar="hidden">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag}>{tag}</Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/scroll-container/examples/snap.tsx

@@ -0,0 +1,36 @@
+/** 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`. */
+import { Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WAREHOUSES = [
+  { id: "msk", city: "Москва", stock: "12 480 позиций" },
+  { id: "spb", city: "Санкт-Петербург", stock: "8 215 позиций" },
+  { id: "kzn", city: "Казань", stock: "4 030 позиций" },
+  { id: "ekb", city: "Екатеринбург", stock: "5 772 позиции" },
+  { id: "nsk", city: "Новосибирск", stock: "3 118 позиций" },
+  { id: "krd", city: "Краснодар", stock: "2 904 позиции" },
+];
+
+export default function ScrollContainerSnapExample() {
+  return (
+    <ScrollContainer axis="horizontal" snap scrollbar="hidden" aria-label="Склады">
+      <ul className={styles.tiles}>
+        {WAREHOUSES.map((warehouse) => (
+          <li key={warehouse.id} className={styles.tile}>
+            <Card.Root>
+              <Card.Body>
+                <Typography as="h3" variant="title-s">
+                  {warehouse.city}
+                </Typography>
+                <Typography as="p" variant="caption" tone="muted">
+                  {warehouse.stock}
+                </Typography>
+              </Card.Body>
+            </Card.Root>
+          </li>
+        ))}
+      </ul>
+    </ScrollContainer>
+  );
+}

package/dist/skill/reference/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/dist/skill/reference/components/segmented-control/COMPONENT.md

@@ -0,0 +1,214 @@
+# 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.
+- 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).
+- 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
+import { SegmentedControl } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+SegmentedControl.Root                 field frame: label row · track · support row (hint | error)
+└─ (track)                            role="radiogroup"; sliding thumb, scrolling row, keyboard
+   └─ SegmentedControl.Item           role="radio" button, one option
+      ├─ SegmentedControl.Icon        icon slot (optional; icon-only → square segment)
+      ├─ SegmentedControl.Label       title, one line (optional; plain text is wrapped automatically)
+      ├─ SegmentedControl.Count       counter Badge after the label (optional)
+      └─ SegmentedControl.Description second line; makes the segment two-line (optional)
+```
+The root is a field root: `className`, `ref` and the native attributes land on the frame, which hugs the track unless `fullWidth`; `id`, `onKeyDown` and the `aria-label*` / `aria-describedby` names land on the radiogroup. Without `label`, `hint` and `error` the frame shows only the track.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### SegmentedControl.Root
+`ref` → `HTMLDivElement` (the field frame). The field: label · `<div role="radiogroup">` track with the sliding thumb, keyboard handling and a horizontally scrolling `ScrollContainer` row · support row. The frame hugs the track unless `fullWidth`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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"` | `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 tend to equal widths but never get narrower than their label — when they do not fit, the row scrolls. |
+| `label` | `ReactNode` | — | Heading above the control; names the `radiogroup` (`aria-labelledby`). Without it give the root an `aria-label`. |
+| `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `radiogroup`. |
+| `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid` and `data-invalid` on the `radiogroup`; the control shakes once when an error arrives. |
+| `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |
+| `id` | `string` | — | Id of the `radiogroup` element (generated when omitted); hint id is `<id>-hint`, error id `<id>-error`. |
+| `labels` | `Partial<SegmentedControlLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | `SegmentedControl.Item`s (may be wrapped, e.g. in `Tooltip.Trigger`). |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `aria-label` / `aria-labelledby` / `aria-describedby` and `onKeyDown` go to the radiogroup (a prevented key skips the kit's handling); `className`, `data-*` and the other attributes to the field frame `<div>`. |
+
+### SegmentedControl.Item
+`ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped in a `SegmentedControl.Label`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Option value compared with the root value. |
+| `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, e.g. `<Icon name="theme.light" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### SegmentedControl.Label
+`ref` → `HTMLSpanElement`. Segment title on one line; never truncated. Plain text is wrapped automatically.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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. |
+| `…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) | 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` and `fullWidth` (Root), `color` (Item, Count), structural content (icon-only, two-line).
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 − 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 | |
+
+### color (Count)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | fills the container; single-line segments tend to equal widths, a long label keeps its own width and the row scrolls when they do not fit; 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` | — |
+
+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 |
+|---|---|---|
+| 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` | track `data-disabled="true"`, `aria-disabled`; every segment disabled; label and hint dimmed |
+| invalid | `invalid` or non-empty `error` | track `data-invalid="true"` + `aria-invalid="true"`, inset danger ring on the track; the error replaces the hint; the track shakes once when an error arrives |
+| required | `required` | red `*` after the label, `aria-required="true"` on the radiogroup |
+| 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 |
+
+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 selected segment is kept in view on mount and on every value change: only the row scrolls, never the page, and the scroll glides only after a user's choice.
+
+## Layout & spacing
+- In a form it is a field: label → track `label-gap`, track → support row `hint-gap`, field → field `--prime-space-5` like every field.
+- 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; keep every control at one size.
+- Caption under a group: gap `--prime-space-2`.
+- `fullWidth` inside modals and mobile sheets. Single-line segments are `flex: 1 1 0` with `min-width: max-content`: short labels share the spare width equally, a long label keeps its own width, nothing truncates; when the labels do not fit, the row scrolls.
+
+## Accessibility
+
+### 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
+- The track is `role="radiogroup"`, named by `label` (`aria-labelledby`); without a label give the root `aria-label`. `aria-disabled` when disabled.
+- Hint and error are linked through `aria-describedby`; an error sets `aria-invalid="true"`, `required` sets `aria-required="true"`.
+- 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` (and a Tooltip for sighted users).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+
+## 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 tend to equal widths and a long label keeps its own — `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`. |
+| [in-form.tsx](examples/in-form.tsx) | An expense form: the choice is a labelled field with a hint, checked on submit, its error leaves as soon as a segment is chosen — `label`, `hint`, `required`, `error`. |
+
+## Mistakes
+- Using it as tabs that show different panels → use `Tabs`.
+- No `label` and no `aria-label` → the radiogroup has no name.
+- A `Label` + `Hint` pair wired by hand with `aria-labelledby` in a form → `label`, `hint`, `error` on the root.
+- Icon-only item without `aria-label` → add `aria-label` and wrap in `Tooltip`.
+- `variant="…"` or `tone="…"` on the root → there is none; use `color` on items for hue.
+- Different `size` than neighbouring controls in a toolbar → use the same tier so heights match.
+- Expecting segments to wrap on narrow screens → they scroll; use `fullWidth` or fewer options.
+
+## Related
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)

package/dist/skill/reference/components/segmented-control/examples/colors.tsx

@@ -0,0 +1,18 @@
+/** A status per option: a dot of its hue before the label and a tinted thumb when chosen — `color`. */
+import { SegmentedControl } from "prime-ui-kit";
+
+export default function SegmentedControlColorsExample() {
+  return (
+    <SegmentedControl.Root defaultValue="paid" aria-label="Статус счёта">
+      <SegmentedControl.Item value="paid" color="green">
+        Оплачен
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="pending" color="orange">
+        Ожидает
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="overdue" color="red">
+        Просрочен
+      </SegmentedControl.Item>
+    </SegmentedControl.Root>
+  );
+}

package/dist/skill/reference/components/segmented-control/examples/controlled.tsx

@@ -0,0 +1,28 @@
+/** The parent owns the choice and updates other content from it — `value`, `onValueChange`. */
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const REVENUE: Record<string, string> = {
+  day: "Выручка за день: 48 200 ₽",
+  week: "Выручка за неделю: 312 700 ₽",
+  month: "Выручка за месяц: 1 284 000 ₽",
+};
+
+export default function SegmentedControlControlledExample() {
+  const [period, setPeriod] = React.useState("week");
+
+  return (
+    <div className={styles.stack}>
+      <SegmentedControl.Root value={period} onValueChange={setPeriod} aria-label="Период отчёта">
+        <SegmentedControl.Item value="day">День</SegmentedControl.Item>
+        <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+        <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+      </SegmentedControl.Root>
+      <Typography variant="body-m" tone="secondary">
+        {REVENUE[period]}
+      </Typography>
+    </div>
+  );
+}