prime-ui-kit 0.14.0 → 0.16.0

package/src/components/scroll-container/examples/load-more.tsx

@@ -0,0 +1,51 @@
+/** An order log that loads the next page as the reader nears its end, with loading lines in the rows' place — `onReachEnd`. */
+import { Card, ScrollContainer, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const ORDERS = Array.from({ length: 40 }, (_, index) => ({
+  id: 2400 - index,
+  amount: `${(18 + ((index * 7) % 23)) * 1000} ₽`,
+}));
+
+const PAGE = 10;
+
+export default function ScrollContainerLoadMoreExample() {
+  const [shown, setShown] = React.useState(PAGE);
+  const [loading, setLoading] = React.useState(false);
+  const done = shown >= ORDERS.length;
+
+  const loadMore = () => {
+    if (done) 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, ORDERS.length));
+        setLoading(false);
+        resolve();
+      }, 800);
+    });
+  };
+
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Журнал заказов">
+      <Card.Header>
+        <Card.Title>Журнал заказов</Card.Title>
+      </Card.Header>
+      <ScrollContainer onReachEnd={loadMore} tabIndex={0} aria-label="Заказы">
+        <Card.List>
+          {ORDERS.slice(0, shown).map((order) => (
+            <Card.ListItem key={order.id}>
+              <Typography as="span" variant="body-m" tone="secondary">
+                Заказ № {order.id} · {order.amount}
+              </Typography>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+        {loading ? <Skeleton lines={3} className={styles.older} /> : null}
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

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

@@ -20,10 +20,8 @@ export default function ScrollContainerLockExample() {
 
   return (
     <Card.Root role="region" className={styles.card} aria-label="Очередь заказов">
-      <div className={styles.cardHeader}>
-        <Typography as="h3" variant="title-s">
-          Очередь заказов
-        </Typography>
+      <Card.Header>
+        <Card.Title>Очередь заказов</Card.Title>
         <Button.Root
           variant="soft"
           tone="neutral"
@@ -32,17 +30,17 @@ export default function ScrollContainerLockExample() {
         >
           {reviewing ? "Закрыть проверку" : "Проверить заказ"}
         </Button.Root>
-      </div>
+      </Card.Header>
       <ScrollContainer lock={reviewing}>
-        <ul className={styles.list}>
+        <Card.List>
           {ORDERS.map((order) => (
-            <li key={order}>
+            <Card.ListItem key={order}>
               <Typography as="span" variant="body-m">
                 {order}
               </Typography>
-            </li>
+            </Card.ListItem>
           ))}
-        </ul>
+        </Card.List>
       </ScrollContainer>
     </Card.Root>
   );

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

@@ -0,0 +1,97 @@
+/** A live exchange log pinned to its last entry: a new entry keeps it at the end, scrolling up loads older ones without moving what is on screen — `anchor`, `onReachStart`. */
+import { Button, Card, ScrollContainer, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Entry = { id: number; time: string; text: string };
+
+const HISTORY: Entry[] = [
+  "Выгрузка заказов в 1С начата",
+  "Заказ № 1042 выгружен",
+  "Заказ № 1043 выгружен",
+  "Заказ № 1044: нет склада отгрузки, пропущен",
+  "Остатки склада «Москва» обновлены",
+  "Цены прайса «Опт» обновлены",
+  "Счёт № 4830 выгружен",
+  "Счёт № 4831 выгружен",
+  "Платёж по счёту № 4821 получен",
+  "Контрагент ООО «Гранит» сопоставлен",
+  "Акт № 312 выгружен",
+  "Выгрузка завершена: 9 из 10",
+].map((text, index) => ({
+  id: index + 1,
+  time: `09:${String(index * 4).padStart(2, "0")}`,
+  text,
+}));
+
+const ARRIVING = [
+  "Новый заказ № 1045 принят",
+  "Остатки склада «Казань» обновлены",
+  "Счёт № 4832 выгружен",
+];
+
+const PAGE = 4;
+
+export default function ScrollContainerLogExample() {
+  // The newest entries first; older pages arrive when the reader scrolls up.
+  const [shown, setShown] = React.useState(PAGE);
+  const [loading, setLoading] = React.useState(false);
+  const [arrived, setArrived] = React.useState<Entry[]>([]);
+  const entries = [...HISTORY.slice(-shown), ...arrived];
+
+  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 receive = () => {
+    setArrived((list) => [
+      ...list,
+      {
+        id: HISTORY.length + list.length + 1,
+        time: `10:${String(list.length * 3).padStart(2, "0")}`,
+        text: ARRIVING[list.length % ARRIVING.length],
+      },
+    ]);
+  };
+
+  return (
+    <Card.Root className={styles.log}>
+      <Card.Header>
+        <Card.Title>Обмен с 1С</Card.Title>
+        <Button.Root variant="soft" tone="neutral" onClick={receive}>
+          Новое событие
+        </Button.Root>
+      </Card.Header>
+      <ScrollContainer
+        anchor="end"
+        onReachStart={loadOlder}
+        tabIndex={0}
+        role="log"
+        aria-label="Журнал обмена"
+        className={styles.entries}
+      >
+        {loading ? <Skeleton lines={2} className={styles.older} /> : null}
+        <Card.List>
+          {entries.map((entry) => (
+            <Card.ListItem key={entry.id}>
+              <Typography as="span" variant="caption" tone="muted">
+                {entry.time}
+              </Typography>
+              <Typography variant="body-m">{entry.text}</Typography>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

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

@@ -8,19 +8,19 @@ const HOURS = Array.from({ length: 12 }, (_, index) => `${String(9 + index).padS
 export default function ScrollContainerOverscrollExample() {
   return (
     <Card.Root role="region" className={styles.card} aria-label="Журнал">
-      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
-        Журнал выгрузок
-      </Typography>
+      <Card.Header>
+        <Card.Title>Журнал выгрузок</Card.Title>
+      </Card.Header>
       <ScrollContainer overscrollBehavior="auto" tabIndex={0} aria-label="Журнал выгрузок">
-        <ul className={styles.list}>
+        <Card.List>
           {HOURS.map((hour) => (
-            <li key={hour}>
+            <Card.ListItem key={hour}>
               <Typography as="span" variant="body-m" tone="secondary">
                 {hour} — отчёт выгружен
               </Typography>
-            </li>
+            </Card.ListItem>
           ))}
-        </ul>
+        </Card.List>
       </ScrollContainer>
     </Card.Root>
   );

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

@@ -1,4 +1,4 @@
-/** A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar. */
+/** A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar — `ScrollContainer`. */
 import { Card, ScrollContainer, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -8,19 +8,19 @@ const EVENTS = Array.from({ length: 16 }, (_, index) => `Заказ № ${1040 +
 export default function ScrollContainerOverviewExample() {
   return (
     <Card.Root role="region" className={styles.card} aria-label="Лента событий">
-      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
-        Лента событий
-      </Typography>
+      <Card.Header>
+        <Card.Title>Лента событий</Card.Title>
+      </Card.Header>
       <ScrollContainer>
-        <ul className={styles.list}>
+        <Card.List>
           {EVENTS.map((event) => (
-            <li key={event}>
+            <Card.ListItem key={event}>
               <Typography as="span" variant="body-m" tone="secondary">
                 {event}
               </Typography>
-            </li>
+            </Card.ListItem>
           ))}
-        </ul>
+        </Card.List>
       </ScrollContainer>
     </Card.Root>
   );

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

@@ -20,25 +20,31 @@ 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>
+        <Card.Header>
+          <Card.Title>Клиенты</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            thin
+          </Typography>
+        </Card.Header>
         <ScrollContainer>
-          <ul className={styles.list}>
+          <Card.List>
             {CLIENTS.map((client) => (
-              <li key={client}>
+              <Card.ListItem key={client}>
                 <Typography as="span" variant="body-m">
                   {client}
                 </Typography>
-              </li>
+              </Card.ListItem>
             ))}
-          </ul>
+          </Card.List>
         </ScrollContainer>
       </Card.Root>
-      <Card.Root role="region" className={styles.card} aria-label="Фильтры заказов">
-        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
-          hidden
-        </Typography>
+      <Card.Root role="region" className={styles.card} aria-label="Статусы заказов">
+        <Card.Header>
+          <Card.Title>Статусы заказов</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            hidden
+          </Typography>
+        </Card.Header>
         <ScrollContainer axis="horizontal" scrollbar="hidden">
           <div className={styles.strip}>
             {TAGS.map((tag) => (

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** A strip of warehouse cards that always comes to rest on a card's start, scrolled by touch, a trackpad or the mouse wheel — `snap`, `axis`. */
 import { Card, ScrollContainer, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -14,7 +14,7 @@ const WAREHOUSES = [
 
 export default function ScrollContainerSnapExample() {
   return (
-    <ScrollContainer axis="horizontal" snap scrollbar="hidden" aria-label="Склады">
+    <ScrollContainer axis="horizontal" snap="mandatory" scrollbar="hidden" aria-label="Склады">
       <ul className={styles.tiles}>
         {WAREHOUSES.map((warehouse) => (
           <li key={warehouse.id} className={styles.tile}>

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

@@ -10,10 +10,13 @@ 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>
+      <Card.Root role="region" className={styles.card} aria-label="Статусы заказов">
+        <Card.Header>
+          <Card.Title>Статусы заказов</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            horizontal
+          </Typography>
+        </Card.Header>
         <ScrollContainer axis="horizontal">
           <div className={styles.strip}>
             {TAGS.map((tag) => (
@@ -23,9 +26,12 @@ export default function ScrollContainerVariantsExample() {
         </ScrollContainer>
       </Card.Root>
       <Card.Root role="region" className={styles.card} aria-label="Расписание залов">
-        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
-          both
-        </Typography>
+        <Card.Header>
+          <Card.Title>Расписание залов</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            both
+          </Typography>
+        </Card.Header>
         <ScrollContainer
           axis="both"
           tabIndex={0}
@@ -40,6 +46,7 @@ export default function ScrollContainerVariantsExample() {
                   as="div"
                   variant="caption"
                   tone="secondary"
+                  numeric="tabular"
                   className={styles.cell}
                 >
                   {room} · {hour}

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

@@ -25,10 +25,10 @@ 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
+└─ (track)                            role="radiogroup"; sliding thumb, switcher 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.Label       title, one line (optional; plain text becomes the label)
       ├─ SegmentedControl.Count       counter Badge after the label (optional)
       └─ SegmentedControl.Description second line; makes the segment two-line (optional)
 ```
@@ -39,7 +39,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 <!-- 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`.
+`ref` → `HTMLDivElement` (the field frame). The field: label · `<div role="radiogroup">` track with the sliding thumb and the switcher row (titles go before it scrolls, when every segment has an icon) · support row. The frame hugs the track unless `fullWidth`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -47,7 +47,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `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`. |
+| `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`. |
@@ -70,6 +70,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `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`. |
+| `className` | `string` | — | Class on the segment button. |
 | `…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
@@ -78,6 +79,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="theme.light" />`. |
+| `className` | `string` | — | Class on the icon box. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Label
@@ -86,6 +88,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | Title text. |
+| `className` | `string` | — | Class on the label. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Count
@@ -103,6 +106,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | Second-line text; wrap a key value in `<strong>`. |
+| `className` | `string` | — | Class on the description. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ## Variants
@@ -128,7 +132,7 @@ Track is `fill-muted` with a faint 1px ring; the selected segment is a floating
 ### color (Count)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `gray` | neutral soft badge (text wash so it reads on track and thumb) | plain counters | yes |
+| `gray` | neutral soft badge (a wash of the text ink, 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
@@ -150,14 +154,18 @@ Colour all items or none; do not give an item and its Count the same hue; prefer
 | 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 |
+| optional | `optional` | a muted `labels.optional` marker after the label |
+| support row reserved | `reserveSupportRow` | the support row stays rendered while empty, so an error arriving shifts nothing |
 | 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 |
+| collapsed | row wider than the container and every segment has an icon | row `data-collapse="icon"`: titles, counts and descriptions leave the row, segments turn square; a `VisuallyHidden` copy of the title names each segment and a `Tooltip` shows it |
+| overflow | row still 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.
+Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb (the shared selection indicator) 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.
+- Width is content-based by default; the row is a switcher (foundation §9): segments never wrap or truncate. In a narrow container segments with icons drop their titles first, then the row scrolls horizontally with fading edges.
+- Without `size` the control takes the tier of its host (a toolbar, a form), else `m`.
 - On a coarse pointer each segment's hit area grows to the 44 px touch target in height; the track keeps its tier height.
 - In a toolbar: gap `--prime-space-3` between controls; keep every control at one size.
 - Caption under a group: gap `--prime-space-2`.
@@ -166,6 +174,8 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowRight` · `ArrowDown` | Next option, wrapping and skipping disabled ones; focus and selection move together. |
@@ -174,11 +184,13 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 | `Tab` | Enters the group on the selected option (or the first enabled one) and leaves it. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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).
+- Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description; plain text is the label, so every reference resolves.
+- Icons are `aria-hidden`; icon-only items need `aria-label` (and a Tooltip for sighted users). In a row collapsed to icons a `VisuallyHidden` copy of the title names the segment and a `Tooltip` shows it.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -192,14 +204,14 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 |---|---|
 | [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`. |
+| [states.tsx](examples/states.tsx) | No selection yet, an invalid group, a disabled segment and a disabled group next to the default — `invalid`, `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. |
+| [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 — `defaultValue`. |
 | [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`. |
+| [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; an optional choice beside it — `label`, `hint`, `required`, `error`, `optional`. |
 
 ## Mistakes
 - Using it as tabs that show different panels → use `Tabs`.
@@ -211,5 +223,5 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 - 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`)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the row), [Badge](../badge/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md) (the title of a collapsed segment), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md); `internal/selectionIndicator` (the thumb)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)

package/src/components/segmented-control/examples/controlled.tsx

@@ -2,8 +2,6 @@
 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 ₽",
@@ -14,7 +12,7 @@ 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>
@@ -23,6 +21,6 @@ export default function SegmentedControlControlledExample() {
       <Typography variant="body-m" tone="secondary">
         {REVENUE[period]}
       </Typography>
-    </div>
+    </>
   );
 }

package/src/components/segmented-control/examples/examples.module.css

@@ -1,13 +1,5 @@
 /* Layout of the SegmentedControl scenarios: semantic tokens only. */
 
-/* controlled.tsx: the group and the content it drives, start-aligned in one column. */
-.stack {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-start;
-  gap: var(--prime-space-3);
-}
-
 /* in-form.tsx: field → field and fields → action at the form rhythm; controls keep their width. */
 .form {
   display: grid;

package/src/components/segmented-control/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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; an optional choice beside it — `label`, `hint`, `required`, `error`, `optional`. */
 import { Button, Input, SegmentedControl } from "prime-ui-kit";
 import * as React from "react";
 
@@ -36,6 +36,10 @@ export default function SegmentedControlInFormExample() {
         <SegmentedControl.Item value="project">Проекта</SegmentedControl.Item>
         <SegmentedControl.Item value="personal">Личный</SegmentedControl.Item>
       </SegmentedControl.Root>
+      <SegmentedControl.Root label="Возмещение" optional defaultValue="salary">
+        <SegmentedControl.Item value="salary">С зарплатой</SegmentedControl.Item>
+        <SegmentedControl.Item value="card">На карту</SegmentedControl.Item>
+      </SegmentedControl.Root>
       <Button.Root type="submit">Сохранить расход</Button.Root>
     </form>
   );

package/src/components/segmented-control/examples/scroll.tsx

@@ -1,4 +1,4 @@
-/** Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view. */
+/** Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view — `defaultValue`. */
 import { SegmentedControl } from "prime-ui-kit";
 
 export default function SegmentedControlScrollExample() {

package/src/components/segmented-control/examples/states.tsx

@@ -1,4 +1,4 @@
-/** No selection yet, a disabled segment and a disabled group next to the default — `disabled`. */
+/** No selection yet, an invalid group, a disabled segment and a disabled group next to the default — `invalid`, `disabled`. */
 import { SegmentedControl, Typography } from "prime-ui-kit";
 
 export default function SegmentedControlStatesExample() {
@@ -22,6 +22,15 @@ export default function SegmentedControlStatesExample() {
           empty
         </Typography>
       </div>
+      <div>
+        <SegmentedControl.Root invalid aria-label="Статус кампании">
+          <SegmentedControl.Item value="active">Активные</SegmentedControl.Item>
+          <SegmentedControl.Item value="archived">Архив</SegmentedControl.Item>
+        </SegmentedControl.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          invalid
+        </Typography>
+      </div>
       <div>
         <SegmentedControl.Root defaultValue="active" aria-label="Статус кампании">
           <SegmentedControl.Item value="active">Активные</SegmentedControl.Item>