prime-ui-kit 0.0.1

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

@@ -0,0 +1,52 @@
+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);
+          }}
+        >
+          <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

@@ -0,0 +1,119 @@
+# SegmentedProgressBar
+
+**Default `size`:** use **`m`** for the size axis unless the screen explicitly needs another tier.
+
+## Canonical
+
+- **`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).
+
+## Extended
+
+### About
+
+`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
+
+```tsx
+import { SegmentedProgressBar } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <SegmentedProgressBar.Root
+      segments={[
+        { value: 30, label: "Errors", tone: "danger" },
+        { value: 25, label: "Pending", tone: "warning" },
+        { value: 35, label: "Success", tone: "success" },
+        { value: 10, label: "Other", tone: "neutral" },
+      ]}
+    />
+  );
+}
+```
+
+### Rules
+
+- **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
+
+### SegmentedProgressBar.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `segments` | `SegmentedProgressSegment[]` | — | Yes | Non-negative weights; layout is proportional to the sum. |
+| `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. |
+
+### SegmentedProgressSegment
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `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>`**.
+- [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 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

@@ -0,0 +1,232 @@
+# Select
+
+**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.
+
+**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`**. 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"`** 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`**.
+
+### Canonical example
+
+```tsx
+import * as React from "react";
+import { Label, Select, Typography } from "prime-ui-kit";
+
+export function Example() {
+  const labelId = React.useId();
+
+  return (
+    <div>
+      <Label.Root id={labelId}>
+        Department
+      </Label.Root>
+      <Select.Root 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>
+  );
+}
+```
+
+### Native `<select>` (`native`)
+
+```tsx
+import { Select } from "prime-ui-kit";
+
+export function NativeExample() {
+  return (
+    <Select.Root native placeholder="Choose">
+      <Select.Item value="a">Option A</Select.Item>
+      <Select.Item value="b">Option B</Select.Item>
+    </Select.Root>
+  );
+}
+```
+
+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.
+- **Controlled:** set **`value`** and **`onChange`** together. **Uncontrolled:** use **`defaultValue`** (or neither for an empty initial value). Values are always **`string`**; map numbers or enums to strings yourself.
+- **`onChange`** runs only when the value changes to a defined string (same contract as internal controllable state).
+- **`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.
+- If there is no visible text label on the trigger, set **`aria-label`** on **`Select.Trigger`**. For an external [Label](../label/COMPONENT.md), give the label a stable **`id`** and set **`aria-labelledby`** on **`Select.Trigger`** to that **`id`** (the trigger’s **`id`** is generated inside the component).
+- List position (e.g. flipping above/below) is resolved internally from viewport space; there are no public **`side`** / **`align`** props on **`Select.Content`**.
+
+## API
+
+### Select.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| 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 |
+| disabled | `boolean` | — | No | Disables the trigger and selection |
+| placeholder | `string` | — | No | Shown in the trigger when no value is selected |
+| hasError | `boolean` | `false` | No | Error styling on the trigger |
+| native | `boolean` | `false` | No | **`true`**: native **`<select>`**; **`false`**: combobox + portaled listbox |
+| children | `React.ReactNode` | — | Yes | Typically **`Select.Trigger`** and **`Select.Content`** (non-**`native`**); **`Select.Item`** tree (**`native`**) |
+
+### Select.Trigger
+
+`forwardRef` to the underlying **`button`**. Props omit **`id`**, **`type`**, and **`role`** (set by the implementation).
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | No | Usually **`Select.Value`** and optionally **`Select.TriggerIcon`** |
+| className | `string` | — | No | Additional class on the button |
+| disabled | `boolean` | — | No | Native disabled; final state also respects **`Select.Root`** **`disabled`** |
+| ref | `React.Ref<HTMLButtonElement>` | — | No | Ref to the button element |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "id" \| "type" \| "role">` | — | No | e.g. **`aria-label`**, **`aria-labelledby`**, event handlers |
+
+### Select.Value
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the value / placeholder span |
+
+### Select.TriggerIcon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | No | Icon or other content to the left of the value |
+| className | `string` | — | No | Wrapper class |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other **`span`** attributes |
+
+### Select.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the portaled listbox container |
+| children | `React.ReactNode` | — | Yes | Items, groups, and separators (listbox portal stays mounted; hidden while closed) |
+
+### Select.Item
+
+`forwardRef` to the option root **`div`**.
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Submitted / controlled string value |
+| label | `string` | — | No | Text shown in the trigger; otherwise derived from non-icon children or **`value`** |
+| disabled | `boolean` | — | No | Option not selectable |
+| className | `string` | — | No | Class on the option row |
+| children | `React.ReactNode` | — | Yes | Label content and optional **`Select.ItemIcon`** |
+| ref | `React.Ref<HTMLDivElement>` | — | No | Ref on the option root |
+
+### Select.ItemIcon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | No | Icon before the item text |
+| className | `string` | — | No | Wrapper class |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other **`span`** attributes |
+
+### Select.Group
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the **`role="group"`** container |
+| children | `React.ReactNode` | — | No | Group label and items |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other **`div`** attributes |
+
+### Select.GroupLabel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the label |
+| children | `React.ReactNode` | — | No | Group heading text |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other **`div`** attributes |
+
+### Select.Separator
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the **`hr`** |
+| …rest | `React.HTMLAttributes<HTMLHRElement>` | — | No | Other **`hr`** attributes |
+
+## Related
+
+- [Label](../label/COMPONENT.md) — visible field label; pair with **`aria-labelledby`** on **`Select.Trigger`** when needed.
+- [Hint](../hint/COMPONENT.md) — helper or error text below the field.
+- [Input](../input/COMPONENT.md) — free-form text when a fixed list is not appropriate.
+- [Dropdown](../dropdown/COMPONENT.md) — action menus, not single form values.
+- [Modal](../modal/COMPONENT.md) / [Drawer](../drawer/COMPONENT.md) — nested focus and stacking when the select sits inside overlays.

package/src/components/select/examples/01-country.tsx

@@ -0,0 +1,35 @@
+import { Label, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Shipping address: visible label + combobox; `Select.Trigger` has no public `id` — pair with
+ * `aria-labelledby` on the trigger.
+ */
+export default function SelectExampleCountry() {
+  const countryLabelId = React.useId();
+
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="body-small" tone="muted" className={styles.caption}>
+        Select a country for tax and delivery estimates.
+      </Typography.Root>
+      <div className={styles.field}>
+        <Label.Root id={countryLabelId}>Country or region</Label.Root>
+        <Select.Root defaultValue="us" placeholder="Choose a country">
+          <Select.Trigger aria-labelledby={countryLabelId}>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="us">United States</Select.Item>
+            <Select.Item value="ca">Canada</Select.Item>
+            <Select.Item value="gb">United Kingdom</Select.Item>
+            <Select.Item value="de">Germany</Select.Item>
+            <Select.Item value="jp">Japan</Select.Item>
+          </Select.Content>
+        </Select.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/select/examples/02-controlled.tsx

@@ -0,0 +1,33 @@
+import { Label, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled `value` / `onChange`: parent owns the string; map enums or numbers yourself.
+ */
+export default function SelectExampleControlled() {
+  const [tier, setTier] = React.useState("pro");
+  const tierLabelId = React.useId();
+
+  return (
+    <div className={styles.stack}>
+      <div className={styles.field}>
+        <Label.Root id={tierLabelId}>Subscription tier</Label.Root>
+        <Select.Root value={tier} onChange={setTier} placeholder="Choose a tier">
+          <Select.Trigger aria-labelledby={tierLabelId}>
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            <Select.Item value="free">Free</Select.Item>
+            <Select.Item value="pro">Pro</Select.Item>
+            <Select.Item value="team">Team</Select.Item>
+          </Select.Content>
+        </Select.Root>
+      </div>
+      <Typography.Root as="p" variant="caption" tone="muted" className={styles.caption}>
+        Current value in React state: <span>{tier}</span>
+      </Typography.Root>
+    </div>
+  );
+}

package/src/components/select/examples/03-groups.tsx

@@ -0,0 +1,43 @@
+import { Label, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Long lists: `Select.Group`, `Select.GroupLabel`, and `Select.Separator` inside `Select.Content`.
+ */
+export default function SelectExampleGroups() {
+  const timezoneLabelId = React.useId();
+
+  return (
+    <div className={styles.field}>
+      <Label.Root id={timezoneLabelId}>Time zone</Label.Root>
+      <Select.Root defaultValue="utc" placeholder="Select time zone">
+        <Select.Trigger aria-labelledby={timezoneLabelId}>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Group>
+            <Select.GroupLabel>Americas</Select.GroupLabel>
+            <Select.Item value="et">Eastern Time</Select.Item>
+            <Select.Item value="ct">Central Time</Select.Item>
+            <Select.Item value="pt">Pacific Time</Select.Item>
+          </Select.Group>
+          <Select.Separator />
+          <Select.Group>
+            <Select.GroupLabel>Europe</Select.GroupLabel>
+            <Select.Item value="utc">UTC</Select.Item>
+            <Select.Item value="cet">Central European Time</Select.Item>
+            <Select.Item value="gmt">GMT (London)</Select.Item>
+          </Select.Group>
+          <Select.Separator />
+          <Select.Group>
+            <Select.GroupLabel>Asia Pacific</Select.GroupLabel>
+            <Select.Item value="jst">Japan (JST)</Select.Item>
+            <Select.Item value="aest">Sydney (AEST)</Select.Item>
+          </Select.Group>
+        </Select.Content>
+      </Select.Root>
+    </div>
+  );
+}