prime-ui-kit 0.2.5 → 0.3.1

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

@@ -0,0 +1,86 @@
+# SegmentedControl
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A single-choice control: a horizontal `radiogroup` whose options are segment buttons, with a floating pill indicator under the active segment.
+
+- **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
+
+```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>
+  );
+}
+```
+
+## 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.
+
+## 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 |
+
+### SegmentedControl.Item
+
+| 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 |
+
+### SegmentedControl.Icon
+
+| 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 |
+
+## Related
+
+- [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.

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

@@ -0,0 +1,75 @@
+# SegmentedProgressBar
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+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.
+
+- **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).
+
+## Composition
+
+- **`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.
+
+### 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**; 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).
+
+## 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; 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). |
+| `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-tech segment label. |
+| `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.

package/src/components/select/COMPONENT.md

@@ -0,0 +1,175 @@
+# Select
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## 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.
+
+## 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.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.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
+
+```tsx
+import { Select } from "prime-ui-kit";
+
+export function Example() {
+  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>
+  );
+}
+```
+
+### Native `<select>` (`native`)
+
+```tsx
+import { Select } from "prime-ui-kit";
+
+export function NativeExample() {
+  return (
+    <Select.Root native size="m" 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.
+
+## 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.
+- **`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 | Trigger and list sizing tokens |
+| 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 |
+
+### 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/slider/COMPONENT.md

@@ -0,0 +1,62 @@
+# Slider
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Horizontal range control built on the native `input type="range"`, with optional text label and kit sizing (`s`–`xl`).
+
+- **Use** when the user should pick a number along a continuous or stepped interval (volume, brightness, percentages, temperature bands) and dragging the track is appropriate.
+- **Use** when native range keyboard and pointer behavior is sufficient and you want minimal custom logic.
+- **Do not use** for vertical sliders; the implementation is horizontal only.
+- **Do not use** when you need a value thumb label, icons, or other slots on the track—compose with surrounding layout and text.
+- **Do not use** expecting built-in error, required, loading, or read-only modes; handle those with form primitives and hints around the control.
+- **Do not use** when a small set of fixed choices fits radio or segmented controls better than a continuous range.
+
+## Composition
+
+- **`Slider`** is a single-part API: **`Slider.Root`** wraps **`ControlSizeProvider`**, an optional **`label`** (`label` + `htmlFor` linked to the input), and one **`input type="range"`** styled as the track.
+- The root `div` carries **`data-size`** from **`size`**; there are no other exported subcomponents.
+
+### Minimal example
+
+```tsx
+import { Slider } from "prime-ui-kit";
+
+export function Example() {
+  return <Slider.Root />;
+}
+```
+
+## Rules
+
+- **Controlled:** pass **`value`** and **`onChange`**; **uncontrolled:** pass **`defaultValue`** (or omit both value props—effective initial value is **`min`**, clamped to **`[min, max]`**).
+- **`min`**, **`max`**, and **`step`** default to **`0`**, **`100`**, and **`1`**; fractional **`step`** values are allowed.
+- Displayed value is **clamped** to **`[min, max]`**; if the browser emits a non-numeric value, the update is ignored.
+- With **`label`**, the visible label is associated with the input via **`id`** / **`htmlFor`**. Without **`label`**, set **`aria-label`** (or an external accessible name), or assistive technologies may not get a proper name.
+- **`disabled`** sets the native **`disabled`** state on the range input.
+- There is no **`asChild`** or portal behavior; focus and **`focus-visible`** styling follow the native control and theme.
+
+## API
+
+### Slider.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `number` | — | No | Controlled value |
+| defaultValue | `number` | — | No | Initial value when uncontrolled; if omitted, the internal initial value is `min` (clamped to `[min, max]`) |
+| min | `number` | `0` | No | Minimum value |
+| max | `number` | `100` | No | Maximum value |
+| step | `number` | `1` | No | Step increment (may be fractional) |
+| disabled | `boolean` | — | No | Disables the range input |
+| onChange | `(value: number) => void` | — | No | Called when the value updates |
+| label | `string` | — | No | Visible label above the track; wires `htmlFor` / `id` on the input |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track, thumb, and label scale |
+| className | `string` | — | No | Class on the root `div` |
+| aria-label | `string` | — | No | Accessible name when there is no `label` |
+
+## Related
+
+- [Label](../label/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)
+- [DigitInput](../digit-input/COMPONENT.md)

package/src/components/stepper/COMPONENT.md

@@ -0,0 +1,186 @@
+# Stepper
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Multi-step progress UI: a high-level **`Stepper`** on a semantic ordered list (`<ol>` / `<li>`), plus primitive **`HorizontalStepper`** and **`VerticalStepper`** layouts where each row owns an explicit visual **`state`**.
+
+- **Use** for wizards, checkout or form stages, and any flow where discrete steps should read clearly in order.
+- **Use** **`Stepper`** when **`currentStep`** (and optional per-step **`status`**) should drive numbering and completed/active/pending visuals.
+- **Use** **`HorizontalStepper`** / **`VerticalStepper`** when step logic lives in the app (store, API) and you set **`state`** on each **`Item`** yourself.
+- **Do not use** as a page hierarchy control; prefer breadcrumbs for site structure.
+- **Do not use** when a single continuous fraction matters more than discrete steps; consider a progress bar.
+- **Do not use** primitive rails alone when you need a native **ordered list** semantics for steps—wrap with appropriate roles/markup or use **`Stepper.Root`**.
+
+## Composition
+
+- **`Stepper.Root`** — `<ol>`; provides **`orientation`**, **`currentStep`**, **`size`**, and a per-render counter for automatic step indices. Children: **`Stepper.Step`** (alias **`Stepper.Item`**) and, in horizontal flows, **`Stepper.SeparatorIcon`** between steps.
+- **`Stepper.Step` / `Stepper.Item`** — `<li>` wrapping a **`<button>`**; supplies step context (**`status`**, **`index`**) to **`Indicator`** and **`Content`**. Optional **`Stepper.Arrow`** after content is common in **vertical** orientation.
+- **`Stepper.Indicator` / `Stepper.ItemIndicator`** — **`span`**; default shows **1-based index** or a checkmark when completed; **`aria-hidden`**. Maps high-level **`error`** to **`data-legacy-status="error"`** for styling.
+- **`Stepper.Content`** — title and optional description beside the indicator.
+- **`Stepper.SeparatorIcon`** — `<li>` with a chevron between horizontal steps (delegates to **`HorizontalStepper.SeparatorIcon`**).
+- **`Stepper.Arrow`** — vertical arrow icon (delegates to **`VerticalStepper.Arrow`**).
+- **`HorizontalStepper.Root`** — non-semantic **`div`** rail; children: **`SeparatorIcon`** and **`Item`** buttons, each with **`ItemIndicator`** inside.
+- **`VerticalStepper.Root`** — non-semantic **`div`** column; children: **`Item`** rows with **`ItemIndicator`**, label text, and optional **`Arrow`**.
+
+### Minimal example
+
+```tsx
+import { Stepper } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Stepper.Root>
+      <Stepper.Step>
+        <Stepper.Indicator />
+        <Stepper.Content title="Step one" />
+      </Stepper.Step>
+    </Stepper.Root>
+  );
+}
+```
+
+## Rules
+
+- **`Stepper.Root`**: **`currentStep`** defaults to **`0`**; indices before it are **`completed`**, equal index is **`active`**, after are **`pending`**. Override any step with **`status`** on **`Stepper.Step`** (e.g. **`error`**).
+- **`Stepper.Step`** without **`index`** consumes the next auto index in child order; mixing explicit **`index`** and auto indices requires careful ordering.
+- **`SeparatorIcon`** is intended for **`orientation="horizontal"`**; it is not the vertical connector pattern.
+- Primitives use **`StepperAlignItemState`**: **`default`** \| **`active`** \| **`completed`** only—no built-in **`error`**; use **`Stepper`** for **`error`** or custom indicator content.
+- Active step sets **`aria-current="step"`** on the **`Stepper`** step button; indicators and separators use **`aria-hidden`** where the label carries meaning—keep titles/descriptions meaningful for assistive tech.
+- **`HorizontalStepper`** / **`VerticalStepper`** do not emit **`<ol>`** / **`<li>`**; add list semantics externally if required.
+- Step transitions, validation, and routing are **app-owned**; the kit handles presentation and button interactions only.
+
+## API
+
+Exported types include **`StepStatus`**, **`StepperOrientation`**, **`StepperSize`**, and **`StepperAlignItemState`** (for primitives).
+
+### Stepper.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| orientation | `"horizontal" \| "vertical"` | `"vertical"` | No | Layout of the step list |
+| currentStep | `number` | `0` | No | Active step index for default statuses |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control tier for the subtree |
+| children | `React.ReactNode` | — | Yes | Steps and optional **`SeparatorIcon`** |
+| className | `string` | — | No | Class on **`<ol>`** |
+
+### Stepper.Step (Stepper.Item)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| index | `number` | auto | No | Step index for status and indicator |
+| status | `StepStatus` | from **`currentStep`** | No | **`pending`** \| **`active`** \| **`completed`** \| **`error`** |
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | **`button`** **`type`** |
+| disabled | `boolean` | — | No | Disables the step button |
+| className | `string` | — | No | Class on **`<button>`** |
+| children | `React.ReactNode` | — | Yes | Indicator, content, optional arrow |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">` | — | No | Other button attributes (**`ref`** supported) |
+
+### Stepper.Indicator (Stepper.ItemIndicator)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | index / checkmark | No | Custom indicator content |
+| className | `string` | — | No | Class on **`span`** |
+
+### Stepper.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| title | `string` | — | Yes | Primary label |
+| description | `string` | — | No | Secondary text |
+| className | `string` | — | No | Wrapper class |
+
+### Stepper.SeparatorIcon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the inner icon |
+
+### Stepper.Arrow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `IconChevronRight` | No | Icon component |
+| className | `string` | — | No | Class on the icon |
+| …rest | props of **`as`** | — | No | Forwarded to the icon |
+
+### HorizontalStepper.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control tier |
+| className | `string` | — | No | Class on **`div`** |
+| children | `React.ReactNode` | — | No | Rail content |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Container attributes |
+
+### HorizontalStepper.SeparatorIcon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `IconChevronRight` | No | Separator icon component |
+| className | `string` | — | No | Class on the SVG |
+| …rest | `Omit<React.ComponentPropsWithoutRef<T>, "as" \| "className">` | — | No | Forwarded to **`as`** |
+
+### HorizontalStepper.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| state | `StepperAlignItemState` | `"default"` | No | **`default`** \| **`active`** \| **`completed`** |
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | **`button`** **`type`** |
+| className | `string` | — | No | Class on **`<button>`** |
+| children | `React.ReactNode` | — | No | Indicator and label |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">` | — | No | Other button attributes (**`ref`** supported) |
+
+### HorizontalStepper.ItemIndicator
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| state | `StepperAlignItemState` | from context | No | Visual override |
+| className | `string` | — | No | Class on **`div`** |
+| children | `React.ReactNode` | checkmark when completed | No | Circle contents when not completed |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | **`div`** attributes |
+
+### VerticalStepper.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control tier |
+| className | `string` | — | No | Class on **`div`** |
+| children | `React.ReactNode` | — | No | Vertical items |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Container attributes |
+
+### VerticalStepper.Arrow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `IconChevronRight` | No | Icon component |
+| className | `string` | — | No | Class on the icon |
+| …rest | `Omit<React.ComponentPropsWithoutRef<T>, "as" \| "className">` | — | No | Forwarded to **`as`** |
+
+### VerticalStepper.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| state | `StepperAlignItemState` | `"default"` | No | Row state |
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | **`button`** **`type`** |
+| className | `string` | — | No | Class on **`<button>`** |
+| children | `React.ReactNode` | — | No | Indicator, text, optional arrow |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">` | — | No | Other button attributes (**`ref`** supported) |
+
+### VerticalStepper.ItemIndicator
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| state | `StepperAlignItemState` | from context | No | Indicator state |
+| className | `string` | — | No | Class on **`div`** |
+| children | `React.ReactNode` | checkmark when completed | No | Circle contents when not completed |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | **`div`** attributes |
+
+## Related
+
+- [Button](../button/COMPONENT.md) — next/back actions next to a controlled stepper
+- [Modal](../modal/COMPONENT.md) and [Drawer](../drawer/COMPONENT.md) — wizard shells
+- [Breadcrumb](../breadcrumb/COMPONENT.md) — hierarchy, not linear stages
+- [Progress bar](../progress-bar/COMPONENT.md) — continuous progress instead of discrete steps