prime-ui-kit 0.2.5 → 0.3.1

package/src/components/switch/COMPONENT.md

@@ -0,0 +1,98 @@
+# Switch
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A compound on/off control: a native `input type="checkbox"` with `role="switch"`, a visual track and thumb, and optional slots for label text, hint, and error wired through `aria-describedby` and invalid state.
+
+- **When to use** — binary settings (notifications, feature flags, consent) where the UI should read as on/off rather than a small checkbox in a list.
+- **When to use** — forms that need `name`, `value`, or `required` on the underlying input together with hint or error copy under the label column.
+- **When to use** — a single independent toggle per row; state is obvious from the thumb position and `aria-checked`.
+- **When not to use** — picking exactly one option from mutually exclusive alternatives (prefer [Radio](../radio/COMPONENT.md)).
+- **When not to use** — lists with partial selection or an **indeterminate** state (prefer [Checkbox](../checkbox/COMPONENT.md)).
+- **When not to use** — you need `asChild` or fully custom markup; the structure is fixed to `Switch.*` parts and [Label](../label/COMPONENT.md) / [Hint](../hint/COMPONENT.md) primitives.
+
+## Composition
+
+- **`Switch.Root`** — field wrapper `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`, `data-checked`, `data-readonly`; provides context and **`ControlSizeProvider`** for child parts. Renders **`children` only** (no shortcut that replaces **`Switch.Label`**).
+- **`Switch.Label`** — **`Label.Root`** row: the native switch **`input`**, the decorative **`track`**, and optional label copy; **`htmlFor`** / **`size`** come from context; **`ref`** on **`Root`** is forwarded to this **`input`**.
+- **`Switch.Hint`** — optional; registers hint text and contributes its id to **`aria-describedby`**; uses a dimmed hint variant when the field is **`disabled`**.
+- **`Switch.Error`** — optional; error-styled **[Hint](../hint/COMPONENT.md)** and registers invalid state when mounted (with **`variant="error"`** on **`Root`** when you want error chrome without the slot).
+- **Order:** **`Root`** → **`Label`** (required for the control to exist) → **`Hint`** / **`Error`** below when needed. Public API: **`Switch`** with **`Root`**, **`Label`**, **`Hint`**, **`Error`**.
+
+### Minimal example
+
+```tsx
+import { Switch } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Switch.Root defaultChecked name="reminders">
+      <Switch.Label>Deadline reminders</Switch.Label>
+    </Switch.Root>
+  );
+}
+```
+
+## Rules
+
+- **Controlled:** pass **`checked`** with **`onCheckedChange`**. **Uncontrolled:** use **`defaultChecked`** (defaults to **`false`**). User toggles run through the internal change handler; **`onChange`** on **`Root`** is not the switch API—use **`onCheckedChange`** only.
+- **`readOnly`** calls **`preventDefault`** in the change handler so the value does not change on click; **`aria-readonly`** is set on the input.
+- **`variant="error"`** or a mounted **`Switch.Error`** sets **`invalid`** in context, **`aria-invalid`** on the input, and error styling; **`disabled`** disables the input and adjusts hint styling.
+- **`aria-describedby`** on **`Root`** is merged with hint and error ids when those slots are mounted; add your own ids in **`aria-describedby`** if you need extra descriptors.
+- **`Switch.Label`** with no visible **`children`** leaves only the track; set an accessible name with **`aria-label`** or **`aria-labelledby`** on **`Root`** (or ensure context from nearby text).
+- The public props type includes **`label?: React.ReactNode`**, but **`Root`** does not render it as **`Switch.Label`**—always compose **`Switch.Label`** (and optional **`Hint`** / **`Error`**) as **`children`**.
+- Keyboard and role follow the native checkbox pattern with **`role="switch"`** and **`aria-checked`**; focus visibility uses **`focus-visible`** on the track.
+- There is no **indeterminate** or **loading** state; **`size`** on **`Root`** drives layout tokens, not a DOM **`size`** attribute on the input.
+
+## API
+
+### Switch.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Track and thumb scale from switch tokens. |
+| variant | `"default" \| "error"` | `"default"` | no | Error styling; **`invalid`** is also true when **`Switch.Error`** is mounted. |
+| checked | `boolean` | — | no | Controlled on state. |
+| defaultChecked | `boolean` | `false` | no | Initial on state when uncontrolled. |
+| onCheckedChange | `(checked: boolean) => void` | — | no | Called after the checked value changes from user input. |
+| disabled | `boolean` | — | no | Disables the input; **`data-disabled`** on the field root. |
+| readOnly | `boolean` | — | no | Prevents toggling; **`data-readonly`** and **`aria-readonly`**. |
+| label | `React.ReactNode` | — | no | Present on the type only; not used to render **`Switch.Label`**—compose **`Switch.Label`** as a child instead. |
+| id | `string` | auto (`useId`) | no | Stable input id; paired with **`Switch.Label`** via **`htmlFor`**. |
+| className | `string` | — | no | Class on the field wrapper **`div`**. |
+| aria-describedby | `string` | — | no | Combined with hint and error ids when those slots exist. |
+| children | `React.ReactNode` | — | no | Typically **`Switch.Label`** and optional **`Switch.Hint`** / **`Switch.Error`**. |
+| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native **`input`**. |
+| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | no | Other native attributes forwarded to the **`input`** (e.g. **`name`**, **`value`**, **`required`**, **`autoFocus`**, **`aria-*`**). **`type`** is always **`checkbox`**. |
+
+### Switch.Label
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | no | Text beside the switch; omit only when an accessible name is provided elsewhere. |
+| className | `string` | — | no | Class on the label row. |
+| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; **`htmlFor`** and **`size`** are managed internally. |
+
+### Switch.Hint
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Supplementary text below the label. |
+| className | `string` | — | no | Class on the hint slot. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; **`id`** is managed internally. |
+
+### Switch.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error message text. |
+| className | `string` | — | no | Class on the error block. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; **`id`** is managed internally. |
+
+## Related
+
+- [Checkbox](../checkbox/COMPONENT.md) — groups, **indeterminate**, and checkbox semantics.
+- [Radio](../radio/COMPONENT.md) — one selected option from a set.
+- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives inside the switch; pair with [Input](../input/COMPONENT.md) in larger forms.

package/src/components/tabs/COMPONENT.md

@@ -0,0 +1,114 @@
+# Tabs
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Compound tabs: a `tablist` of triggers, an animated indicator, and one visible `tabpanel` at a time. Values on `Tabs.Tab` and `Tabs.Panel` must align so the active pair matches.
+
+- **Use** to switch sections on a single view (settings areas, product details blocks, dashboard sub-views) without route changes.
+- **Use** controlled `value` / `onValueChange` when the active tab must follow URL, store, or wizard step.
+- **Use** `orientation="vertical"` for a sidebar-style tab rail next to content.
+- **Do not use** for primary page-to-page navigation; prefer links and routes (see [Breadcrumb](../breadcrumb/COMPONENT.md) for hierarchy).
+- **Do not use** for two to four lightweight mutually exclusive options without rich panels; consider [SegmentedControl](../segmented-control/COMPONENT.md).
+- **Do not use** expecting inactive panel subtrees to stay mounted; hidden panels are not rendered (see Rules).
+
+## Composition
+
+- **`Tabs.Root`** — context wrapper (`div` with `data-orientation`, `data-size`). Put **`Tabs.List`** and **`Tabs.Panel`** nodes as direct structure; order in the tree is list first, then panels (typical reading order).
+- **`Tabs.List`** — `role="tablist"` with `aria-orientation`, keyboard handling, internal indicator, and **`ControlSizeProvider`** for descendants. Children should be **`Tabs.Tab`** triggers only.
+- **`Tabs.Tab`** — `role="tab"` / `button type="button"`. Optional **`Tabs.Icon`** (before label) and **`Tabs.Label`** for text; `value` must match a **`Tabs.Panel`** `value`.
+- **`Tabs.Panel`** — `role="tabpanel"`; renders **only** when its `value` equals the root’s active value.
+
+### Minimal example
+
+```tsx
+import { Tabs } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Tabs.Root defaultValue="a">
+      <Tabs.List>
+        <Tabs.Tab value="a">
+          <Tabs.Label>Tab</Tabs.Label>
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="a">Panel content</Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+## Rules
+
+- **Uncontrolled:** omit `value`, set `defaultValue` on `Tabs.Root` (implementation default for `defaultValue` is `""` if omitted). **Controlled:** pass `value` and `onValueChange`; state follows `useControllableState` semantics.
+- **Disabled tabs:** `disabled` on `Tabs.Tab` sets native `disabled`, `data-disabled`, and excludes the tab from arrow-key traversal; disabled targets are skipped.
+- **Keyboard** (focus inside `Tabs.List`): **ArrowLeft** / **ArrowRight** in horizontal mode, **ArrowUp** / **ArrowDown** in vertical mode; **Home** / **End** move to first / last **enabled** tab; focus moves to the newly selected tab after arrow navigation.
+- **Focus order:** the selected tab has `tabIndex={0}`; others use `tabIndex={-1}`.
+- **ARIA:** `aria-controls` / `aria-labelledby` wire tab buttons to panels; list `aria-orientation` mirrors `orientation`.
+- **`Tabs.Icon`** sets `aria-hidden="true"` on the wrapper span; ensure the tab still has a clear name (e.g. `Tabs.Label` or visible text).
+- **Inactive panels:** `Tabs.Panel` returns `null` when inactive—avoid putting expensive trees in panels without app-level lazy loading or conditional data fetching.
+- **No `asChild`:** each tab is always a `<button>`; there is no built-in URL synchronization.
+- **Pairs:** for every panel `value` you expose, provide a corresponding tab (and vice versa) so the tab/panel relationship stays consistent for assistive tech.
+- **Layout:** full-width or custom layout is achieved with `className` and your own flex/grid CSS on the root, list, or tabs—there is no dedicated “full width” prop.
+
+## API
+
+### Tabs.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | No | Active tab id (controlled) |
+| defaultValue | `string` | `""` | No | Initial active tab when uncontrolled |
+| onValueChange | `(value: string) => void` | — | No | Called when the active tab changes |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | No | Tab list axis and arrow-key mapping |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger and panel typography scale |
+| children | `React.ReactNode` | — | Yes | `Tabs.List` and `Tabs.Panel` (and related structure) |
+| className | `string` | — | No | Class on the root `div` |
+
+### Tabs.List
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Typically `Tabs.Tab` elements |
+| className | `string` | — | No | Class on the tablist container |
+
+### Tabs.Tab
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Id matching the associated `Tabs.Panel` |
+| disabled | `boolean` | `false` | No | Non-interactive; skipped in keyboard roving |
+| children | `React.ReactNode` | — | Yes | Trigger content (e.g. `Tabs.Icon`, `Tabs.Label`) |
+| className | `string` | — | No | Class on the `button` |
+
+### Tabs.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon glyph |
+| className | `string` | — | No | Class on the `span` |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other span attributes |
+
+### Tabs.Label
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Label text |
+| className | `string` | — | No | Class on the `span` |
+| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other span attributes |
+
+### Tabs.Panel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Must match the active `Tabs.Tab` `value` to render |
+| children | `React.ReactNode` | — | Yes | Panel body |
+| className | `string` | — | No | Class on the panel `div` |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)
+- [Breadcrumb](../breadcrumb/COMPONENT.md)
+- **Icon** — use inside `Tabs.Icon` for glyphs sized with the tab control tokens

package/src/components/tag/COMPONENT.md

@@ -0,0 +1,67 @@
+# Tag
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A compact chip-style label: optional leading icon (`Tag.Icon`), optional removable close control when `onRemove` is set. Root is a `span` with `data-size` / `data-disabled`; the inner body wraps children in `ControlSizeProvider` so nested icons pick up the same control size tier.
+
+- **Use** for filter chips, selected values (recipients, skills), or metadata labels where space is tight and optional one-click removal helps.
+- **Use** `Tag.Icon` when a small icon should align with tag typography and scale with `size`.
+- **Do not use** as a toggle or single-choice control; use [Checkbox](../checkbox/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), or [Select](../select/COMPONENT.md).
+- **Do not use** when the whole chip must navigate or submit a primary action; prefer [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
+- **Do not use** expecting localized copy for the remove button without wrapping; the built-in remove `aria-label` is fixed to `"Remove"` in source.
+- **Do not use** as a status/count pill without removal semantics when [Badge](../badge/COMPONENT.md) fits better.
+
+## Composition
+
+- **`Tag.Root`** — outer `span`; holds a **`span`** body with **`ControlSizeProvider`** around **`children`**, then an optional remove **`button`** when **`onRemove`** is defined. Put plain text, **`Tag.Icon`**, or other nodes inside **`Tag.Root`**; place **`Tag.Icon`** before text when both are used so the icon sits on the left.
+- **`Tag.Icon`** — wrapper **`span`** for the icon node; inherits size from the surrounding **`Tag.Root`** context.
+
+### Minimal example
+
+```tsx
+import { Tag } from "prime-ui-kit";
+
+export function Example() {
+  return <Tag.Root>Label</Tag.Root>;
+}
+```
+
+## Rules
+
+- Omit **`size`** to follow the nearest ancestor **`ControlSizeProvider`**; context **`xs`** maps to tag size **`s`**. With no provider and no **`size`**, the effective size is **`m`**.
+- **`onRemove`** is optional; when present, a **`type="button"`** remove control is rendered with **`aria-label="Remove"`** and **`aria-hidden`** on the cross SVG. **`disabled`** sets **`aria-disabled`** on the root and disables the remove button.
+- Without **`onRemove`**, there is no focusable control inside the tag; the root is not a button or link.
+- For lists of removable tags, give the group a clear name (**`aria-label`** or **`aria-labelledby`**) so “Remove” has context.
+- **`Tag.Icon`** does not force **`aria-hidden`** on icons; if the icon is decorative, rely on adjacent text or set **`aria-hidden`** on the icon content yourself.
+- There is no **`variant`** prop; appearance follows **`size`** and whether removal is enabled.
+
+## API
+
+### Tag.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` or from `ControlSizeProvider` | No | Visual tier for height, radius, text, and nested icon scale |
+| onRemove | `() => void` | — | No | When set, renders the remove button on the right |
+| disabled | `boolean` | — | No | Disables removal and sets `aria-disabled` on the root |
+| children | `React.ReactNode` | — | No | Text, `Tag.Icon`, or other nodes |
+| className | `string` | — | No | Extra class on the root `span` |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other root attributes (`data-*`, `aria-*`, etc.) |
+
+### Tag.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Icon or other content |
+| className | `string` | — | No | Extra class on the wrapper |
+
+## Related
+
+- [Badge](../badge/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [Input](../input/COMPONENT.md)
+- [Select](../select/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/textarea/COMPONENT.md

@@ -0,0 +1,98 @@
+# Textarea
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A composite multiline field: native `textarea` inside a bordered `label`, optional footer for a character counter, and optional hint or error lines below wired through `aria-describedby`.
+
+**When to use**
+
+- Long or growing text in forms, feedback, notes, descriptions, and comments where a single line is not enough.
+- Flows that need a built-in counter, hint, or error message aligned with the same sizing scale as other controls.
+- Layouts where auto-growing height (`autoResize`) should track content without manual `rows` tuning.
+
+**When not to use**
+
+- Single-line values — use [Input](../input/COMPONENT.md).
+- Rich text or embedded formatting — use a dedicated editor component.
+- When the visible label must sit only above the chrome — pair [Label](../label/COMPONENT.md) with a stable `id` on `Textarea.Root` and avoid nesting a second `label`.
+
+## Composition
+
+- **`Textarea.Root`** — outer `div` (`field`) with `data-size`, `TextareaProvider`, and `ControlSizeProvider`. The native `textarea` sits inside a `label` (`htmlFor` → input id) with the bordered `control` styling; when `autoResize` is true, the textarea is wrapped so `data-value` can drive height.
+- **`Textarea.CharCounter`** — must be a **direct** child of `Root`; implementation partitions children by reference equality to `Textarea.CharCounter` and renders matching nodes in the control footer.
+- **`Textarea.Hint`** / **`Textarea.Error`** — direct children of `Root`, **not** passed as `CharCounter`; they render after the `label` and register ids merged into the textarea’s `aria-describedby`.
+
+### Minimal example
+
+```tsx
+import { Textarea } from "prime-ui-kit";
+
+export function Example() {
+  return <Textarea.Root placeholder="Notes" />;
+}
+```
+
+## Rules
+
+- **Controlled vs uncontrolled:** pass **`value`** with **`onChange`** / **`onInput`** as needed for controlled text; omit **`value`** and optionally set **`defaultValue`** for uncontrolled usage.
+- **`autoResize`** defaults to **`true`**: input events update a wrapper `data-value` mirror; set **`autoResize={false}`** to rely on fixed height / native resize behavior.
+- **`variant="error"`** or mounting **`Textarea.Error`** sets invalid styling; **`aria-invalid`** defaults from that unless overridden.
+- **`aria-describedby`** you pass is **merged** with auto-added hint and error ids (your ids first, then hint and error when those parts mount).
+- **`disabled`** / **`readOnly`** on `Root` flow to the native textarea; **`Textarea.Hint`** switches to a disabled visual variant when either is true.
+- Do not pass **`size`** as a DOM attribute on the textarea — it is omitted from the element API and reserved for **`Textarea.Root`** (`"s"` \| `"m"` \| `"l"` \| `"xl"`).
+- **`Textarea.CharCounter`** is only recognized as an immediate child of **`Root`**; arbitrary wrappers around it will not land in the footer.
+- Counter overflow (**`current` > `max`**) sets **`data-overflow="true"`** on the counter for styling; it does not block typing by itself (pair with **`maxLength`** if you need a hard cap).
+- The counter uses **`aria-live="polite"`** so count updates do not interrupt typing.
+- There is no **`asChild`** or polymorphic root — structure is fixed.
+
+## API
+
+### Textarea.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"default" \| "error"` | `"default"` | no | Visual invalid emphasis; combines with `aria-invalid` and `Textarea.Error` registration. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Control scale (padding, type, min height). |
+| autoResize | `boolean` | `true` | no | When true, height follows content via wrapper `data-value`; when false, no auto-grow wrapper. |
+| id | `string` | from `useId()` | no | Stable id for the textarea; `label` uses `htmlFor` pointing here. |
+| className | `string` | — | no | Class on the bordered `label` (`control`). |
+| disabled | `boolean` | — | no | Native disabled state. |
+| readOnly | `boolean` | — | no | Native read-only state. |
+| value | `string` | — | no | Controlled value. |
+| defaultValue | `string` | — | no | Uncontrolled initial value. |
+| onInput | `React.FormEventHandler<HTMLTextAreaElement>` | — | no | Fires after internal `data-value` sync when `autoResize` is on. |
+| aria-describedby | `string` | — | no | Merged with hint/error ids when those parts mount. |
+| aria-invalid | `Booleanish` | from variant / error | no | Explicit invalidity over heuristics. |
+| children | `React.ReactNode` | — | no | `CharCounter` in the footer; `Hint` / `Error` after the `label`. |
+| …rest | `Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size">` | — | no | Standard textarea attributes (`placeholder`, `rows`, `maxLength`, `required`, `onChange`, `name`, etc.). |
+
+### Textarea.CharCounter
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| current | `number` | — | yes | Current character count. |
+| max | `number` | — | yes | Displayed limit; overflow when `current > max` sets `data-overflow="true"`. |
+
+### Textarea.Hint
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Hint copy. |
+| className | `string` | — | no | Extra class on the underlying `Hint.Root`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` comes from context. |
+
+### Textarea.Error
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | yes | Error copy. |
+| className | `string` | — | no | Extra class on the underlying `Hint.Root`. |
+| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` comes from context. |
+
+## Related
+
+- [Input](../input/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)

package/src/components/tooltip/COMPONENT.md

@@ -0,0 +1,87 @@
+# Tooltip
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A composite tooltip: optional delay provider, root with open state, trigger that wraps a single element, and content rendered in a portal and positioned relative to the trigger.
+
+- **Use** to clarify icon-only controls, abbreviated labels, dense table cells, or non-obvious metrics on hover or keyboard focus.
+- **Use** when the extra text is short and supplementary; keep the trigger’s visible label or `aria-label` as the primary affordance where possible.
+- **Do not use** for long explanations or content that should stay visible without hover—prefer inline help, a hint, or a dedicated panel.
+- **Do not use** for interactive content inside the layer (links, buttons, inputs); tooltip content is non-interactive and uses `pointer-events: none` in styles.
+- **Do not use** one root for multiple anchors—each trigger needs its own `Tooltip.Root` (or separate instances).
+- **Do not rely** on tooltips opening for natively `disabled` controls; disabled elements often do not receive hover/focus—wrap or use a different focusable pattern if a tooltip is required.
+
+## Composition
+
+- **`Tooltip.Provider`** (optional) — wraps a subtree to share **`delayDuration`** (default **400** ms) for nested **`Tooltip.Root`** instances. Omit it when the default delay is fine.
+- **`Tooltip.Root`** — holds open state (controlled or uncontrolled). Children must include **`Tooltip.Trigger`** and **`Tooltip.Content`** (order in the tree is conventional; both participate via context).
+- **`Tooltip.Trigger`** — accepts **exactly one** **`React.ReactElement`** child. The implementation **`cloneElement`s** it: merges **`ref`**, **`className`**, **`aria-describedby`**, and pointer/focus handlers. The child must forward refs and accept standard DOM props.
+- **`Tooltip.Content`** — tooltip body; rendered through **`Portal`** as a **`div`** with **`role="tooltip"`** and **`id`** matching the trigger’s **`aria-describedby`**. Sets **`data-size`** and **`data-side`** for styling (including the arrow). Wraps children in **`ControlSizeProvider`** for the chosen **`size`**.
+
+### Minimal example
+
+```tsx
+import { Tooltip } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <button type="button">Hover</button>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Help text</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}
+```
+
+## Rules
+
+- **Uncontrolled:** omit **`open`**; optional **`defaultOpen`** (defaults to **`false`**). **Controlled:** pass **`open`** and **`onOpenChange`**; the same open state drives visibility together with hover/focus on the trigger.
+- Opening is **delayed** by **`Tooltip.Provider`**’s **`delayDuration`** after **`mouseenter`** or **`focus`**; leaving or **blur** clears the timer and closes. Cleanup runs on unmount.
+- **Position:** **`side`** is **`top`** \| **`bottom`** \| **`left`** \| **`right`** (default **`top`**). Coordinates are **clamped** to the viewport (**8px** inset); there is **no automatic flip** to the opposite side when space is tight—choose **`side`** explicitly if needed.
+- **Accessibility:** trigger gets **`aria-describedby`** pointing at the content **`id`**; content uses **`role="tooltip"`**. For inline glossary-style terms, prefer **`button type="button"`** as the trigger so keyboard focus is predictable.
+- **Portal:** content does not sit in the trigger’s DOM subtree; it won’t inherit layout/CSS from ancestors of the trigger (only what you pass as children and classes on **`Tooltip.Content`**).
+- **`Tooltip.Content`** defaults **`size`** to **`m`** and **`side`** to **`top`**; visual scale and arrow follow **`data-size`** / **`data-side`** and theme tokens—there is no separate **`variant`** prop.
+
+## API
+
+The package exports the **`Tooltip`** namespace object and types **`TooltipSize`**, **`TooltipSide`**, **`TooltipProviderProps`**, **`TooltipRootProps`**, **`TooltipTriggerProps`**, **`TooltipContentProps`**.
+
+### Tooltip.Provider
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| delayDuration | `number` | `400` | No | Milliseconds to wait before opening after pointer enters or the trigger receives focus |
+| children | `React.ReactNode` | — | Yes | Subtree whose tooltips use this delay |
+
+### Tooltip.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Typically `Tooltip.Trigger` and `Tooltip.Content` |
+| open | `boolean` | — | No | Controlled open state |
+| defaultOpen | `boolean` | `false` | No | Initial open state when uncontrolled |
+| onOpenChange | `(open: boolean) => void` | — | No | Called when open state changes |
+
+### Tooltip.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement` | — | Yes | Single element; receives ref, `aria-describedby`, and open/close handlers |
+| className | `string` | — | No | Merged with the child’s `className` via `cx()` |
+
+### Tooltip.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Tooltip body; wrapped in `ControlSizeProvider` for nested controls that read control size |
+| size | `TooltipSize` (`"s"` \| `"m"` \| `"l"` \| `"xl"`) | `"m"` | No | Padding, typography, and arrow scale |
+| side | `TooltipSide` (`"top"` \| `"bottom"` \| `"left"` \| `"right"`) | `"top"` | No | Placement relative to the trigger before viewport clamping |
+| className | `string` | — | No | Additional class on the portal root |
+
+## Related
+
+[Button](../button/COMPONENT.md) — typical focusable trigger; [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) — persistent field labeling and helper text; [Popover](../popover/COMPONENT.md) — focusable, interactive overlay content.

package/src/components/typography/COMPONENT.md

@@ -0,0 +1,89 @@
+# Typography
+
+**Проектирование по умолчанию:** для текста страницы выбирайте **`body-default`** в `variant`, если явно не оговорено иное.
+
+## About
+
+Стилизованный текст с **семантическими ролями чтения** (`variant`), привязанными к `typography.role` в токенах, и опциональными осями: `weight`, `tracking`, курсив и приглушённый `tone`. Рендерится как выбранный HTML-тег (`as`).
+
+- **Use** для основного текста, подзаголовков по смыслу ролей, подписей и метрик там, где нужны токены кита, а не произвольный `font-size`.
+- **Use** `tone="muted"` для вторичных пояснений и юридических строк.
+- **Use** вложенные `Typography.Root` с разными `as` и `weight` внутри одного блока.
+- **Use** `as="h1"`–`as="h6"` для визуального уровня заголовка, согласованного с темой; по возможности сохраняйте логичный порядок уровней на странице.
+- **Use** `as` с landmarks (`main`, `article`, `section`, `header`, `footer`, …) при вёрстке шаблонов.
+- **Do not use** для подписи внутри **кнопки** или **поля ввода** как отдельной «типографики»: у этих компонентов свой ритм текста — положитесь на разметку [Button](../button/COMPONENT.md) / [Input](../input/COMPONENT.md) и при необходимости [Label](../label/COMPONENT.md).
+- **Do not use** `as` вместо настоящих `<button>` / `<a>` для действий и навигации.
+- **Do not use** ожидая отдельный контроль `line-height` вне роли — межстрочный интервал связан с `variant` в стилях.
+
+Интерактивные компоненты (формы, кнопки и т.д.) настраиваются **своими** пропами и токенами; **`Typography`** к ним не относится и **не** задаёт их внешний вид.
+
+## Справочное сопоставление: MD3, Apple (SF), Polaris
+
+Ниже — **ориентировочное** соответствие ролей prime-ui-kit стилям из [Material Design 3 — Type scale](https://m3.material.io/styles/typography/type-scale-tokens), уровням текста [Apple — Typography](https://developer.apple.com/design/human-interface-guidelines/typography) (SF Pro) и вариантам [Polaris Text](https://polaris.shopify.com/components/typography/text). У разных систем **разные pt/px**; ориентир — **уровень иерархии**, не побитовое совпадение.
+
+**Кегль в теме:** каждая роль ссылается на ступени `typography.sizeScale` / `lineHeightScale` → примитивы `font.size.*` / `font.lineHeight.*`. Ниже — **приблизительный размер шрифта** при `1rem = 16px` на `:root` (округление).
+
+| `variant` | Примитив кегля | ≈ px @16 | Близкий стиль MD3 | Близкий уровень Apple (SF) | Polaris `Text` |
+| --------- | ---------------- | -------- | ----------------- | --------------------------- | -------------- |
+| `display` | `9xl` | 57 | Display Large | Large Title | `heading3xl` |
+| `headline` | `6xl` | 32 | Headline Large | Title 1 | `heading2xl` |
+| `heading-page` | `4xl` | 28 | Headline Medium | Title 2 | `headingXl` |
+| `heading-section` | `2xl` | 24 | Headline Small | Title 3 | `headingLg` |
+| `heading-subsection` | `xl` | 22 | Title Large | Headline | `headingMd` |
+| `heading-group` | `xs` | 14 | Title Small | Subheadline / Footnote | `headingSm`, `headingXs` |
+| `body-large` | `s` | 16 | Body Large | Body / Callout | `bodyLg` |
+| `body-default` | `xs` | 14 | Body Medium | Subheadline | `bodyMd` |
+| `body-small` | `2xs` | 12 | Body Small | Footnote | `bodySm` |
+| `body-compact` | кегль `xs`, межстрочный `2xs` | 14, плотнее | Label Large (плотная строка) | — | `bodyXs` |
+| `caption` | `2xs` | 12 | Label Medium | Caption 1 | `bodySm` (по смыслу + `tone`) |
+| `caption-micro` | `labelMicro` | 11 | Label Small | Caption 2 | самый мелкий смысловой уровень |
+
+Ступени **`7xl`**, **`8xl`** в шкале есть (как у MD3 Display Medium / Small по размеру), но **в роли `typography.role` не задействованы** — при необходимости используйте их через токены напрямую, не через `Typography`.
+
+## Composition
+
+- Одна часть: **`Typography.Root`**. Текст или инлайн-разметка в **`children`**.
+- **`as`** задаёт элемент по умолчанию **`p`**; допустимы абзац, инлайн, блок, **заголовки `h1`–`h6`**, **`small`**, **`blockquote`**, а также **landmarks**: `article`, `section`, `header`, `footer`, `aside`, `nav`, `main`.
+
+### Minimal example
+
+```tsx
+import { Typography } from "prime-ui-kit";
+
+export function Example() {
+  return <Typography.Root variant="body-default">Hello</Typography.Root>;
+}
+```
+
+## Rules
+
+- **`variant` обязателен**; лишние **`data-*`** для значений по умолчанию не выставляются (`weight="regular"`, `tracking="normal"`, `tone="default"`, без курсива).
+- В DOM на корне: **`data-variant`** (кебаб-кейс, например `heading-page`).
+- HTML-атрибуты (`id`, `aria-*`, …) пробрасываются через **`...rest`**.
+- Корень использует **`text-wrap: balance`** для коротких блоков; при необходимости переопределяйте снаружи.
+- Отдельных состояний disabled/loading/error нет — сочетайте с родительским UI.
+
+## API
+
+### Typography.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | см. `TypographyAs` | `"p"` | No | HTML-элемент-обёртка |
+| variant | см. `TypographyVariant` | — | Yes | Семантическая роль чтения |
+| weight | `"regular"` \| `"medium"` \| `"semibold"` | `"regular"` | No | Начертание |
+| tracking | `"normal"` \| `"tight"` \| `"tighter"` \| `"wide"` | `"normal"` | No | Межбуквенное расстояние |
+| italic | `boolean` | `false` | No | Курсив |
+| tone | `"default"` \| `"muted"` | `"default"` | No | Основной или вторичный цвет текста |
+| children | `React.ReactNode` | — | No | Контент |
+| className | `string` | — | No | Дополнительный класс |
+| ref | `React.Ref<HTMLElement>` | — | No | Ref на узел |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | Прочие атрибуты элемента |
+
+## Related
+
+- [Label](../label/COMPONENT.md)
+- [Hint](../hint/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [Banner](../banner/COMPONENT.md)
+- [Notification](../notification/COMPONENT.md)

package/src/styles/theme-dark.css

@@ -98,12 +98,23 @@
   --prime-sys-elevation-shadow-surface: 0 1px 2px rgba(8, 10, 14, 0.35);
   --prime-sys-elevation-shadow-tooltip: 0 14px 30px rgba(8, 10, 14, 0.5), 0 4px 10px rgba(8, 10, 14, 0.4);
   --prime-sys-elevation-zIndex-base: var(--prime-ref-zIndex-base);
+  --prime-sys-elevation-zIndex-drawer: var(--prime-ref-zIndex-drawer);
+  --prime-sys-elevation-zIndex-drawerNestedShell: var(--prime-ref-zIndex-drawerNestedShell);
   --prime-sys-elevation-zIndex-dropdown: var(--prime-ref-zIndex-dropdown);
+  --prime-sys-elevation-zIndex-dropdownInDrawer: var(--prime-ref-zIndex-dropdownInDrawer);
+  --prime-sys-elevation-zIndex-dropdownInDrawerInModal: var(--prime-ref-zIndex-dropdownInDrawerInModal);
+  --prime-sys-elevation-zIndex-dropdownInModal: var(--prime-ref-zIndex-dropdownInModal);
   --prime-sys-elevation-zIndex-modal: var(--prime-ref-zIndex-modal);
   --prime-sys-elevation-zIndex-popover: var(--prime-ref-zIndex-popover);
+  --prime-sys-elevation-zIndex-popoverInDrawer: var(--prime-ref-zIndex-popoverInDrawer);
+  --prime-sys-elevation-zIndex-popoverInDrawerInModal: var(--prime-ref-zIndex-popoverInDrawerInModal);
+  --prime-sys-elevation-zIndex-popoverInModal: var(--prime-ref-zIndex-popoverInModal);
   --prime-sys-elevation-zIndex-sticky: var(--prime-ref-zIndex-sticky);
   --prime-sys-elevation-zIndex-toast: var(--prime-ref-zIndex-toast);
   --prime-sys-elevation-zIndex-tooltip: var(--prime-ref-zIndex-tooltip);
+  --prime-sys-elevation-zIndex-tooltipInDrawer: var(--prime-ref-zIndex-tooltipInDrawer);
+  --prime-sys-elevation-zIndex-tooltipInDrawerInModal: var(--prime-ref-zIndex-tooltipInDrawerInModal);
+  --prime-sys-elevation-zIndex-tooltipInModal: var(--prime-ref-zIndex-tooltipInModal);
   --prime-sys-motion-duration-fast: var(--prime-ref-motion-duration-fast);
   --prime-sys-motion-duration-medium: var(--prime-ref-motion-duration-medium);
   --prime-sys-motion-duration-slow: var(--prime-ref-motion-duration-slow);
@@ -385,11 +396,39 @@
   --prime-sys-typography-lineHeightScale-4xl: var(--prime-ref-font-lineHeight-4xl);
   --prime-sys-typography-lineHeightScale-5xl: var(--prime-ref-font-lineHeight-5xl);
   --prime-sys-typography-lineHeightScale-6xl: var(--prime-ref-font-lineHeight-6xl);
+  --prime-sys-typography-lineHeightScale-7xl: var(--prime-ref-font-lineHeight-7xl);
+  --prime-sys-typography-lineHeightScale-8xl: var(--prime-ref-font-lineHeight-8xl);
+  --prime-sys-typography-lineHeightScale-9xl: var(--prime-ref-font-lineHeight-9xl);
   --prime-sys-typography-lineHeightScale-l: var(--prime-ref-font-lineHeight-l);
+  --prime-sys-typography-lineHeightScale-labelMicro: var(--prime-ref-font-lineHeight-labelMicro);
   --prime-sys-typography-lineHeightScale-m: var(--prime-ref-font-lineHeight-m);
   --prime-sys-typography-lineHeightScale-s: var(--prime-ref-font-lineHeight-s);
   --prime-sys-typography-lineHeightScale-xl: var(--prime-ref-font-lineHeight-xl);
   --prime-sys-typography-lineHeightScale-xs: var(--prime-ref-font-lineHeight-xs);
+  --prime-sys-typography-role-bodyCompact-fontSize: var(--prime-sys-typography-sizeScale-xs);
+  --prime-sys-typography-role-bodyCompact-lineHeight: var(--prime-sys-typography-lineHeightScale-2xs);
+  --prime-sys-typography-role-bodyDefault-fontSize: var(--prime-sys-typography-sizeScale-xs);
+  --prime-sys-typography-role-bodyDefault-lineHeight: var(--prime-sys-typography-lineHeightScale-xs);
+  --prime-sys-typography-role-bodyLarge-fontSize: var(--prime-sys-typography-sizeScale-s);
+  --prime-sys-typography-role-bodyLarge-lineHeight: var(--prime-sys-typography-lineHeightScale-s);
+  --prime-sys-typography-role-bodySmall-fontSize: var(--prime-sys-typography-sizeScale-2xs);
+  --prime-sys-typography-role-bodySmall-lineHeight: var(--prime-sys-typography-lineHeightScale-2xs);
+  --prime-sys-typography-role-caption-fontSize: var(--prime-sys-typography-sizeScale-2xs);
+  --prime-sys-typography-role-caption-lineHeight: var(--prime-sys-typography-lineHeightScale-2xs);
+  --prime-sys-typography-role-captionMicro-fontSize: var(--prime-sys-typography-sizeScale-labelMicro);
+  --prime-sys-typography-role-captionMicro-lineHeight: var(--prime-sys-typography-lineHeightScale-labelMicro);
+  --prime-sys-typography-role-display-fontSize: var(--prime-sys-typography-sizeScale-9xl);
+  --prime-sys-typography-role-display-lineHeight: var(--prime-sys-typography-lineHeightScale-9xl);
+  --prime-sys-typography-role-headingGroup-fontSize: var(--prime-sys-typography-sizeScale-xs);
+  --prime-sys-typography-role-headingGroup-lineHeight: var(--prime-sys-typography-lineHeightScale-xs);
+  --prime-sys-typography-role-headingPage-fontSize: var(--prime-sys-typography-sizeScale-4xl);
+  --prime-sys-typography-role-headingPage-lineHeight: var(--prime-sys-typography-lineHeightScale-4xl);
+  --prime-sys-typography-role-headingSection-fontSize: var(--prime-sys-typography-sizeScale-2xl);
+  --prime-sys-typography-role-headingSection-lineHeight: var(--prime-sys-typography-lineHeightScale-2xl);
+  --prime-sys-typography-role-headingSubsection-fontSize: var(--prime-sys-typography-sizeScale-xl);
+  --prime-sys-typography-role-headingSubsection-lineHeight: var(--prime-sys-typography-lineHeightScale-xl);
+  --prime-sys-typography-role-headline-fontSize: var(--prime-sys-typography-sizeScale-6xl);
+  --prime-sys-typography-role-headline-lineHeight: var(--prime-sys-typography-lineHeightScale-6xl);
   --prime-sys-typography-sizeScale-2xl: var(--prime-ref-font-size-2xl);
   --prime-sys-typography-sizeScale-2xs: var(--prime-ref-font-size-2xs);
   --prime-sys-typography-sizeScale-3xl: var(--prime-ref-font-size-3xl);
@@ -397,7 +436,11 @@
   --prime-sys-typography-sizeScale-4xl: var(--prime-ref-font-size-4xl);
   --prime-sys-typography-sizeScale-5xl: var(--prime-ref-font-size-5xl);
   --prime-sys-typography-sizeScale-6xl: var(--prime-ref-font-size-6xl);
+  --prime-sys-typography-sizeScale-7xl: var(--prime-ref-font-size-7xl);
+  --prime-sys-typography-sizeScale-8xl: var(--prime-ref-font-size-8xl);
+  --prime-sys-typography-sizeScale-9xl: var(--prime-ref-font-size-9xl);
   --prime-sys-typography-sizeScale-l: var(--prime-ref-font-size-l);
+  --prime-sys-typography-sizeScale-labelMicro: var(--prime-ref-font-size-labelMicro);
   --prime-sys-typography-sizeScale-m: var(--prime-ref-font-size-m);
   --prime-sys-typography-sizeScale-s: var(--prime-ref-font-size-s);
   --prime-sys-typography-sizeScale-xl: var(--prime-ref-font-size-xl);