prime-ui-kit 0.7.11 → 0.9.0

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

@@ -0,0 +1,90 @@
+# ScrollContainer
+
+**Category:** 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 custom panel or page column that needs the same scrollbar and overscroll rules as the kit's own overlays.
+
+## When not to use
+- Modal / Drawer body, Select / Dropdown / Popover panels, CommandMenu list, DataTable viewport → they already scroll through ScrollContainer; do not wrap them again ([Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Popover](../popover/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)).
+- The main page column inside the app shell → `AppShell.Main` is already a ScrollContainer ([AppShell](../../layout/app-shell/COMPONENT.md)).
+- Content that should simply grow with the page → no scroll container at all.
+
+## Import
+```tsx
+import { ScrollContainer } from "prime-ui-kit";
+```
+
+## API
+
+### ScrollContainer
+`forwardRef` to the root `HTMLElement`. No `asChild`.
+
+| 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`). |
+| `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).
+
+## Variants
+
+### axis
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `vertical` | `overflow-y: auto`, `overflow-x: hidden`, thin vertical thumb | Lists, feeds, panel bodies | yes |
+| `horizontal` | `overflow-x: auto`, `overflow-y: hidden`, thin horizontal thumb | Chip / filter strips, wide rows | |
+| `both` | `overflow: auto` on both axes | Wide tables or canvases that also scroll vertically | |
+
+### overscrollBehavior
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | |
+
+**Combinations** — `axis="horizontal"` with `overscrollBehavior="contain"` (default) for strips; `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.
+
+## 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.
+
+## 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.
+- Choose a semantic `as` (`main`, `nav`, `aside`) when the region is a landmark.
+- No `labels`.
+
+## 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 |
+
+```tsx
+import { ScrollContainer } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <ScrollContainer aria-label="Журнал событий" className="eventLog">
+      <p>Длинный текст…</p>
+    </ScrollContainer>
+  );
+}
+```
+
+## 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.
+- 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)

package/src/components/scroll-container/examples/both-axes.tsx

@@ -0,0 +1,57 @@
+/** `axis="both"` for a wide grid that scrolls in both directions, and `overscrollBehavior="auto"` that hands the scroll to the page at the end. Use for wide canvases, schedules and timetables. */
+import { ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const HOURS = Array.from({ length: 12 }, (_, i) => `${String(9 + i).padStart(2, "0")}:00`);
+const ROOMS = Array.from({ length: 16 }, (_, i) => `Зал ${i + 1}`);
+
+export default function ScrollContainerBothAxesExample() {
+  return (
+    <div className={styles.layout}>
+      <section className={styles.card} aria-label="Расписание залов">
+        <Typography.Root as="h3" variant="title-s" className={styles.cardTitle}>
+          Расписание · axis=both
+        </Typography.Root>
+        <ScrollContainer
+          axis="both"
+          tabIndex={0}
+          aria-label="Сетка расписания"
+          className={styles.canvas}
+        >
+          <div className={styles.grid}>
+            {ROOMS.flatMap((room) =>
+              HOURS.map((hour) => (
+                <Typography.Root
+                  key={`${room}-${hour}`}
+                  as="div"
+                  variant="caption"
+                  tone="secondary"
+                  className={styles.cell}
+                >
+                  {room} · {hour}
+                </Typography.Root>
+              )),
+            )}
+          </div>
+        </ScrollContainer>
+      </section>
+      <section className={styles.card} aria-label="Журнал">
+        <Typography.Root as="h3" variant="title-s" className={styles.cardTitle}>
+          Журнал · overscroll auto
+        </Typography.Root>
+        <ScrollContainer overscrollBehavior="auto" tabIndex={0} aria-label="Журнал событий">
+          <ul className={styles.list}>
+            {HOURS.map((hour) => (
+              <li key={hour}>
+                <Typography.Root as="span" variant="body-m" tone="secondary">
+                  {hour} — отчёт выгружен
+                </Typography.Root>
+              </li>
+            ))}
+          </ul>
+        </ScrollContainer>
+      </section>
+    </div>
+  );
+}

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

@@ -0,0 +1,66 @@
+/* Layout for the ScrollContainer examples: layout and card surface only, text goes through Typography. */
+
+.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%;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  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);
+}
+
+.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;
+}
+
+.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;
+}

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

@@ -0,0 +1,44 @@
+/** A vertical list that scrolls inside a fixed-height flex card and a horizontal strip of badges (`axis="horizontal"`). Use when a region inside a card or panel must scroll on its own. */
+import { Badge, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = Array.from({ length: 16 }, (_, i) => `Заказ № ${1040 + i} оплачен`);
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+
+export default function ScrollContainerListExample() {
+  return (
+    <div className={styles.layout}>
+      <section className={styles.card} aria-label="Лента событий">
+        <Typography.Root as="h3" variant="title-s" className={styles.cardTitle}>
+          Лента событий
+        </Typography.Root>
+        <ScrollContainer>
+          <ul className={styles.list}>
+            {EVENTS.map((event) => (
+              <li key={event}>
+                <Typography.Root as="span" variant="body-m" tone="secondary">
+                  {event}
+                </Typography.Root>
+              </li>
+            ))}
+          </ul>
+        </ScrollContainer>
+      </section>
+      <section className={styles.card} aria-label="Фильтры">
+        <Typography.Root as="h3" variant="title-s" className={styles.cardTitle}>
+          Фильтры
+        </Typography.Root>
+        <ScrollContainer axis="horizontal">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag} size="m">
+                {tag}
+              </Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </section>
+    </div>
+  );
+}

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

@@ -1,121 +1,209 @@
 # SegmentedControl
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** selection
 
-## About
+> A switch between 2–5 mutually exclusive options or modes that takes effect immediately.
 
-A single-choice control: a horizontal `radiogroup` whose options are segment buttons, with a floating pill indicator under the active segment.
+## 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`).
 
-- **Use** when there are few mutually exclusive options that should stay visible (period toggles, layout mode, compact filters).
-- **Use** with **`SegmentedControl.Icon`** plus visible or visually hidden text when a segment is icon-led.
-- **Do not use** for long lists or many options—prefer [Select](../select/COMPONENT.md) or a dropdown.
-- **Do not use** when each choice should show its own panel and tab keyboard model—prefer [Tabs](../tabs/COMPONENT.md).
-- **Do not use** for independent or multi-select actions—prefer [Button group](../button-group/COMPONENT.md) or other patterns.
-- **Do not use** expecting a vertical stack or orientation prop; layout is horizontal only.
-
-## Composition
-
-- **`SegmentedControl.Root`** — outer `div` with **`role="radiogroup"`**, **`data-size`**, focus and arrow-key handling, **`ControlSizeProvider`** for descendants, and a decorative indicator layer (`aria-hidden`).
-- **`SegmentedControl.Item`** — direct children of **`Root`** (and only in that role for correct behavior). Each item is a **`button`** with **`role="radio"`**; order in the tree is the visual order of segments.
-- **`SegmentedControl.Icon`** — optional **`span`** with **`aria-hidden="true"`** inside an **`Item`**; pair with visible label text or an accessible name in **`Item`** **`children`**.
-
-### Minimal example
+## 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.
 
+## Import
 ```tsx
 import { SegmentedControl } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <SegmentedControl.Root defaultValue="a">
-      <SegmentedControl.Item value="a">A</SegmentedControl.Item>
-      <SegmentedControl.Item value="b">B</SegmentedControl.Item>
-    </SegmentedControl.Root>
-  );
-}
 ```
 
-### Canonical composition (reference)
-
-For a **single file** that combines **controlled mode**, **`SegmentedControl.Icon` + text**, **icon-only segments with visually hidden labels**, and layout notes (remember **`Root` does not forward `aria-label`**), see **`examples/canonical-composition.tsx`**. Imports use **`"prime-ui-kit"`** so the same patterns work in an app after installing the package.
-
-The **playground** (`playground/sections/SegmentedControlSection.tsx`) renders the same scenarios as **`playground/snippets/segmented/*.tsx`** (internal `@/` imports). The **`examples/`** files below mirror those snippets with **`"prime-ui-kit"`** imports.
-
-### Example files in `examples/`
-
-| File | Scenario (aligned with `playground/snippets/segmented/`) |
-|------|----------|
-| `sizes.tsx` | All four **`size`** values `s`–`xl` with identical segment labels |
-| `states.tsx` | Default group; **`disabled`** on one **`Item`**; **`disabled`** on **`Root`** |
-| `controlled.tsx` | **`value`** + **`onValueChange`** (no **`defaultValue`**) |
-| `composition.tsx` | **`Icon`** + label text; icon-only rows with visually hidden text in **`Item`** |
-| `full-width.tsx` | Narrow container; **`className`** overrides root **`width: fit-content`** so segments share width |
-| `features.tsx` | Two, three, and four segments; keyboard (**ArrowLeft** / **ArrowRight** on the group) |
-
-Additional English product-style recipes:
-
-| File | Scenario |
-|------|----------|
-| `canonical-composition.tsx` | Combined: icons, controlled period, icon-only (superset demo) |
-| `view-mode.tsx` | Catalog view: List / Grid / Table |
-| `pricing-toggle.tsx` | Billing: Monthly / Annual |
-| `catalog-filters.tsx` | Compact availability filter; **`size="s"`** |
-
-### Note for LLMs
-
-- **Imports:** `SegmentedControl`, `Icon`, and `Typography` from **`"prime-ui-kit"`** in **`examples/`**; paths are relative to `src/components/segmented-control/examples/`. Playground snippets use **`@/…`** but should stay behavior-identical to these files.
-- **Values are strings:** map `onValueChange` to app enums with a type guard or narrow union; **`Item` does not accept `aria-label`**—accessible names come from **visible** `children` and/or **visually hidden** text inside **`Item`**.
-- **`SegmentedControl.Icon`** is **`aria-hidden`**; always pair with visible text or a visually hidden span inside the same **`Item`**.
-- **`Root`** does **not** forward **`aria-label`**, **`aria-labelledby`**, or **`style`**: use a **wrapper** and visible copy, or **`aria-labelledby`** on a wrapper that references visible page text—not on **`Root`**.
-- **Keyboard:** **ArrowLeft** / **ArrowRight** move among **enabled** items; **`disabled`** on **`Item`** is skipped; **`defaultValue=""`** leaves no selection and **`Root`** is focusable until the user picks a segment.
-- **Many options or vertical layout:** prefer [Select](../select/COMPONENT.md); **tabbed panels** → [Tabs](../tabs/COMPONENT.md).
-
-## Rules
-
-- **Controlled:** pass **`value`** and handle changes with **`onValueChange`**. **Uncontrolled:** use **`defaultValue`** (defaults to **`""`**).
-- **`defaultValue=""`** (and no controlled **`value`**) means **no** segment is selected; **`Root`** gets **`tabIndex={0}`** so the group can be focused until a segment is chosen.
-- Values are **strings**; mapping to app enums or unions is the consumer’s responsibility.
-- **`disabled`** on **`Root`** sets **`aria-disabled`** on the group and **`data-disabled`**; all segments are inactive.
-- **`disabled`** on an **`Item`** skips that segment for **Left/Right** arrow navigation among enabled radios.
-- **Roving tabindex:** **Tab** focuses the group (when nothing is selected) or the checked segment; **ArrowLeft** / **ArrowRight** move selection and focus across enabled items.
-- **`SegmentedControl.Icon`** is **`aria-hidden`**; the segment’s accessible name must come from **`Item`** **`children`** (visible text and/or visually hidden text). **`Item`** does not forward extra attributes—there is no **`…rest`**—so you cannot set **`aria-label`** on the segment via props.
-- **No `asChild`** and no merging **`Root`** with an arbitrary element.
-- **`Root`** does **not** forward arbitrary HTML attributes (**`aria-label`**, **`style`**, etc.); wrap **`Root`** in another element when you need extra semantics or layout hooks.
-- The indicator position follows the active segment’s layout; updates use **`ResizeObserver`** and **`MutationObserver`** on the root—avoid unpredictable segment size changes without expecting a reflow/recalc.
+## Anatomy
+```
+SegmentedControl.Root                 role="radiogroup"; track + sliding thumb, keyboard handling
+└─ 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.Description    second line; makes the segment two-line (optional)
+```
 
 ## API
 
 ### SegmentedControl.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | No | Selected value in controlled mode |
-| defaultValue | `string` | `""` | No | Initial value when uncontrolled; empty string means no segment selected |
-| onValueChange | `(value: string) => void` | — | No | Called when the selected value changes |
-| disabled | `boolean` | `false` | No | Disables the entire group |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Segment dimensions and typography |
-| children | `React.ReactNode` | — | Yes | `Item` nodes (and their content) |
-| className | `string` | — | No | Extra class on the container (e.g. full-width override when the default **`width: fit-content`** is too narrow—see **`examples/full-width.tsx`**) |
+| 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). |
+| `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.
 
 ### SegmentedControl.Item
+| 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>`. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | Yes | Segment identifier |
-| disabled | `boolean` | `false` | No | Disables this segment |
-| children | `React.ReactNode` | — | Yes | Label and/or `SegmentedControl.Icon` |
-| className | `string` | — | No | Extra 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`.
 
 ### SegmentedControl.Icon
+| 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`.
+
+### SegmentedControl.Label
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Segment title; truncates with an ellipsis. |
+| `className` | `string` | — | Class on the `<span>`. |
+
++ native `<span>` props except `children`.
+
+### SegmentedControl.Count
+| 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.
+
+### SegmentedControl.Description
+| 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`.
+
+## Variants
+No `variant`/`tone`. Axes: `size` (Root), `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 | |
+| `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 | |
+
+### 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) | |
+
+### 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 | |
+
+### Structural content
+| 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.
+
+**Hierarchy** — one segmented control per decision; in a toolbar keep all controls at one size (see [toolbar.tsx](examples/toolbar.tsx)).
+
+## 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 |
+
+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`.
+
+## 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.
+- 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.
+- Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description.
+- Icons are `aria-hidden`; icon-only items need `aria-label`.
+- No `labels` keys.
+
+## 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 |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Icon node |
-| className | `string` | — | No | Extra class on the `span` |
-| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other `span` attributes |
+```tsx
+import { SegmentedControl } from "prime-ui-kit";
 
-## Related
+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>
+  );
+}
+```
+
+## Mistakes
+- Using it as tabs that show different panels → use `Tabs`.
+- No `aria-label` on the root → the radiogroup has no name.
+- 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.
 
-- [Tabs](../tabs/COMPONENT.md) — separate panels and tab keyboard model.
-- [Button group](../button-group/COMPONENT.md) — grouped actions, not a single required choice.
-- [Radio](../radio/COMPONENT.md) — standalone radio field primitive.
-- [Select](../select/COMPONENT.md) — many options or list in a dropdown.
+## Related
+[Tabs](../tabs/COMPONENT.md) · [Radio](../radio/COMPONENT.md) · [Switch](../switch/COMPONENT.md) · [Badge](../badge/COMPONENT.md) · [Tooltip](../tooltip/COMPONENT.md)

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

@@ -0,0 +1,23 @@
+/** Items with a palette color: a dot before the label and a tinted thumb when selected. Use it for picking a status where each value has its own hue. */
+import { SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SegmentedControlColorsExample() {
+  const [status, setStatus] = React.useState("ok");
+  return (
+    <SegmentedControl.Root value={status} onValueChange={setStatus} aria-label="Техсостояние">
+      <SegmentedControl.Item value="ok" color="green">
+        Исправен
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="service" color="orange">
+        Нужно ТО
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="repair" color="red">
+        Нужен ремонт
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="in-repair" color="red">
+        В ремонте
+      </SegmentedControl.Item>
+    </SegmentedControl.Root>
+  );
+}

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

@@ -1,22 +1,23 @@
+/** A controlled group with value and onValueChange driving a caption. Use it when the selection changes other content on the page. */
 import { SegmentedControl, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./segmented-examples.module.css";
+import styles from "./examples.module.css";
 
-/** Controlled selection with `value` and `onValueChange` (mirrors playground/snippets/segmented/controlled). */
-export default function SegmentedControlledExample() {
-  const [controlled, setControlled] = React.useState("week");
+const LABELS: Record<string, string> = { day: "за день", week: "за неделю", month: "за месяц" };
+
+export default function SegmentedControlControlledExample() {
+  const [period, setPeriod] = React.useState("week");
 
   return (
-    <div className={styles.demoStack}>
-      <SegmentedControl.Root value={controlled} onValueChange={setControlled}>
-        <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
-        <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
-        <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+    <div className={styles.cell}>
+      <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.Root as="p" variant="body-compact" tone="muted" className={styles.demoCaption}>
-        Selected: <strong>{controlled}</strong> — state is held in React (<code>value</code> +{" "}
-        <code>onValueChange</code>).
+      <Typography.Root variant="caption" tone="muted">
+        Показываем выручку {LABELS[period]}
       </Typography.Root>
     </div>
   );