prime-ui-kit 0.2.3 → 0.3.1

package/src/components/modal/COMPONENT.md

@@ -0,0 +1,105 @@
+# Modal
+
+## About
+
+Centered overlay dialog with a portal, backdrop, focus trap, scroll lock, and optional built-in header, body, and footer. `Modal.Panel` composes these pieces so consumers rarely touch internal layers.
+
+- **Use** for blocking confirmation, forms, or disclosures that need full attention and clear dismiss semantics.
+- **Use** when Escape, overlay click, and an explicit close control should all be able to dismiss the dialog (configurable on `Modal.Root`).
+- **Do not use** for non-blocking hints or menus; prefer lighter overlays (for example [Popover](../popover/COMPONENT.md)).
+- **Do not use** for edge-docked sheets; prefer [Drawer](../drawer/COMPONENT.md) when the pattern is a side panel.
+- **Do not use** nested modal stacks without extra focus and stacking discipline; the kit does not add a second modal layer API.
+
+## Composition
+
+- **`Modal.Root`** — holds open state (controlled via **`open`** / **`onOpenChange`** or uncontrolled via **`defaultOpen`**), and options **`closeOnEscape`** / **`closeOnOverlayClick`**. Renders **`children`** only (no DOM wrapper).
+- **`Modal.Trigger`** — optional; **`React.Children.only`**: pass **exactly one** React element; its **`onClick`** is merged to call **`onOpen`** when the event is not **`defaultPrevented`**.
+- **`Modal.Panel`** — when open: **`createPortal`** (default container `document.body`), fullscreen **`role="presentation"`** overlay, then **`role="dialog"`** with **`aria-modal="true"`**. If **`title`** is set, renders an internal header (**`h2`**, optional description, optional built-in close icon button), wraps **`children`** in an internal body, and optional **`footer`**. Without **`title`**, **`children`** render directly inside the dialog surface—supply **`aria-label`** or **`aria-labelledby`** (and **`aria-describedby`** when needed).
+- **`Modal.Close`** — same single-child contract as **`Trigger`**; merges **`onClick`** to **`onClose`** when not **`defaultPrevented`**. Typical placement: a control inside **`footer`**.
+- **Order:** **`Modal.Root`** → **`Modal.Trigger`** (if any) and **`Modal.Panel`** as siblings (or only **`Modal.Panel`** in controlled flows).
+
+### Minimal example
+
+```tsx
+import { Button, Modal } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root>Open</Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel title="Title">
+        <p>Content</p>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}
+```
+
+## Rules
+
+- **Shell tokens:** overlay padding, panel padding, gaps between header/body/footer, and max width use **`--prime-sys-size-modal-*`** (semantic `size.modal` in `tokens/semantic.ts`). Title/description text tiers may still follow control typography tokens where the chrome matches **`size`** `m`.
+- **Controlled:** omit **`Modal.Trigger`** and drive **`open`** / **`onOpenChange`** on **`Modal.Root`**; **`Modal.Panel`** still portals when **`open`** is true.
+- **Uncontrolled:** use **`defaultOpen`** or rely on **`Modal.Trigger`**; **`onOpenChange`** fires for any transition.
+- **`Modal.Trigger`** and **`Modal.Close`** require **exactly one** child element (**`cloneElement`**); fragments or multiple nodes are invalid.
+- **Accessibility:** with **`title`** / **`description`**, **`aria-labelledby`** / **`aria-describedby`** on the dialog are wired from the internal header. Without a visible title, set **`aria-label`** on **`Modal.Panel`** or valid **`aria-labelledby`** / **`aria-describedby`** yourself.
+- While open, siblings of the portal subtree on **`document.body`** get **`inert`** and **`aria-hidden="true"`** to hide background from assistive tech; restore runs on close.
+- **Focus:** focus is trapped inside the dialog while open; initial focus follows browser / trap behavior—ensure a focusable control or manage focus if the first paint is static text only.
+- **`showClose`** (default **`true`** when a header is shown) controls the header icon button; **`closeAriaLabel`** defaults to **`"Close"`**.
+- **`container`** on **`Modal.Panel`** overrides the portal target (for tests or custom stacking); default is **`document.body`**.
+- **`overlayClassName`**, **`footerClassName`**, **`bodyClassName`**, and **`bodyStyle`** target the overlay, **`<footer>`**, and body wrapper respectively; without **`title`**, **`bodyClassName`** / **`bodyStyle`** do not apply (no inner body wrapper).
+
+## API
+
+### Modal.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| open | `boolean` | — | No | Controlled open state |
+| defaultOpen | `boolean` | `false` | No | Initial open when uncontrolled |
+| onOpenChange | `(open: boolean) => void` | — | No | Fires when open state changes |
+| closeOnEscape | `boolean` | `true` | No | Whether Escape closes the dialog |
+| closeOnOverlayClick | `boolean` | `true` | No | Whether a direct backdrop click closes |
+| children | `React.ReactNode` | — | No | e.g. `Modal.Trigger` and `Modal.Panel` |
+
+### Modal.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement<{ onClick?: React.MouseEventHandler }>` | — | Yes | Single element whose `onClick` is composed with open |
+
+### Modal.Close
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement<{ onClick?: React.MouseEventHandler; className?: string; size?: "s" \| "m" \| "l" \| "xl" }>` | — | Yes | Single element whose `onClick` is composed with close |
+
+### Modal.Panel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| title | `React.ReactNode` | — | No | If set, builds header with `h2` and optional description |
+| description | `React.ReactNode` | — | No | Shown under the title when `title` is set |
+| icon | `React.ReactNode` | — | No | Icon slot in the header row |
+| showClose | `boolean` | `true` | No | Header close icon button when `title` is set |
+| closeAriaLabel | `string` | `"Close"` | No | `aria-label` for the header close control |
+| children | `React.ReactNode` | — | No | Main content; wrapped in internal body when `title` is set |
+| footer | `React.ReactNode` | — | No | Rendered in an internal `footer` |
+| container | `HTMLElement \| null` | — | No | Portal container; default `document.body` |
+| overlayClassName | `string` | — | No | Class on the fullscreen backdrop |
+| footerClassName | `string` | — | No | Class on the `footer` element |
+| bodyClassName | `string` | — | No | Class on the internal body when `title` is set |
+| bodyStyle | `React.CSSProperties` | — | No | Inline style on the internal body when `title` is set |
+| aria-label | `string` | — | No | Dialog name when there is no `title`-driven label |
+| aria-labelledby | `string` | — | No | Overrides auto wiring from the built-in header |
+| aria-describedby | `string` | — | No | Overrides auto wiring from the built-in description |
+| className | `string` | — | No | Class on the `role="dialog"` root |
+| style | `React.CSSProperties` | — | No | Style on the `role="dialog"` root |
+| …rest | `Omit<React.HTMLAttributes<HTMLDivElement>, "title">` | — | No | Other attributes forwarded to the dialog root |
+
+## Related
+
+- [Button](../button/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)
+- [Popover](../popover/COMPONENT.md)

package/src/components/notification/COMPONENT.md

@@ -0,0 +1,120 @@
+# Notification
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Toast notifications: `NotificationProvider` keeps a queue, hooks expose `notify` / `dismiss` / `dismissAll`, and cards render in a portal with stacked groups per corner and semantic type.
+
+- **Use** for short, non-blocking feedback after actions (save, send, background job finished) when you do not need to trap focus.
+- **Use** when the message should appear above the page chrome and auto-dismiss or offer a single secondary action.
+- **Use** `useNotificationStore` when the UI must read `items` (e.g. custom lists or bulk dismiss).
+- **Use** `NotificationCard` alone only for static previews or fully custom wiring; live toasts go through the provider and `notify`.
+- **Do not use** for errors that require a blocking decision, long forms, or primary workflow inside the toast—prefer [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), or [Banner](../banner/COMPONENT.md).
+- **Do not use** multiple nested `NotificationProvider`s unless you intentionally want several portals and duplicate zones.
+
+## Composition
+
+- **`NotificationProvider`** — wraps the tree that calls hooks; provides context and mounts a **portal** with a fixed viewport. Each screen **position** gets a **zone**; inside a zone, notifications are split into **stacks by `type`** (`success`, `error`, `warning`, `info`).
+- **`NotificationStack` / `NotificationStackItem`** (internal) — ordered list with Framer Motion; hovering expands the stack and sets **`paused`** on cards so countdown timers stop until collapse.
+- **`NotificationCard`** — root is an `article` with a live region role, leading icon, title row (optional **badge**), optional description, optional **action** (`Button.Root`), optional close control, and a progress track unless **`persistent`**.
+
+### Minimal example
+
+```tsx
+import { NotificationProvider, useNotifications } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <NotificationProvider>
+      <Notifier />
+    </NotificationProvider>
+  );
+}
+
+function Notifier() {
+  const { notify } = useNotifications();
+  return (
+    <button type="button" onClick={() => notify({ type: "info", title: "Hello" })}>
+      Notify
+    </button>
+  );
+}
+```
+
+## Rules
+
+- Call **`useNotifications`** or **`useNotificationStore`** only under **`NotificationProvider`**; both hooks throw if context is missing.
+- **`notify`** returns a string **`id`**; pass it to **`dismiss`** or use **`dismissAll`** for every active toast.
+- **`useNotificationStore`** exposes the same methods plus **`items`**: `NotificationRecord[]` of non-dismissing entries only (no internal closing-animation flag).
+- Options passed to **`notify`** are merged with defaults: **`size`** `"m"`, **`position`** from the provider, **`duration`** `5000` ms, **`persistent`** `false`, **`closable`** `true`.
+- With **`persistent`**, there is no auto-dismiss, no progress bar, and duration does not drive closing; users or **`dismiss`** / **`dismissAll`** must close the card. Visually, **`persistent`** also turns on the accent-tinted **border** and (unless **`prefers-reduced-motion`**) the **`notification-glow`** shadow pulse — default **`notify()`** uses **`persistent: false`**, so live toasts look flatter unless you opt in.
+- If **`duration <= 0`**, the countdown effect does not run—time-based auto-dismiss does not occur; close via **`dismiss`** or the close button when **`closable`**.
+- Stacks are keyed by **`position`** and **`type`**; **`max`** (default `5`) caps depth per stack—older items in that stack are dropped when exceeded.
+- **`type`** `error` and **`warning`** use **`role="alert"`** and **`aria-live="assertive"`**; other types use **`role="status"`** and **`aria-live="polite"`**.
+- Close control uses **`aria-label="Dismiss notification"`**; default type icons are **`aria-hidden`** inside the icon wrapper.
+- Each stack list has **`aria-label`** `Notifications at <position>`.
+- Nested **`NotificationProvider`** instances each render their own portal and zones—usually one root provider is enough.
+- **`NotificationCard`** is not connected to the store by itself; supply **`item`**, **`paused`**, and **`onDismiss`** and keep **`item`** fields consistent with **`NotificationRecord`**.
+
+## API
+
+### NotificationProvider
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Subtree where notification hooks are used |
+| position | `NotificationPosition` | `"top-right"` | No | Default **`position`** for **`notify`** when omitted in options |
+| max | `number` | `5` | No | Maximum items per stack (same **`position`** + **`type`**) |
+
+### NotificationOptions (`notify` payload)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"success" \| "error" \| "warning" \| "info"` | — | Yes | Semantics, default icon, and stack grouping |
+| title | `string` | — | Yes | Primary heading |
+| description | `string` | — | No | Secondary text |
+| size | `"s" \| "m" \| "l"` | `"m"` | No | Card scale |
+| position | `NotificationPosition` | provider default | No | Corner or edge anchor |
+| duration | `number` | `5000` | No | Auto-dismiss delay in ms (ignored for closing when **`persistent`**; see Rules when `<= 0`) |
+| persistent | `boolean` | `false` | No | Disable timer and progress UI |
+| icon | `React.ReactNode` | type default | No | Custom leading icon |
+| badge | `string \| number` | — | No | Label next to the title |
+| closable | `boolean` | `true` | No | Show dismiss button |
+| action | `{ label: string; onClick: () => void }` | — | No | Secondary action rendered as neutral stroke **`Button.Root`** |
+
+`notify` returns the new record’s **`id`** (`string`).
+
+### NotificationRecord
+
+All **`NotificationOptions`** fields plus required **`id`**, **`position`**, **`size`**, **`duration`**, **`persistent`**, **`closable`**, and **`createdAt`** (`number`, ms). Defaults are filled when the record is created inside **`notify`**.
+
+### NotificationCard
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| item | `NotificationRecord` | — | Yes | Card data |
+| paused | `boolean` | — | Yes | Pause countdown (e.g. expanded stack) |
+| onDismiss | `(id: string) => void` | — | Yes | Called to remove the toast (timer or UI) |
+| stackDepth | `number` | `0` | No | Stack index for layout / `data-*` |
+| stackExpanded | `boolean` | `false` | No | Whether the parent stack is expanded |
+| className | `string` | — | No | Extra class on the root `article` |
+
+### useNotifications()
+
+| Field | Type | Description |
+|------|------|-------------|
+| notify | `(options: NotificationOptions) => string` | Enqueue a notification |
+| dismiss | `(id: string) => void` | Dismiss one by id |
+| dismissAll | `() => void` | Dismiss all active |
+
+### useNotificationStore()
+
+Same **`notify`**, **`dismiss`**, and **`dismissAll`** as above, plus **`items`**: `NotificationRecord[]` (active only, excluding items in the exit-animation phase).
+
+## Related
+
+- [Banner](../banner/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)
+- [Modal](../modal/COMPONENT.md)

package/src/components/pagination/COMPONENT.md

@@ -0,0 +1,61 @@
+# Pagination
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Page navigation for chunked lists: previous and next controls with chevron icons, numeric page buttons, and ellipsis cells when there are many pages.
+
+- **Use** for server-driven or client-paged tables, search results, and any UI where the user moves between discrete page indices.
+- **Use** when you already know **`totalPages`** and can keep **`page`** in sync (controlled pattern).
+- **Do not use** as the only paging affordance when you rely on infinite scroll and never expose page numbers—this component assumes explicit pages.
+- **Do not use** when **`totalPages` is less than 1** and you still need a visible empty state; the root returns **`null`** in that case, so render a message or hide the bar in the parent.
+- **Do not use** expecting localized arrow or “Page N” strings from props; labels are fixed in the implementation (English).
+- **Do not use** if you must replace inner markup (custom arrows, slots); structure and **`Button`** wiring are fixed—extend or fork for deep customization.
+
+## Composition
+
+- **`Pagination`** is a single-part namespace: **`Pagination.Root`** only (exported as **`Pagination = { Root }`**).
+- **`Pagination.Root`** renders a **`nav`** with **`aria-label="Pagination"`**, **`data-size`**, and a row of controls: **previous** (ghost neutral **`Button`** with **`Button.Icon`**), a sequence of numeric page **`Button.Root`** cells or ellipsis **`span`**s (**`aria-hidden`**), then **next** (same as previous).
+- Page items use **`Button.Root`** with **`size`** from the root; the current page uses **`variant="primary"`** and **`mode="filled"`**; other numbers and arrows use **`variant="neutral"`** and **`mode="ghost"`**.
+
+### Minimal example
+
+```tsx
+import { Pagination } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Pagination.Root page={1} totalPages={5} onPageChange={() => {}} />
+  );
+}
+```
+
+## Rules
+
+- **Controlled only:** **`page`**, **`totalPages`**, and **`onPageChange`** are required; there is no uncontrolled mode.
+- **`page`** is clamped internally to **`1 … totalPages`** before rendering and when handling clicks.
+- If **`totalPages < 1`**, the component returns **`null`** (render nothing).
+- With **`totalPages ≤ 7`**, every page number is shown. With more pages, the row is shortened using **`siblingCount`** (default **`1`**) and ellipsis segments (**`…`**).
+- **First page:** previous control is **`disabled`**. **Last page:** next is **`disabled`**. **Single page:** both arrows are **`disabled`**.
+- The active page button sets **`aria-current="page"`**; other page buttons use **`aria-label={`Page ${n}`}`**; arrows use **“Previous page”** / **“Next page”**.
+- **`className`** merges onto the root **`nav`** only.
+- Syncing **`page`** to the URL, router, or query params is the responsibility of the parent.
+
+## API
+
+### Pagination.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| page | `number` | — | Yes | Current page; clamped to `1 … totalPages` for display and navigation |
+| totalPages | `number` | — | Yes | Page count; if `< 1`, renders nothing |
+| onPageChange | `(page: number) => void` | — | Yes | Called when the user selects a page or an arrow |
+| siblingCount | `number` | `1` | No | How many page indices to show on each side of the current page when `totalPages > 7` |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control and ellipsis scale (`--prime-sys-size-control-*`) |
+| className | `string` | — | No | Extra class on the root `nav` |
+
+## Related
+
+- [Button](../button/COMPONENT.md)
+- [DataTable](../data-table/COMPONENT.md)

package/src/components/popover/COMPONENT.md

@@ -0,0 +1,93 @@
+# Popover
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A composite “anchor + portaled panel”: clicking the trigger toggles a non-modal dialog next to the anchor, positioned toward the viewport edge and dismissible with Escape or an outside click.
+
+- **Use** for short contextual panels—help text, compact filters, a few fields or actions—without leaving the page or blocking the whole UI.
+- **Use** when content should stay visually tied to a specific control (metrics, footnotes, inline configuration).
+- **Do not use** for full-screen or blocking flows; prefer [Modal](../modal/COMPONENT.md).
+- **Do not use** for hover-only hints; prefer [Tooltip](../tooltip/COMPONENT.md).
+- **Do not use** expecting left/right placement relative to the anchor; only **top** and **bottom** sides are supported.
+- **Do not use** with multiple or fragment children under `Popover.Trigger`; exactly **one** element is supported.
+
+## Composition
+
+- **`Popover.Root`** — holds open state (controlled or uncontrolled), stable ids for trigger and content, and the trigger element ref used for positioning.
+- **`Popover.Trigger`** — must wrap **exactly one** `React` element; ref, `aria-*`, and click-to-toggle are merged onto that child (`cloneElement`).
+- **`Popover.Content`** — rendered in a **portal** only when open; root is a scroll container with `role="dialog"`, positioned from the trigger via `side` / `align`, wraps children in `ControlSizeProvider` when `size` is set, and applies optional **`insetPadding`** / **`insetGap`** on the same node (`data-inset-padding`, `data-inset-gap`).
+
+### Minimal example
+
+```tsx
+import { Popover } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <button type="button">Open</button>
+      </Popover.Trigger>
+      <Popover.Content insetPadding="x2" insetGap="x3">
+        Panel
+      </Popover.Content>
+    </Popover.Root>
+  );
+}
+```
+
+## Rules
+
+- **Uncontrolled:** use `defaultOpen` on `Popover.Root` for the initial open state after mount.
+- **Controlled:** pass `open` and `onOpenChange` together; parent can open or close from outside logic.
+- When closed, **`Popover.Content`** returns `null` (nothing is mounted in the portal).
+- **`trapFocus`** on `Popover.Content` keeps Tab cycling inside the panel while open and restores focus on close when enabled.
+- **Escape** and **outside click** call close; clicks on a portaled **Select** listbox that belongs to the panel are ignored as outside (see `isPortaledSelectListboxOwnedByContainer`).
+- **Non-modal:** `aria-modal={false}`—focus can leave the page; this is intentional for a lightweight overlay.
+- Trigger receives **`aria-expanded`**, **`aria-haspopup="dialog"`**, and **`aria-controls`** pointing at the content id; **`aria-labelledby`** on the panel references the trigger id—give the anchor a visible name or **`aria-label`** when there is no text.
+- There is no popover-level **`disabled`**; if the anchor (e.g. [Button](../button/COMPONENT.md)) is disabled, it will not open.
+- **`asChild`** exists for slot API compatibility; merging always applies to the single child—**`asChild={false}`** does not render an internal button.
+- Density: tune **`Popover.Content` `size`** for the control tier and **`insetPadding` / `insetGap`** for inner spacing; optional **`className`** on `Content` for further styling.
+
+## API
+
+### Popover.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| open | `boolean` | — | No | Controlled open state; use with `onOpenChange`. |
+| defaultOpen | `boolean` | `false` | No | Initial state in uncontrolled mode. |
+| onOpenChange | `(open: boolean) => void` | — | No | Fires when opening or closing (trigger, Escape, outside click). |
+| children | `React.ReactNode` | — | Yes | Typically `Popover.Trigger` and `Popover.Content`. |
+
+### Popover.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement` | — | Yes | Single anchor element; ref, ARIA, and click handler are merged in. |
+| asChild | `boolean` | `true` | No | Reserved for slot API compatibility; behavior always merges with the single child. |
+
+### Popover.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| align | `"start" \| "center" \| "end"` | `"start"` | No | Horizontal alignment of the panel relative to the trigger. |
+| side | `"bottom" \| "top"` | `"bottom"` | No | Preferred side; layout may flip at the viewport edge. |
+| sameMinWidthAsTrigger | `boolean` | `false` | No | Panel min width matches the trigger (`border-box`), still subject to panel max width and viewport. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control density tier for nested controls via `ControlSizeProvider`. |
+| trapFocus | `boolean` | `false` | No | Trap focus inside the panel while open. |
+| insetPadding | `"none" \| "x1" \| "x2" \| "x3"` | `"none"` | No | Extra inset padding relative to the panel tier (`data-inset-padding`). |
+| insetGap | `"none" \| "x2" \| "x3" \| "x4"` | `"none"` | No | Vertical gap between direct children (`data-inset-gap`). |
+| className | `string` | — | No | Extra class on the panel root. |
+| children | `React.ReactNode` | — | Yes | Panel body. |
+
+## Related
+
+- [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md) — typical triggers.
+- [Select](../select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md) — nested overlays; Select listbox clicks are treated as inside the popover when owned by the panel.
+- [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md) — fields inside the panel.
+- [Typography](../typography/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — text and labels in the panel.
+- [Modal](../modal/COMPONENT.md) — blocking modal flow.
+- [Tooltip](../tooltip/COMPONENT.md) — short hover/focus hint without an action panel.

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

@@ -0,0 +1,59 @@
+# ProgressBar
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A horizontal completion indicator built on the native `progress` element: fill is driven by `value` and `max`, with optional text label and `size` for track density.
+
+- **Use** for determinate tasks—uploads, downloads, or any operation where progress maps to a numeric range.
+- **Use** in multi-step flows when the user should see how far they are through a bounded sequence (steps, checklist, wizard).
+- **Use** with a `label` when the bar needs a short visible name tied to the meter for assistive tech.
+- **Do not use** for indeterminate or endless “busy” feedback; this API always requires a numeric `value` (use a spinner or another pattern instead).
+- **Do not use** for vertical or circular meters; the track is horizontal only—for a circular indicator in the kit, see Related.
+- **Do not use** expecting extra native attributes on the inner `progress`; they are not forwarded—wrap the component if you need custom markup.
+
+## Composition
+
+- **`ProgressBar`** is a single-part namespace: only **`ProgressBar.Root`** is public.
+- **`ProgressBar.Root`** renders a wrapper `div` with `data-size`, an optional **`label`** as a `span` with a generated `id`, and a native **`<progress>`** for the track. The bar spans the full width of its container.
+
+### Minimal example
+
+```tsx
+import { ProgressBar } from "prime-ui-kit";
+
+export function Example() {
+  return <ProgressBar.Root value={40} max={100} />;
+}
+```
+
+## Rules
+
+- **`value`** is required and clamped to **`[0, max]`**; negative values become `0`, values above `max` become `max`.
+- **`max`** defaults to **`100`**; if **`max <= 0`**, the implementation uses **`100`** as the effective maximum.
+- **`size`** defaults to **`m`**; allowed values are **`s`**, **`m`**, **`l`**, **`xl`** (`ProgressBarSize`).
+- There is no **`disabled`**, **`loading`**, or **`error`** prop—mute or hide the block at the screen level if needed.
+- Native **`progress`** exposes the **`progressbar`** role with **`value`** / **`max`** to the accessibility tree; with **`label`**, **`aria-labelledby`** points at the label element.
+- The bar is not interactive and is not keyboard-focusable; keep focus on real controls nearby.
+- “Controlled” usage is just React state passed into **`value`**; there is no separate uncontrolled mode with an internal store.
+
+## API
+
+### ProgressBar.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `number` | — | Yes | Current value; clamped to `[0, max]` after `max` is normalized. |
+| `max` | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used. |
+| `label` | `string` | — | No | Text above the track; when set, the progress element gets `aria-labelledby` referencing the label. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height and label typography scale. |
+| `className` | `string` | — | No | Class on the outer wrapper around the label and `progress`. |
+| `ref` | `React.Ref<HTMLProgressElement>` | — | No | Ref to the native `progress` element. |
+
+## Related
+
+- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — stacked proportional segments (e.g. status mix) instead of a single value.
+- [ProgressCircle](../progress-circle/COMPONENT.md) — circular determinate indicator when layout calls for a ring or compact numeric emphasis.
+- [Typography](../typography/COMPONENT.md) — headings and supporting copy around a status block.
+- [Button](../button/COMPONENT.md) — cancel, pause, or actions next to the bar.

package/src/components/progress-circle/COMPONENT.md

@@ -0,0 +1,63 @@
+# ProgressCircle
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Circular progress indicator: an SVG ring with `progressbar` semantics and optional centered content inside the ring.
+
+- **Use** when you need a compact fraction of a known maximum (percent, steps, seats vs capacity) in a round layout.
+- **Use** with **`max`** when the scale is not 0–100 (e.g. 12 months, 60 seats).
+- **Use** **`children`** for a short label or number in the center when it should match the visual focus of the ring.
+- **Do not use** for indeterminate or endless loading without a numeric fraction; there is no indeterminate mode in the API.
+- **Do not use** as the primary focus target or form control; the SVG is informational and not keyboard-focusable.
+- **Do not use** expecting a polymorphic root or `asChild`; the implementation is a fixed wrapper with SVG plus optional inner slot.
+
+## Composition
+
+- **`ProgressCircle`** exposes **`Root`** only (`ProgressCircle.Root`).
+- **`ProgressCircle.Root`** — root `div` (`inline-flex`), sets **`data-size`** and a CSS variable for the inner slot size.
+- **SVG** — **`role="progressbar"`** with track and fill circles; fill length follows **`value`** / **`max`**.
+- **Optional `children`** — when present, rendered in an inner container centered over the ring; omit when the ring alone is enough.
+
+### Minimal example
+
+```tsx
+import { ProgressCircle } from "prime-ui-kit";
+
+export function Example() {
+  return <ProgressCircle.Root value={40} />;
+}
+```
+
+## Rules
+
+- Progress is **always driven by props**: pass **`value`** on each render; there is no internal stored progress state.
+- **`value`** is clamped to **`[0, max]`**; negative values become `0`, values above **`max`** become **`max`**.
+- If **`max <= 0`**, the implementation uses **`100`** as the scale to avoid division by zero.
+- Set **`label`** when the SVG needs an accessible name and the center has no suitable visible text (it maps to **`aria-label`** on the SVG).
+- The SVG exposes **`aria-valuenow`**, **`aria-valuemin={0}`**, and **`aria-valuemax`** equal to the effective maximum.
+- There are no **`disabled`**, **`loading`**, or **`error`** props; reflect those with surrounding UI or by freezing **`value`** updates.
+- Root is **`inline-flex`** and does not stretch to full width; place it inside your own flex or grid layout when aligning with other content.
+- One visual style only; scale appearance with **`size`** (`s`–`xl` from progress-circle primitives).
+
+## API
+
+### ProgressCircle.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `number` | — | Yes | Current value; clamped to `[0, max]` |
+| max | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Diameter and stroke width from `progressCircle` primitives |
+| label | `string` | — | No | Accessible name for the SVG (`aria-label`) |
+| children | `React.ReactNode` | — | No | Centered content inside the ring |
+| className | `string` | — | No | Extra class on the root `div` |
+| ref | `React.Ref<HTMLDivElement>` | — | No | Ref on the root `div` |
+
+## Related
+
+- [ProgressBar](../progress-bar/COMPONENT.md) — linear fraction of a maximum when a horizontal bar fits better.
+- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple proportional segments on one track.
+- [Typography](../typography/COMPONENT.md) — captions and units beside or around the ring.
+- [Button](../button/COMPONENT.md) — cancel, retry, or other actions next to a long-running task.

package/src/components/radio/COMPONENT.md

@@ -0,0 +1,95 @@
+# Radio
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A compound radio control: a field wrapper, a [Label](../label/COMPONENT.md) row with a native `input type="radio"` and decorative marker, plus optional [Hint](../hint/COMPONENT.md) and error text wired to `aria-describedby` and invalid state.
+
+- **When to use** — exactly one choice from a set of mutually exclusive options that submit with the form (`name`, `value`, `required`).
+- **When to use** — grouped options that should behave as a single native radio group (same `name` on each `Radio.Root`).
+- **When to use** — hint or inline validation aligned under the label column.
+- **When not to use** — multiple independent toggles or “select many” lists (prefer [Checkbox](../checkbox/COMPONENT.md)).
+- **When not to use** — a single binary on/off setting where a switch matches the product language (prefer [Switch](../switch/COMPONENT.md)).
+- **When not to use** — a compact segmented bar of modes in one control (prefer [Segmented control](../segmented-control/COMPONENT.md)).
+- **When not to use** — you need `asChild` or fully custom markup; the marker and label row are fixed by the implementation.
+
+## Composition
+
+- **`Radio.Root`** — `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`; provides context and `ControlSizeProvider` for child parts (`inputId`, hint/error ids, `describedBy`, registration for hint/error slots).
+- **`Radio.Label`** — [Label](../label/COMPONENT.md) with `htmlFor` tied to the input id; contains the native `input[type=radio]`, decorative SVG rings, and optional text in a trailing column.
+- **`Radio.Hint`** — optional; registers presence so its id is merged into the input’s `aria-describedby`; uses disabled hint variant when the root is `disabled`.
+- **`Radio.Error`** — optional; error-styled message and registers invalid state (same as `variant="error"` on the root for styling).
+- **Order:** `Root` → `Label` → `Hint` and/or `Error` when needed. Public API: `Radio` with `Root`, `Label`, `Hint`, `Error`.
+
+### Minimal example
+
+```tsx
+import { Radio } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Radio.Root name="option" value="a">
+      <Radio.Label>Option</Radio.Label>
+    </Radio.Root>
+  );
+}
+```
+
+## Rules
+
+- Support **controlled** (`checked` + `onChange`) and **uncontrolled** (`defaultChecked`); forward standard input change semantics from the native radio.
+- Build a **group** with multiple **`Radio.Root`** instances sharing the same **`name`**; wrap in **`fieldset`** / **`legend`** when the group needs a visible or programmatic heading.
+- There is **no** separate `RadioGroup` component—selection is native HTML behavior or your own controlled state.
+- **`variant="error"`** or a mounted **`Radio.Error`** sets **`aria-invalid`** on the input and error styling on the root; **`disabled`** disables the input and dims the label/hint treatment.
+- **`aria-describedby`** on the root is merged with hint and error ids when those slots mount.
+- Set **`aria-label`** or ensure visible label text when **`Radio.Label`** has no readable children (icon-only or empty label).
+- **`Radio.Root`** **`ref`** is forwarded to the **native `input`** element.
+- DOM **`type`** is always **`radio`**; the design-system **`size`** prop lives on **`Radio.Root`** and does not map to the HTML `size` attribute (that key is omitted from input props).
+
+## API
+
+### Radio.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"default" \| "error"` | `"default"` | no | Error styling and `data-invalid` when `error` or when `Radio.Error` is mounted. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Marker, typography, and hint/error scale. |
+| id | `string` | auto (`useId`) | no | Input id; paired with `Radio.Label` via `htmlFor`. |
+| className | `string` | — | no | Class on the field wrapper `div`. |
+| disabled | `boolean` | — | no | Disables the input and label row. |
+| aria-describedby | `string` | — | no | Combined with hint and error ids when those slots exist. |
+| children | `React.ReactNode` | — | no | Typically `Label`, optional `Hint` / `Error`. |
+| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native radio input. |
+| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | no | Other native attributes on the `input` (e.g. `name`, `value`, `checked`, `defaultChecked`, `onChange`, `required`, `readOnly`, `form`). `type` is always `radio`. |
+
+### Radio.Label
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Label text beside the marker; omit only if an accessible name is set on the root input via remaining root props (e.g. `aria-label`). |
+| className | `string` | — | no | Class on the label row. |
+| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; `htmlFor` and `size` come from context. |
+
+### Radio.Hint
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Supplementary text below the label. |
+| className | `string` | — | no | Additional class on the hint slot. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally. |
+
+### Radio.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error message text. |
+| className | `string` | — | no | Additional class on the error slot. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally for `aria-describedby`. |
+
+## Related
+
+- [Checkbox](../checkbox/COMPONENT.md) — independent or multi-select toggles.
+- [Switch](../switch/COMPONENT.md) — binary setting with a different control pattern.
+- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives used inside Radio; pair with [Input](../input/COMPONENT.md) in larger forms.
+- [Segmented control](../segmented-control/COMPONENT.md) — compact mode switching in one bar.