prime-ui-kit 0.2.5 → 0.3.2

package/src/components/tag/examples/02-removable-selected-values.tsx

@@ -0,0 +1,33 @@
+import { Tag } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Selected values (skills, recipients): removable chips in a named group so the fixed
+ * remove control `aria-label` has context from the page.
+ */
+export default function TagExampleRemovableSelectedValues() {
+  const [skills, setSkills] = React.useState<string[]>([
+    "Design systems",
+    "React",
+    "Accessibility",
+  ]);
+
+  const removeSkill = (label: string) => {
+    setSkills((prev) => prev.filter((s) => s !== label));
+  };
+
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Required skills</legend>
+      <div className={styles.chipRow}>
+        {skills.map((label) => (
+          <Tag.Root key={label} size="m" onRemove={() => removeSkill(label)}>
+            {label}
+          </Tag.Root>
+        ))}
+      </div>
+    </fieldset>
+  );
+}

package/src/components/tag/examples/03-status-metadata.tsx

@@ -0,0 +1,24 @@
+import { Icon, Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Read-only metadata and status: no `onRemove`, optional leading icon via `Tag.Icon`.
+ */
+export default function TagExampleStatusMetadata() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Release</legend>
+      <div className={styles.chipRow}>
+        <Tag.Root size="m">
+          <Tag.Icon>
+            <Icon name="status.locked" aria-hidden />
+          </Tag.Icon>
+          <span>Production</span>
+        </Tag.Root>
+        <Tag.Root size="m">v2.4.1</Tag.Root>
+        <Tag.Root size="m">Stable</Tag.Root>
+      </div>
+    </fieldset>
+  );
+}

package/src/components/tag/examples/04-tag-sizes.tsx

@@ -0,0 +1,18 @@
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Size ladder `s` → `xl` for dense toolbars vs prominent filter rows. */
+export default function TagExampleSizes() {
+  return (
+    <fieldset className={styles.fieldsetPlain}>
+      <legend className={styles.legend}>Size scale</legend>
+      <div className={styles.chipRow}>
+        <Tag.Root size="s">Small</Tag.Root>
+        <Tag.Root size="m">Medium</Tag.Root>
+        <Tag.Root size="l">Large</Tag.Root>
+        <Tag.Root size="xl">Extra large</Tag.Root>
+      </div>
+    </fieldset>
+  );
+}

package/src/components/tag/examples/examples.module.css

@@ -0,0 +1,20 @@
+.fieldsetPlain {
+  margin: 0;
+  padding: 0;
+  border: none;
+  min-width: 0;
+}
+
+.legend {
+  margin: 0 0 var(--prime-sys-spacing-s);
+  padding: 0;
+  font-size: var(--prime-sys-typography-sizeScale-s);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.chipRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-s);
+  align-items: center;
+}

package/src/components/textarea/COMPONENT.md

@@ -0,0 +1,120 @@
+# Textarea
+
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+
+## Canonical
+
+- **Purpose:** multiline text with optional in-control **character counter**, and optional **hint** or **error** below, wired through **`aria-describedby`** on the native **`textarea`**.
+- **Skeleton vs Input:** unlike [Input](../input/COMPONENT.md) (`Root` → `Wrapper` → **`Field`**), **Textarea** uses a single **`Textarea.Root`**: an outer **`.field`** stack wraps a bordered **`label`** (the field chrome) that owns the native **`<textarea>`**—there is **no** separate `Textarea.Field` export; pass standard textarea attributes on **`Root`**.
+- **Children:** **`Textarea.CharCounter`** only as a **direct** child of **`Root`** (footer inside the chrome). **`Textarea.Hint`** / **`Textarea.Error`** as direct children **after** that chrome (siblings of the inner `label`, not wrapped around `CharCounter`).
+- **Size:** `size` ∈ `s | m | l | xl` only on **`Textarea.Root`**; the HTML **`size`** attribute is omitted from the public typing (reserved).
+- **Scenario examples (source):** [`./examples/01-support-ticket.tsx`](./examples/01-support-ticket.tsx), [`./examples/02-comment.tsx`](./examples/02-comment.tsx), [`./examples/03-controlled.tsx`](./examples/03-controlled.tsx), [`./examples/04-full-width.tsx`](./examples/04-full-width.tsx).
+
+```tsx
+import { Textarea } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Textarea.Root placeholder="Notes" name="notes">
+      <Textarea.Hint>Optional hint below the field.</Textarea.Hint>
+    </Textarea.Root>
+  );
+}
+```
+
+## Extended
+
+### About
+
+A composite multiline field: native `textarea` inside bordered field chrome, 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`** (see [`./examples/02-comment.tsx`](./examples/02-comment.tsx)); do not nest a second `label` around the control.
+
+### Composition
+
+- **`Textarea.Root`** — outer `div` (`.field`) with `data-size`, `TextareaProvider`, and `ControlSizeProvider`. The native `textarea` sits inside a `label` (`htmlFor` → input id) with 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`.
+
+### Extended examples
+
+- [`./examples/01-support-ticket.tsx`](./examples/01-support-ticket.tsx) — Support form: description with counter, hint, and `maxLength`.
+- [`./examples/02-comment.tsx`](./examples/02-comment.tsx) — Order comment: **Label** + **`Textarea.Root`** with shared **`id`**, counter, and logistics hint.
+- [`./examples/03-controlled.tsx`](./examples/03-controlled.tsx) — Controlled value in React state with **`onChange`**.
+- [`./examples/04-full-width.tsx`](./examples/04-full-width.tsx) — Filling a card column: root is already **`width: 100%`**; parent sets the track width.
+
+**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition patterns; this page keeps the contract (rules + API tables) authoritative.
+
+### 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.
+- **Full width:** the `.field` root uses **`width: 100%`** and **`min-width: 0`** (same idea as Input). Place **`Textarea.Root`** inside a parent that spans the desired column or card width.
+- 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/textarea/examples/01-support-ticket.tsx

@@ -0,0 +1,35 @@
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const MAX = 2000;
+
+/**
+ * Support ticket: long description with counter, hint, and a hard cap via maxLength.
+ */
+export default function TextareaExampleSupportTicket() {
+  const [text, setText] = React.useState("");
+
+  return (
+    <div className={styles.stack}>
+      <Textarea.Root
+        id="support-description"
+        name="description"
+        size="m"
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        maxLength={MAX}
+        placeholder="Describe what happened, steps to reproduce, and what you expected instead."
+        rows={4}
+        required
+        aria-label="Support ticket description"
+      >
+        <Textarea.CharCounter current={text.length} max={MAX} />
+        <Textarea.Hint>
+          We typically reply within one business day. Avoid sharing passwords or full card numbers.
+        </Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/02-comment.tsx

@@ -0,0 +1,35 @@
+import { Label, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FIELD_ID = "order-comment";
+const MAX = 240;
+
+/**
+ * Order comment: caption above the field chrome via Label + shared id on Textarea.Root.
+ */
+export default function TextareaExampleComment() {
+  const [comment, setComment] = React.useState("");
+
+  return (
+    <div className={styles.labelBlock}>
+      <Label.Root htmlFor={FIELD_ID} size="m">
+        Comment for the courier
+        <Label.Sub>Optional — visible to logistics until the order ships.</Label.Sub>
+      </Label.Root>
+      <Textarea.Root
+        id={FIELD_ID}
+        name="courierComment"
+        size="m"
+        value={comment}
+        onChange={(e) => setComment(e.target.value)}
+        maxLength={MAX}
+        placeholder="Gate code, safe drop spot, or delivery window"
+      >
+        <Textarea.CharCounter current={comment.length} max={MAX} />
+        <Textarea.Hint>Keep it short; the driver sees this on the handheld.</Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/03-controlled.tsx

@@ -0,0 +1,27 @@
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled textarea: value lives in parent state; hint reflects live length.
+ */
+export default function TextareaExampleControlled() {
+  const [draft, setDraft] = React.useState(
+    "Draft text is owned by React state and updates on every change event.",
+  );
+
+  return (
+    <div className={styles.stack}>
+      <Textarea.Root
+        size="m"
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        placeholder="Type here…"
+        name="draft"
+      >
+        <Textarea.Hint>Characters in state: {draft.length}</Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/04-full-width.tsx

@@ -0,0 +1,23 @@
+import { Textarea } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Full width within a parent: Textarea.Root already stretches to 100% of its container.
+ */
+export default function TextareaExampleFullWidth() {
+  return (
+    <div className={styles.fullWidthCard}>
+      <Textarea.Root
+        size="m"
+        name="cardNote"
+        placeholder="This field spans the full width of the card column."
+      >
+        <Textarea.Hint>
+          Widen or narrow the parent; the control follows the track (min-width: 0 avoids grid
+          blowout).
+        </Textarea.Hint>
+      </Textarea.Root>
+    </div>
+  );
+}

package/src/components/textarea/examples/examples.module.css

@@ -0,0 +1,21 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.labelBlock {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.fullWidthCard {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: min(100%, 22rem);
+  padding: var(--prime-sys-spacing-x3);
+  border-radius: var(--prime-sys-radius-m);
+  border: 1px dashed var(--prime-sys-color-border-subtle);
+  background: var(--prime-sys-color-surface-raised);
+}

package/src/components/tooltip/COMPONENT.md

@@ -0,0 +1,144 @@
+# 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>
+  );
+}
+```
+
+### Canonical example (icon-only control)
+
+Use this as the default copy-paste shell: **`aria-label`** (or another accessible name) on the **focusable** trigger, **`Button.Icon`** + **`Icon`**, and a short **`Tooltip.Content`** (often **`size="s"`** next to a **`size="m"`** control).
+
+```tsx
+import { Button, Icon, Tooltip } from "prime-ui-kit";
+
+export function CopyLinkHint() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <Button.Root
+          type="button"
+          variant="neutral"
+          mode="ghost"
+          size="m"
+          aria-label="Copy link"
+        >
+          <Button.Icon>
+            <Icon name="action.copy" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+      </Tooltip.Trigger>
+      <Tooltip.Content size="s">Copy page link to clipboard</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}
+```
+
+Source of truth (stays in sync with the snippet above): `examples/canonical-icon-hint.tsx`.
+
+### Examples (source)
+
+Runnable demos live next to this file (workspace imports use `@/`; published consumers use `prime-ui-kit`):
+
+| File | Intent |
+|------|--------|
+| `examples/canonical-icon-hint.tsx` | Icon-only button, **`aria-label`**, short hint |
+| `examples/scenario-delay-provider.tsx` | **`Tooltip.Provider`** with **`delayDuration={800}`** |
+| `examples/scenario-long-content.tsx` | Long wrapped copy; **`size="m"`** |
+| `examples/scenario-side-bottom.tsx` | **`side="bottom"`** when default placement clips |
+| `examples/scenario-controlled-programmatic.tsx` | **`open`** / **`onOpenChange`** with **`delayDuration={0}`** for demos |
+
+Playground snippets (broader variants, including Russian copy): `playground/snippets/tooltip/`.
+
+### Extended usage
+
+- **Delay:** wrap a subtree in **`Tooltip.Provider`** and set **`delayDuration`** (ms). Default is **400**; use a longer value to reduce accidental flashes, or **`0`** for tests and controlled demos.
+- **Long text:** rely on the built-in **`max-width`** and **`word-break`** on the content surface; prefer shorter copy when possible—if users must read a paragraph, use inline help, **Hint**, or **Popover** instead.
+- **Placement:** set **`side`** on **`Tooltip.Content`** when **top** clips; coordinates are **viewport-clamped** (**8px** inset) but the kit does **not** auto-flip to the opposite side.
+- **Controlled:** pass **`open`** and **`onOpenChange`** on **`Tooltip.Root`**; pointer/focus on the trigger still updates the same state. Pair with **`delayDuration={0}`** when an external control should show the tooltip immediately.
+- **Disabled triggers:** native **`disabled`** elements often skip hover/focus—wrap with a focusable container or use **`aria-disabled`** + custom styling if a tooltip on a “disabled” control is required.
+
+### Note for LLMs
+
+When generating **Tooltip** markup for this library: (1) **`Tooltip.Trigger`** takes **exactly one** **`ReactElement`** child (the implementation uses **`cloneElement`**). (2) Put the **accessible name** on the trigger (**`aria-label`**, visible text, or **`aria-labelledby`**)—the tooltip supplements it; do not rely on the tooltip alone for the control’s name. (3) Do not put **links, buttons, or inputs** inside **`Tooltip.Content`** (non-interactive layer, **`pointer-events: none`**). (4) Use **one** **`Tooltip.Root`** per anchor; do not attach one root to multiple triggers. (5) For starting points, mirror **`examples/canonical-icon-hint.tsx`**, then adapt **`scenario-*.tsx`** files.
+
+## 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/tooltip/examples/canonical-icon-hint.tsx

@@ -0,0 +1,19 @@
+import { Button, Icon, Tooltip } from "prime-ui-kit";
+
+/**
+ * Icon-only control: accessible name on the trigger plus a short tooltip on hover/focus.
+ */
+export default function TooltipCanonicalIconHint() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <Button.Root type="button" variant="neutral" mode="ghost" size="m" aria-label="Copy link">
+          <Button.Icon>
+            <Icon name="action.copy" size="s" tone="subtle" />
+          </Button.Icon>
+        </Button.Root>
+      </Tooltip.Trigger>
+      <Tooltip.Content size="s">Copy page link to clipboard</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}

package/src/components/tooltip/examples/examples.module.css

@@ -0,0 +1,6 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  align-items: flex-start;
+}

package/src/components/tooltip/examples/scenario-controlled-programmatic.tsx

@@ -0,0 +1,32 @@
+import { Button, Switch, Tooltip } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled open state: drive the same boolean from UI and Tooltip.Root.
+ */
+export default function TooltipScenarioControlledProgrammatic() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div className={styles.stack}>
+      <Switch.Root size="m" checked={open} onCheckedChange={setOpen}>
+        <Switch.Label>Show tooltip programmatically</Switch.Label>
+        <Switch.Hint>
+          Hover or focus the button still updates <code>open</code> via <code>onOpenChange</code>.
+        </Switch.Hint>
+      </Switch.Root>
+      <Tooltip.Provider delayDuration={0}>
+        <Tooltip.Root open={open} onOpenChange={setOpen}>
+          <Tooltip.Trigger>
+            <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+              Trigger
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Controlled tooltip</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    </div>
+  );
+}

package/src/components/tooltip/examples/scenario-delay-provider.tsx

@@ -0,0 +1,19 @@
+import { Button, Tooltip } from "prime-ui-kit";
+
+/**
+ * Shared hover/focus delay via Tooltip.Provider (default is 400ms).
+ */
+export default function TooltipScenarioDelayProvider() {
+  return (
+    <Tooltip.Provider delayDuration={800}>
+      <Tooltip.Root>
+        <Tooltip.Trigger>
+          <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+            Hover slowly
+          </Button.Root>
+        </Tooltip.Trigger>
+        <Tooltip.Content>This tooltip opens after 800ms on hover or focus</Tooltip.Content>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  );
+}

package/src/components/tooltip/examples/scenario-long-content.tsx

@@ -0,0 +1,22 @@
+import { Button, Tooltip } from "prime-ui-kit";
+
+/**
+ * Long supplementary copy: tooltip content is clamped by theme max-width and wraps.
+ */
+export default function TooltipScenarioLongContent() {
+  return (
+    <Tooltip.Provider delayDuration={200}>
+      <Tooltip.Root>
+        <Tooltip.Trigger>
+          <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+            Password rules
+          </Button.Root>
+        </Tooltip.Trigger>
+        <Tooltip.Content size="m">
+          Use at least 12 characters with upper and lower case letters and numbers. Do not reuse
+          passwords from other sites; use a unique passphrase for this account.
+        </Tooltip.Content>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  );
+}

package/src/components/tooltip/examples/scenario-side-bottom.tsx

@@ -0,0 +1,21 @@
+import { Button, Tooltip } from "prime-ui-kit";
+
+/**
+ * Explicit placement: no automatic flip—pick side when the default clips.
+ */
+export default function TooltipScenarioSideBottom() {
+  return (
+    <Tooltip.Provider delayDuration={200}>
+      <Tooltip.Root>
+        <Tooltip.Trigger>
+          <Button.Root type="button" variant="neutral" mode="stroke" size="m">
+            Anchor near top
+          </Button.Root>
+        </Tooltip.Trigger>
+        <Tooltip.Content side="bottom" size="m">
+          Shown below the trigger; position is clamped to the viewport inset.
+        </Tooltip.Content>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  );
+}