prime-ui-kit 0.3.1 → 0.4.0

package/src/components/segmented-control/examples/full-width.tsx

@@ -0,0 +1,16 @@
+import { SegmentedControl } from "prime-ui-kit";
+
+import styles from "./segmented-examples.module.css";
+
+/** Override root `width: fit-content` with a full-width class in a narrow shelf (mirrors playground/snippets/segmented/full-width). */
+export default function SegmentedFullWidthExample() {
+  return (
+    <div className={styles.fullWidthShelf}>
+      <SegmentedControl.Root defaultValue="day" size="m" className={styles.fullWidthRoot}>
+        <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+        <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+        <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+      </SegmentedControl.Root>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/pricing-toggle.tsx

@@ -0,0 +1,40 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+type BillingCycle = "monthly" | "annual";
+
+function isBillingCycle(value: string): value is BillingCycle {
+  return value === "monthly" || value === "annual";
+}
+
+/**
+ * SaaS-style billing cycle toggle: two clear options, often paired with price copy elsewhere.
+ */
+export default function PricingToggleExample() {
+  const [cycle, setCycle] = React.useState<BillingCycle>("monthly");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <SegmentedControl.Root
+        value={cycle}
+        onValueChange={(v) => {
+          if (isBillingCycle(v)) setCycle(v);
+        }}
+        size="m"
+      >
+        <SegmentedControl.Item value="monthly">Monthly</SegmentedControl.Item>
+        <SegmentedControl.Item value="annual">Annual</SegmentedControl.Item>
+      </SegmentedControl.Root>
+      <Typography.Root as="p" variant="body-compact" tone="muted">
+        Showing prices for <strong>{cycle === "monthly" ? "monthly" : "annual"}</strong> billing.
+      </Typography.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,41 @@
+/* Visually hidden label for icon-only segments (accessible name). */
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+/* Layout helpers aligned with playground/snippets/segmented demos */
+.demoRow {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.demoStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.fullWidthShelf {
+  width: min(100%, 22rem);
+}
+
+/* Higher specificity than SegmentedControl `.root` (`width: fit-content`) without `!important`. */
+.fullWidthShelf .fullWidthRoot {
+  width: 100%;
+}
+
+.demoCaption {
+  margin-top: var(--prime-sys-spacing-s);
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-muted);
+}

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

@@ -0,0 +1,51 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+
+import styles from "./segmented-examples.module.css";
+
+/** Same segment labels across control sizes `s`–`xl` (mirrors playground/snippets/segmented/sizes). */
+export default function SegmentedSizesExample() {
+  return (
+    <div className={styles.demoStack}>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          SegmentedControl s
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" size="s">
+          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          SegmentedControl m
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" size="m">
+          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          SegmentedControl l
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" size="l">
+          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          SegmentedControl xl
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" size="xl">
+          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,43 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+
+import styles from "./segmented-examples.module.css";
+
+/** Default group, one disabled item, entire group disabled (mirrors playground/snippets/segmented/states). */
+export default function SegmentedStatesExample() {
+  return (
+    <div className={styles.demoStack}>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Default
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" size="m">
+          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          One segment disabled
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="active" size="m">
+          <SegmentedControl.Item value="active">Active</SegmentedControl.Item>
+          <SegmentedControl.Item value="paused" disabled>
+            Paused
+          </SegmentedControl.Item>
+          <SegmentedControl.Item value="archived">Archived</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <div className={styles.demoRow}>
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          Entire control disabled
+        </Typography.Root>
+        <SegmentedControl.Root defaultValue="day" disabled size="m">
+          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
+          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/segmented-control/examples/view-mode.tsx

@@ -0,0 +1,53 @@
+import { SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+type CatalogView = "list" | "grid" | "table";
+
+function isCatalogView(value: string): value is CatalogView {
+  return value === "list" || value === "grid" || value === "table";
+}
+
+/**
+ * Catalog or dashboard view mode: mutually exclusive layout, state owned by the parent.
+ */
+export default function ViewModeExample() {
+  const [view, setView] = React.useState<CatalogView>("list");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-m)",
+          alignItems: "center",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          View
+        </Typography.Root>
+        <SegmentedControl.Root
+          value={view}
+          onValueChange={(v) => {
+            if (isCatalogView(v)) setView(v);
+          }}
+          size="m"
+        >
+          <SegmentedControl.Item value="list">List</SegmentedControl.Item>
+          <SegmentedControl.Item value="grid">Grid</SegmentedControl.Item>
+          <SegmentedControl.Item value="table">Table</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </div>
+      <Typography.Root as="p" variant="body-default" tone="muted">
+        Active layout: <strong>{view}</strong>
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/segmented-progress-bar/COMPONENT.md

@@ -1,22 +1,56 @@
 # SegmentedProgressBar
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the screen explicitly needs another tier.
 
-## About
+## Canonical
 
-A horizontal **stacked** bar: one segment per category, with widths proportional to each segment’s **`value`** (weight). Use semantic **`tone`** colors for status (success, warning, danger, etc.) and optional labels for tooltips and assistive-tech descriptions.
+- **`SegmentedProgressBar`** — proportional **stacked** bar: **`SegmentedProgressBar.Root`** only; one segment per category, width ∝ **`value`** (weight).
+- **`segments`:** each item has **`value`** (≥ 0, clamped), optional **`label`** (tooltip + assistive copy), optional **`tone`**: **`primary` | `success` | `warning` | `danger` | `neutral`** (default **`primary`**).
+- **`segmentGap`:** **`none`** (default, continuous bar) or **`hairline`** (1px separators via track background).
+- **`label`:** optional visible title above the track; when set, the track uses **`aria-labelledby`** + **`aria-describedby`** with a visually hidden distribution string; without **`label`**, **`aria-label`** is the distribution text.
+- **Not** a native **`<progress>`** — track is **`role="group"`**; use [ProgressBar](../progress-bar/COMPONENT.md) for a single determinate fraction.
+- **Not** for picking a segment — use [SegmentedControl](../segmented-control/COMPONENT.md); **not** for steps — use [Stepper](../stepper/COMPONENT.md).
 
-- **Use** for part-to-whole breakdowns—e.g. job outcomes (errors / pending / success), survey responses, or storage by type.
-- **Use** with **`segmentGap="none"`** (default) for a continuous bar; use **`segmentGap="hairline"`** when segments should read as distinct columns with a 1px separator.
-- **Use** with **`label`** when the bar needs a visible title; the **distribution** string is still exposed to screen readers via **`aria-describedby`**.
-- **Do not use** for a single continuous fraction of one task—use [ProgressBar](../progress-bar/COMPONENT.md) (native `<progress>`).
-- **Do not use** for interactive selection—use [SegmentedControl](../segmented-control/COMPONENT.md).
-- **Do not use** for discrete steps—use [Stepper](../stepper/COMPONENT.md).
+## Extended
 
-## Composition
+### About
 
-- **`SegmentedProgressBar`** is a single-part namespace: only **`SegmentedProgressBar.Root`** is public.
-- **`SegmentedProgressBar.Root`** renders a wrapper `div` with `data-size` and `data-segment-gap`, an optional **`label`**, a visually hidden **`<span>`** with the distribution text when **`label`** is set, and a **`role="group"`** track containing one **`div`** per segment.
+`SegmentedProgressBar` shows a part-to-whole breakdown: segment widths follow **`value[i] / sum(values)`** via **`flex-grow`**, so layout stays correct in shrink-to-fit parents. Percentages in the accessibility description are rounded to whole numbers.
+
+- **When to use** — status mixes (errors / pending / success), survey or poll shares, rollout phase allocation, storage or budget split by category.
+- **When to use** — **`segmentGap="none"`** for one solid bar; **`hairline`** when segments should read as separate columns.
+- **When to use** — per-segment **`label`** for tooltips and clearer **`aria-*`** distribution text.
+- **When not to use** — a single task completion percentage; use **ProgressBar**.
+- **When not to use** — interactive selection or toggles; use **SegmentedControl**.
+- **When not to use** — discrete wizard steps; use **Stepper**.
+
+### Composition
+
+- **`SegmentedProgressBar.Root`** — outer wrapper with **`data-size`**, **`data-segment-gap`**, optional visible **`label`**, optional visually hidden distribution **`span`** (when **`label`** is set), and a **`role="group"`** track with one **`div`** per segment (presentational fills).
+
+### Playground (`playground/sections/SegmentedProgressBarSection.tsx`)
+
+The section renders snippets from **`playground/snippets/progress/`** (segmented bar demos only):
+
+| Demo (section) | Snippet | What it shows |
+|----------------|---------|----------------|
+| Распределение | [`segmented-distribution.tsx`](../../../playground/snippets/progress/segmented-distribution.tsx) | Weights as shares of the sum (like percentages when the total is 100); visible **`label`** and per-segment **`label`** / **`tone`** (Russian copy in the snippet; **`previewLayout="stack"`**). |
+| Размеры | [`segmented-sizes.tsx`](../../../playground/snippets/progress/segmented-sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** with the same weights (**`previewLayout="stack-center"`**). |
+| Зазор между сегментами | [`segmented-gap.tsx`](../../../playground/snippets/progress/segmented-gap.tsx) | Default **`segmentGap="none"`** vs **`hairline`** (1px separators); **`previewLayout="stack"`**. |
+
+`playground/snippets/segmented/*` is for **SegmentedControl**, not this component.
+
+### Example files in `examples/`
+
+Imports use **`"prime-ui-kit"`** so the same patterns work in an app. **`distribution-breakdown`**, **`size-ladder`**, and **`segment-gaps`** mirror the three playground frames above (same structure; English labels and copy where the snippets use Russian).
+
+| File | Scenario |
+|------|----------|
+| [`distribution-breakdown.tsx`](examples/distribution-breakdown.tsx) | **`label`** + weighted segments + **`tone`** (`snippets/progress/segmented-distribution.tsx`). |
+| [`size-ladder.tsx`](examples/size-ladder.tsx) | **`size`** ladder **`s`–`xl`** (`snippets/progress/segmented-sizes.tsx`; snippet wraps rows in **`stack`** + **`examplePreviewBleed`** for the playground). |
+| [`segment-gaps.tsx`](examples/segment-gaps.tsx) | **`segmentGap`** **`none`** vs **`hairline`** (`snippets/progress/segmented-gap.tsx`). |
+| [`multi-phase-rollout.tsx`](examples/multi-phase-rollout.tsx) | Phase mix (internal / beta / GA) with distinct **`tone`** values — not mounted in the section; extra recipe. |
+| [`storage-mix.tsx`](examples/storage-mix.tsx) | Category-style breakdown with **`hairline`** — not mounted in the section; extra recipe. |
 
 ### Minimal example
 
@@ -37,15 +71,13 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
-- **Weights** are **non-negative**; each **`value`** is clamped to **`≥ 0`**. Invalid numbers are treated as **`0`**.
-- **Segment sizes** follow **`value[i] / sum(values)`** via **`flex-grow`** on the track (not `%` width), so layout stays correct in shrink-to-fit parents (e.g. playground `stack` preview). If the sum is **`0`**, the track is empty (track background only).
-- **Percentages** in the accessibility description are **rounded** to whole numbers.
-- **`segmentGap`** defaults to **`none`** (no gap between fills). **`hairline`** задаёт **`gap: 1px`** на треке; фон трека — **`--prime-sys-color-border-subtle`**, сегменты лежат поверх (видна «линия» между заливками). При **`none`** фон трека — **`surface-accentSoft`**.
-- **`tone`** defaults to **`primary`** when omitted; allowed values: **`primary`**, **`success`**, **`warning`**, **`danger`**, **`neutral`**.
-- **`label`** on each segment is passed to **`title`** on the segment for tooltips; it also appears in the **distribution** string for assistive tech when provided.
-- The bar is **not** a single native **`progressbar`**; the track is **`role="group"`** with **`aria-label`** (no visible label) or **`aria-labelledby`** + **`aria-describedby`** (with label).
+- **Weights** are non-negative; invalid numbers are treated as **`0`**. If the sum is **`0`**, the track shows no fills (track background only).
+- **Layout** uses **`flex-grow`** from weights, not `%` width, so proportions stay correct when the parent shrinks.
+- **`segmentGap`:** **`none`** — track background **`surface-accentSoft`**; **`hairline`** — **`gap: 1px`** on the track, background **`border-subtle`**, segments sit on top so a thin line shows between fills.
+- **`tone`** omitted → **`primary`**.
+- Segment **`label`** → native **`title`** on the segment **div**.
 
 ## API
 
@@ -54,8 +86,8 @@ export function Example() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `segments` | `SegmentedProgressSegment[]` | — | Yes | Non-negative weights; layout is proportional to the sum. |
-| `label` | `string` | — | No | Text above the track; when set, the group uses **`aria-labelledby`** and **`aria-describedby`**. |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height and label typography (same scale as ProgressBar). |
+| `label` | `string` | — | No | Text above the track; **`aria-labelledby`** + **`aria-describedby`** when set. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height and label typography (aligned with ProgressBar). |
 | `segmentGap` | `"none" \| "hairline"` | `"none"` | No | Gap between segment fills. |
 | `className` | `string` | — | No | Class on the outer wrapper. |
 | `ref` | `React.Ref<HTMLDivElement>` | — | No | Ref to the **`role="group"`** track element. |
@@ -64,12 +96,24 @@ export function Example() {
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `value` | `number` | Yes | Weight **`≥ 0`**; contributes to proportion. |
-| `label` | `string` | No | Tooltip and assistive-tech segment label. |
+| `value` | `number` | Yes | Weight ≥ 0; contributes to proportion. |
+| `label` | `string` | No | Tooltip and assistive segment label in the distribution string. |
 | `tone` | `"primary" \| "success" \| "warning" \| "danger" \| "neutral"` | No | Default **`primary`**. |
 
 ## Related
 
-- [ProgressBar](../progress-bar/COMPONENT.md) — single determinate progress on `<progress>`.
+- [ProgressBar](../progress-bar/COMPONENT.md) — single determinate progress on **`<progress>`**.
 - [ProgressCircle](../progress-circle/COMPONENT.md) — circular fraction.
 - [Typography](../typography/COMPONENT.md) — headings and legends beside the bar.
+
+## LLM note
+
+- Playground source of truth for live demos: **`playground/sections/SegmentedProgressBarSection.tsx`** → **`playground/snippets/progress/segmented-{distribution,sizes,gap}.tsx`** (not **`snippets/segmented/`**, which is SegmentedControl).
+- Export: **`import { SegmentedProgressBar } from "prime-ui-kit"`** — public surface is **`SegmentedProgressBar.Root`** only (namespace object).
+- **`SegmentedProgressBarRootProps`:** **`segments`** (required), **`label?`**, **`size?`**, **`segmentGap?`**, **`className?`**; **`ref`** → track **`div`** (**`role="group"`**).
+- **`SegmentedProgressSegment`:** **`value`** (number), **`label?`**, **`tone?`** — **`tone`** literals: **`primary`**, **`success`**, **`warning`**, **`danger`**, **`neutral`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
+- **`segmentGap`** literals: **`none`**, **`hairline`** — default **`none`**.
+- Do not describe this as a native progress bar; it is **`role="group"`**, not **`role="progressbar"`**.
+- Do not suggest **SegmentedControl** or **Stepper** for the same job unless the UX is selection or steps, not a static breakdown.
+- For a single 0–100% task, recommend **ProgressBar** instead.

package/src/components/segmented-progress-bar/examples/distribution-breakdown.tsx

@@ -0,0 +1,16 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+/** Part-to-whole job outcomes with a visible title and per-segment labels for tooltips and SR distribution. */
+export default function DistributionBreakdownExample() {
+  return (
+    <SegmentedProgressBar.Root
+      label="Pipeline results"
+      segments={[
+        { value: 30, label: "Failed", tone: "danger" },
+        { value: 25, label: "Queued", tone: "warning" },
+        { value: 35, label: "Succeeded", tone: "success" },
+        { value: 10, label: "Skipped", tone: "neutral" },
+      ]}
+    />
+  );
+}

package/src/components/segmented-progress-bar/examples/multi-phase-rollout.tsx

@@ -0,0 +1,15 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+/** Rollout mix by phase: weights reflect share of accounts or environments on each tier. */
+export default function MultiPhaseRolloutExample() {
+  return (
+    <SegmentedProgressBar.Root
+      label="Feature rollout"
+      segments={[
+        { value: 15, label: "Internal", tone: "neutral" },
+        { value: 35, label: "Beta", tone: "warning" },
+        { value: 50, label: "General availability", tone: "success" },
+      ]}
+    />
+  );
+}

package/src/components/segmented-progress-bar/examples/segment-gaps.tsx

@@ -0,0 +1,23 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+const segments = [
+  { value: 50, label: "Region A", tone: "primary" as const },
+  { value: 50, label: "Region B", tone: "neutral" as const },
+];
+
+/** Default continuous bar vs hairline separators — weights and tones are unchanged. */
+export default function SegmentGapsExample() {
+  return (
+    <>
+      <SegmentedProgressBar.Root
+        segments={segments}
+        label="Continuous (default, segmentGap none)"
+      />
+      <SegmentedProgressBar.Root
+        segmentGap="hairline"
+        segments={segments}
+        label="Hairline separators"
+      />
+    </>
+  );
+}

package/src/components/segmented-progress-bar/examples/size-ladder.tsx

@@ -0,0 +1,19 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+const segments = [
+  { value: 40, tone: "danger" as const },
+  { value: 35, tone: "warning" as const },
+  { value: 25, tone: "success" as const },
+];
+
+/** Same weights across the control size scale (aligned with ProgressBar). */
+export default function SizeLadderExample() {
+  return (
+    <>
+      <SegmentedProgressBar.Root size="s" segments={segments} />
+      <SegmentedProgressBar.Root size="m" segments={segments} />
+      <SegmentedProgressBar.Root size="l" segments={segments} />
+      <SegmentedProgressBar.Root size="xl" segments={segments} />
+    </>
+  );
+}

package/src/components/segmented-progress-bar/examples/storage-mix.tsx

@@ -0,0 +1,16 @@
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+/** Non-status categories: tones differentiate segments without implying pass/fail. */
+export default function StorageMixExample() {
+  return (
+    <SegmentedProgressBar.Root
+      label="Disk usage by type"
+      segmentGap="hairline"
+      segments={[
+        { value: 42, label: "Documents", tone: "primary" },
+        { value: 33, label: "Media", tone: "neutral" },
+        { value: 25, label: "Applications", tone: "warning" },
+      ]}
+    />
+  );
+}

package/src/components/select/COMPONENT.md

@@ -1,43 +1,60 @@
 # Select
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
 
 ## About
 
 A single-select field: by default (**`native`** `false`) it is a combobox — a trigger shows the current choice or a placeholder, and a portaled listbox lets the user pick one string value from predefined options. With **`native`** `true`, **`Select.Root`** renders a native **`<select>`** with **`<option>`** / **`<optgroup>`** built from the same **`Select.Item`** (and optional **`Select.Group`**) tree.
 
-- **Use** for forms, settings, and filters where exactly one option must be chosen from a closed set (role, country, theme, interval, and similar fields).
-- **Use** when a compact trigger label is enough and the full list should open on demand with keyboard support.
-- **Use** optional `Select.Group`, `Select.GroupLabel`, and `Select.Separator` to structure long option lists.
-- **Do not use** for multi-select, inline search, or async loading of options; this primitive is single-choice only with static item children.
-- **Do not use** when the user must type arbitrary text; use an input-style control instead.
-- **Do not use** for command or action menus; use [Dropdown](../dropdown/COMPONENT.md) when choices are actions, not a single form value.
+**When to use**
+
+- Forms, settings, and filters where exactly one option must be chosen from a closed set (role, country, theme, interval, and similar fields).
+- Flows where a compact trigger is enough and the full list should open on demand with keyboard support.
+- Long option lists structured with **`Select.Group`**, **`Select.GroupLabel`**, and **`Select.Separator`**.
+
+**When not to use**
+
+- Multi-select, inline search, or async loading of options — this primitive is single-choice only with static item children.
+- Arbitrary free text — use an input-style control instead.
+- Command or action menus — use [Dropdown](../dropdown/COMPONENT.md) when choices are actions, not a single form value.
 
 ## Composition
 
 - **`Select.Root`** — owns value (controlled or uncontrolled), `size`, `hasError`, `disabled`, **`placeholder`**, and **`native`**. When **`native`** is `false`, it also owns open state and highlight. Wrap everything else.
-- **`Select.Trigger`** — (non-**`native`** only) the combobox `button` (fixed chevron on the right). Put **`Select.Value`** inside; optionally **`Select.TriggerIcon`** before **`Select.Value`**.
+- **`Select.Trigger`** — (non-**`native`** only) the combobox `button` (fixed chevron on the right). Put **`Select.Value`** inside; optionally **`Select.TriggerIcon`** before **`Select.Value`**. The implementation sets the trigger **`id`**; you cannot override it — associate an external [Label](../label/COMPONENT.md) with **`aria-labelledby`** pointing at the label’s **`id`**.
 - **`Select.Value`** — (non-**`native`** only) displays the selected item label, otherwise falls back to the raw value or **`placeholder`** (hint styling when empty).
-- **`Select.Content`** — when **`native`** is `false`: portaled **`role="listbox"`**; rendered in the tree always but hidden when closed. Place **`Select.Item`** rows (and optional groups/separators) inside. Must come after the trigger in the document for a predictable structure. When **`native`** is `true`, **`Select.Content`** is optional as a structural wrapper; only **`Select.Item`** (and groups) contribute to the DOM **`<select>`**.
+- **`Select.Content`** — when **`native`** is `false`: portaled **`role="listbox"`** with **`display: none`** while closed (nodes stay mounted). Place **`Select.Item`** rows (and optional groups/separators) inside. Must come after the trigger in the document for a predictable structure. When **`native`** is `true`, **`Select.Content`** is optional as a structural wrapper; only **`Select.Item`** (and groups) contribute to the DOM **`<select>`**.
 - **`Select.Item`** — one option per row; optional **`Select.ItemIcon`** children are recognized by component type and rendered before the text. Use **`label`** when the trigger should show different text than the row content.
 - **`Select.Group`** / **`Select.GroupLabel`** / **`Select.Separator`** — optional structure inside **`Select.Content`**.
 
-### Minimal example
+### Canonical example
 
 ```tsx
-import { Select } from "prime-ui-kit";
+import * as React from "react";
+import { Label, Select, Typography } from "prime-ui-kit";
 
 export function Example() {
+  const labelId = React.useId();
+
   return (
-    <Select.Root size="m" placeholder="Choose">
-      <Select.Trigger>
-        <Select.Value />
-      </Select.Trigger>
-      <Select.Content>
-        <Select.Item value="a">Option A</Select.Item>
-        <Select.Item value="b">Option B</Select.Item>
-      </Select.Content>
-    </Select.Root>
+    <div>
+      <Label.Root id={labelId} size="m">
+        Department
+      </Label.Root>
+      <Select.Root size="m" placeholder="Choose">
+        <Select.Trigger aria-labelledby={labelId}>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="eng">Engineering</Select.Item>
+          <Select.Item value="design">Design</Select.Item>
+          <Select.Item value="sales">Sales</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Typography.Root as="p" variant="caption" tone="muted">
+        Used for routing internal requests only.
+      </Typography.Root>
+    </div>
   );
 }
 ```
@@ -59,6 +76,45 @@ export function NativeExample() {
 
 You can wrap items in **`Select.Content`** for parity with the composable tree; behavior is the same.
 
+### Playground snippets (live demos)
+
+These files power **`playground/sections/SelectSection.tsx`** (Russian copy in the playground UI). Order matches the section.
+
+| File | Intent |
+|------|--------|
+| `playground/snippets/select/sizes.tsx` | Four **`size`** values **`s`–`xl`** in one column |
+| `playground/snippets/select/states.tsx` | Placeholder only, **`defaultValue`**, root **`disabled`**, **`hasError`** |
+| `playground/snippets/select/controlled.tsx` | **`value`** / **`onChange`** with caption showing parent state |
+| `playground/snippets/select/composition.tsx` | **`Select.TriggerIcon`**, **`Select.ItemIcon`**, item **`label`** vs short row text |
+| `playground/snippets/select/full-width.tsx` | Trigger fills a narrow shell (**`width: 100%`** from kit styles) |
+| `playground/snippets/select/native.tsx` | **`Select.Root`** **`native`** with optional **`Select.Content`** wrapper |
+| `playground/snippets/select/features.tsx` | **`Group`** / **`GroupLabel`** / **`Separator`**, disabled item, long list + scroll |
+
+### Examples next to this file
+
+Runnable examples use **`@/`** in the workspace; published consumers import **`prime-ui-kit`**. **`pattern-*`** files mirror the playground snippets above in English (same APIs).
+
+| File | Intent |
+|------|--------|
+| `examples/pattern-sizes.tsx` | **`sizes.tsx`** snippet |
+| `examples/pattern-states.tsx` | **`states.tsx`** snippet |
+| `examples/pattern-controlled.tsx` | **`controlled.tsx`** snippet |
+| `examples/pattern-composition.tsx` | **`composition.tsx`** snippet |
+| `examples/pattern-full-width.tsx` | **`full-width.tsx`** snippet |
+| `examples/pattern-native.tsx` | **`native.tsx`** snippet |
+| `examples/pattern-features.tsx` | **`features.tsx`** snippet |
+
+### Additional scenarios
+
+| File | Intent |
+|------|--------|
+| [`./examples/01-country.tsx`](./examples/01-country.tsx) | Visible **`Label.Root`** + **`aria-labelledby`** on **`Select.Trigger`** and helper copy |
+| [`./examples/02-controlled.tsx`](./examples/02-controlled.tsx) | Controlled **`value`** / **`onChange`** with **`Label.Root`** (same tier options as **`pattern-controlled.tsx`**) |
+| [`./examples/03-groups.tsx`](./examples/03-groups.tsx) | Time zones with **`Select.Group`**, **`Select.GroupLabel`**, **`Select.Separator`** |
+| [`./examples/04-full-width-form.tsx`](./examples/04-full-width-form.tsx) | Multi-field form column; triggers span the track |
+
+**LLM note:** Prefer **`pattern-*`** and `playground/snippets/select/*.tsx` for parity with live demos; use **`01`–`04`** for labeled forms and richer scenarios. This page keeps the contract (rules + API tables) authoritative.
+
 ## Rules
 
 - **`native`** — default **`false`**. **`true`**: one **`<select>`** with kit styling; **`Select.Trigger`**, **`Select.Value`**, **`Select.Content`** portal, and listbox keyboard behavior are not used (the platform handles the dropdown). Options are collected by walking **`children`** for **`Select.Item`** (and **`Select.Group`** / **`Select.GroupLabel`** → **`<optgroup>`**; **`Select.Separator`** is skipped). **`placeholder`** adds a first **`<option value="">`**; do not use **`value=""`** on an **`Select.Item`** if you rely on that placeholder. **`Select.ItemIcon`** / **`Select.TriggerIcon`** are not represented in the native control.
@@ -67,6 +123,7 @@ You can wrap items in **`Select.Content`** for parity with the composable tree;
 - **`disabled`** on **`Select.Root`** prevents opening the list and selecting; the trigger is inactive.
 - **`disabled`** on **`Select.Item`** skips that option for pointer selection and for arrow-key navigation among enabled options only.
 - **`hasError`** on **`Select.Root`** applies error styling to the trigger; there is no separate **`variant`** prop.
+- **Width:** there is no **`fullWidth`** prop on **`Select.Root`**. The combobox trigger uses **`width: 100%`** — constrain or stretch the field with the parent layout (form column, grid cell, flex item).
 - **`Select.Content`** uses **`Portal`**, which attaches after the first client layout effect; until option nodes mount, **`selectedLabel`** may be unset and **`Select.Value`** can briefly show the raw **`value`** instead of an item’s **`label`**—effects on **`Select.Item`** then call **`onInitLabel`** to align the trigger text.
 - **`Select.Content`** is portaled; on open the listbox receives focus, **`useOutsideClick`** and **Escape** close it. Arrow **Up**/**Down**, **Home**/**End** move highlight; **Enter** or **Space** selects the highlighted enabled item; **Escape** closes from the listbox handler as well.
 - **`Select.Trigger`** is **`role="combobox"`** with **`aria-expanded`**, **`aria-haspopup="listbox"`**, and **`aria-controls`** pointing at the listbox **`id`**. Items expose **`role="option"`**, **`aria-selected`**, and **`aria-disabled`** when disabled.
@@ -79,7 +136,7 @@ You can wrap items in **`Select.Content`** for parity with the composable tree;
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger and list sizing tokens |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Token tier: trigger height, type scale, padding, icon sizes in trigger and list |
 | value | `string` | — | No | Controlled selected value |
 | defaultValue | `string` | — | No | Initial value when uncontrolled |
 | onChange | `(value: string) => void` | — | No | Fires after a new value is selected |
@@ -120,7 +177,7 @@ You can wrap items in **`Select.Content`** for parity with the composable tree;
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | className | `string` | — | No | Class on the portaled listbox container |
-| children | `React.ReactNode` | — | Yes | Items, groups, and separators |
+| children | `React.ReactNode` | — | Yes | Items, groups, and separators (listbox portal stays mounted; hidden while closed) |
 
 ### Select.Item