prime-ui-kit 0.10.0 → 0.11.1

package/dist/skill/reference/components/timeline/COMPONENT.md

@@ -0,0 +1,181 @@
+# Timeline
+
+**Category:** data-display
+**Kind:** composite
+
+> An event feed: dots on a thin line, event title and date, an optional amount on the right, grouped under labels.
+
+## When to use
+- Activity or operation history with dates and amounts (payments, rentals, orders).
+- Maintenance / audit history with intervals between events (`Timeline.Gap`).
+- A list of events where a row opens details (`onClick`, `href`, `asChild`).
+
+## When not to use
+- Steps of a process the user goes through → use [Stepper](../stepper/COMPONENT.md).
+- Records with many attributes to compare or sort → use [DataTable](../data-table/COMPONENT.md).
+- Transient system messages → use [Notification](../notification/COMPONENT.md).
+- Work with a start and an end laid out on a calendar (tasks, bookings, occupancy) → use [Gantt](../gantt/COMPONENT.md).
+
+## Import
+```tsx
+import { Timeline } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Timeline.Root                    size container, sets the tier
+└─ Timeline.Group label          labelled <ol>; the line runs from its first dot to its last
+   ├─ Timeline.Item              <li> + row (div | button | a | asChild element) with the dot
+   │  ├─ Timeline.Title          first line
+   │  ├─ Timeline.Meta           second line (date)
+   │  │  └─ Timeline.MetaPrimary emphasized part
+   │  └─ Timeline.Value          trailing amount
+   │     └─ Timeline.ValueMeta   second line under the amount
+   └─ Timeline.Gap               <li>: interval between events (dashed segment, hollow dot)
+      └─ Timeline.GapMeta        caption on the right («сейчас»)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Timeline.Root
+`ref` → `HTMLDivElement`. A size container that sets the tier for every group and row.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text, dot and row rhythm: rows 40 · 52 · 64 · 68 · 76 px. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `children` (`Timeline.Group`), `className` and the other div attributes. |
+
+### Timeline.Group
+`ref` → `HTMLOListElement`. A labelled `<ol>` of events; the line runs from its first dot to its last.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Group heading («Недавно»); names the list via `aria-labelledby`. |
+| `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "children">` | — | `children` (`Timeline.Item`, `Timeline.Gap`), `className` and the other ol attributes. |
+
+### Timeline.Item
+`ref` → the row element. An `<li>` with a row: `<div>`, `<button>` (`onClick`), `<a>` (`href`) or your element (`asChild`); the dot is prepended. The row under the pointer or keyboard focus is highlighted (pill, accent title and dot).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"blue"` | Decorative dot hue for categories, at reduced emphasis. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | — | Status dot color at full emphasis; wins over `color`. |
+| `onClick` | `MouseEventHandler<HTMLElement>` | — | Renders the row as a `<button>`. |
+| `href` | `string` | — | Renders the row as a link (with `target`, `rel`, `download`). |
+| `asChild` | `boolean` | `false` | Renders the row as the single child element (a router link). |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "color" \| "onClick">` | — | `children` (Title, Meta, Value), `className` and the other row attributes. |
+
+### Timeline.Title · Timeline.Meta · Timeline.MetaPrimary
+`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, accent on the highlighted row, wraps), the muted date line with tabular numbers, and its emphasized part.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### Timeline.Value · Timeline.ValueMeta
+`ref` → `HTMLSpanElement`. `<span>`: the trailing amount (right-aligned, tabular) and a muted second line under it. Moves under the meta below 20rem.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Value: text color (income `success`, refund `danger`). |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### Timeline.Gap
+`ref` → `HTMLDivElement`. An `<li>` interval between events: a shorter row with a hollow dot on a dashed segment and a muted caption.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Caption and dot color; `warning` / `danger` flag a long interval. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `children` (the interval caption and an optional `Timeline.GapMeta`), `className` and the other div attributes. |
+
+### Timeline.GapMeta
+`ref` → `HTMLSpanElement`. A caption on the right of the gap («сейчас»), in the gap tone.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | rows 40, title 12/16, dot 8 | very dense side panels | |
+| `s` | rows 52, title 13/20 | side panels, drawers | |
+| `m` | rows 64, title 14/20, dot 10 | page content and cards | yes |
+| `l` · `xl` | rows 68 / 76, title 16/24, dot 12 | spacious feeds, detail pages | |
+
+### color (Item)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `blue` | blue dot at reduced emphasis | default category | yes |
+| `gray` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | dot in the hue | categories | |
+
+### tone (Item · Value · Gap)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | muted dot / primary value / muted gap caption | a status without meaning | Value, Gap |
+| `accent` | accent | a pending action | |
+| `success` | success | paid, income | |
+| `warning` | warning | overdue, a too-long interval | |
+| `danger` | danger | refund, failure | |
+| `info` | info | informational events | |
+
+On an Item `tone` wins over `color` and shows at full emphasis.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| tier | `size` | `data-size` on the root |
+| highlighted | pointer over the row, keyboard focus | `:hover`, `:focus-visible`: `fill-subtle-active` pill, accent title and dot (a `tone` keeps its dot) |
+| dot color | `color` / `tone` | `data-color` (without a tone) or `data-tone` |
+| interactive | `onClick`, `href`, `asChild` | `data-interactive`; pointer cursor, inset focus ring |
+
+Timeline keeps no state and has no persistent selection: every row is highlighted only while it is under the pointer or focused.
+
+## Layout & spacing
+- The root is a size container: give it a definite width (`width: min(100%, 30rem)`).
+- Row grid: dot column · text · value; below 20rem of root width the value moves under the meta line.
+- Rows touch so the line is continuous; group → group `--prime-space-4`.
+- Inside a Card put it in `Card.Body`; the card owns the padding.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Interactive rows are one Tab stop each; the focus ring is drawn inside the row. |
+| `Enter` · `Space` | Activates a button row; Enter opens a link row. |
+
+### ARIA
+- Each group is an `<ol>` labelled by its heading (`aria-labelledby`); events are `<li>`.
+- The dot is `aria-hidden`: put the status into the title or meta, not only the dot color.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.Value`. |
+| [variants.tsx](examples/variants.tsx) | Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. |
+| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.GapMeta`, `Timeline.ValueMeta`. |
+| [links.tsx](examples/links.tsx) | Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. |
+| [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line. |
+
+## Mistakes
+- `Timeline.Item` outside `Timeline.Group` → items are `<li>`; always wrap them in a group.
+- A process with steps → use Stepper.
+- Status only by dot color → put it in the title or meta too.
+- `<div onClick>` inside an item → pass `onClick` to `Timeline.Item` (native button, focus ring).
+- `Timeline.Root` in a shrink-wrapped flex parent → give it a width.
+- Using the timeline to pick a row (a selected / current state) → it has none; use a list with selection (`Select`, `DataTable` row selection) or `Tabs`.
+
+## Related
+- **Built from:** —
+- **See also:** [Stepper](../stepper/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Gantt](../gantt/COMPONENT.md), [Card](../card/COMPONENT.md)

package/dist/skill/reference/components/timeline/examples/examples.module.css

@@ -0,0 +1,25 @@
+/* Layout of the Timeline scenarios. The root is a size container: give it a definite width,
+   a shrink-wrapped container collapses. */
+
+/* 30rem feed. */
+.feed {
+  width: min(100%, calc(var(--prime-space-24) * 5));
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-10);
+  width: min(100%, calc(var(--prime-space-24) * 5));
+  min-width: 0;
+}
+
+/* narrow.tsx: a 375px phone column. */
+.phone {
+  width: min(100%, calc(var(--prime-space-1) * 93.75));
+}
+
+/* narrow.tsx: 280px, below the 20rem container breakpoint. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-10) * 7));
+}

package/dist/skill/reference/components/timeline/examples/links.tsx

@@ -0,0 +1,28 @@
+/** Rows that open an operation page become links, one Tab stop each with a focus ring — `href`. */
+import { Timeline } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  { id: "rent-ivan", title: "Аренда закончилась · Иван К.", date: "21.09.26", value: "+6 300 ₽" },
+  { id: "oil", title: "ТО: замена масла", date: "10.09.26", value: "−689 ₽" },
+  { id: "wash", title: "Мойка и химчистка салона", date: "01.09.26", value: "−450 ₽" },
+];
+
+export default function TimelineLinksExample() {
+  return (
+    <Timeline.Root className={styles.feed}>
+      <Timeline.Group label="Операции">
+        {EVENTS.map((event) => (
+          <Timeline.Item key={event.id} href={`#${event.id}`}>
+            <Timeline.Title>{event.title}</Timeline.Title>
+            <Timeline.Meta>
+              <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary>
+            </Timeline.Meta>
+            <Timeline.Value>{event.value}</Timeline.Value>
+          </Timeline.Item>
+        ))}
+      </Timeline.Group>
+    </Timeline.Root>
+  );
+}

package/dist/skill/reference/components/timeline/examples/narrow.tsx

@@ -0,0 +1,41 @@
+/** At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line. */
+import { Timeline } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WIDTHS = [
+  { id: "phone", className: styles.phone, label: "375 px" },
+  { id: "narrow", className: styles.narrow, label: "280 px" },
+];
+
+const EVENTS = [
+  { id: 1, title: "Аренда закончилась · Марина Л.", date: "17.07.26", value: "+9 450 ₽" },
+  {
+    id: 2,
+    title: "ТО: замена масла и фильтров, проверка тормозов",
+    date: "10.09.26",
+    value: "−689 ₽",
+  },
+];
+
+export default function TimelineNarrowExample() {
+  return (
+    <div className={styles.stack}>
+      {WIDTHS.map((width) => (
+        <Timeline.Root key={width.id} className={width.className}>
+          <Timeline.Group label={width.label}>
+            {EVENTS.map((event) => (
+              <Timeline.Item key={event.id}>
+                <Timeline.Title>{event.title}</Timeline.Title>
+                <Timeline.Meta>
+                  <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary>
+                </Timeline.Meta>
+                <Timeline.Value>{event.value}</Timeline.Value>
+              </Timeline.Item>
+            ))}
+          </Timeline.Group>
+        </Timeline.Root>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/timeline/examples/overview.tsx

@@ -0,0 +1,47 @@
+/** An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.Value`. */
+import { Timeline } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  {
+    id: 1,
+    title: "Аренда закончилась · Иван К.",
+    date: "21.09.26",
+    ago: "15 д. назад",
+    value: "+6 300 ₽",
+  },
+  { id: 2, title: "ТО: замена масла", date: "10.09.26", ago: "26 д. назад", value: "−689 ₽" },
+  {
+    id: 3,
+    title: "Аренда закончилась · Сергей М.",
+    date: "04.09.26",
+    ago: "32 д. назад",
+    value: "+13 500 ₽",
+  },
+  {
+    id: 4,
+    title: "Аренда закончилась · Амир Х.",
+    date: "30.07.26",
+    ago: "68 д. назад",
+    value: "+5 400 ₽",
+  },
+];
+
+export default function TimelineOverviewExample() {
+  return (
+    <Timeline.Root className={styles.feed}>
+      <Timeline.Group label="Недавно">
+        {EVENTS.map((event) => (
+          <Timeline.Item key={event.id}>
+            <Timeline.Title>{event.title}</Timeline.Title>
+            <Timeline.Meta>
+              <Timeline.MetaPrimary>{event.date}</Timeline.MetaPrimary> · {event.ago}
+            </Timeline.Meta>
+            <Timeline.Value>{event.value}</Timeline.Value>
+          </Timeline.Item>
+        ))}
+      </Timeline.Group>
+    </Timeline.Root>
+  );
+}

package/dist/skill/reference/components/timeline/examples/sizes.tsx

@@ -0,0 +1,33 @@
+/** Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. */
+import { Timeline } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function TimelineSizesExample() {
+  return (
+    <div className={styles.stack}>
+      {SIZES.map((size) => (
+        <Timeline.Root key={size} size={size}>
+          <Timeline.Group label={size}>
+            <Timeline.Item>
+              <Timeline.Title>Аренда закончилась · Иван К.</Timeline.Title>
+              <Timeline.Meta>
+                <Timeline.MetaPrimary>21.09.26</Timeline.MetaPrimary> · 15 д. назад
+              </Timeline.Meta>
+              <Timeline.Value>+6 300 ₽</Timeline.Value>
+            </Timeline.Item>
+            <Timeline.Item>
+              <Timeline.Title>ТО: замена масла</Timeline.Title>
+              <Timeline.Meta>
+                <Timeline.MetaPrimary>10.09.26</Timeline.MetaPrimary> · 26 д. назад
+              </Timeline.Meta>
+              <Timeline.Value>−689 ₽</Timeline.Value>
+            </Timeline.Item>
+          </Timeline.Group>
+        </Timeline.Root>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/timeline/examples/structure.tsx

@@ -0,0 +1,56 @@
+/** A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.GapMeta`, `Timeline.ValueMeta`. */
+import { Timeline } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TimelineStructureExample() {
+  return (
+    <Timeline.Root className={styles.feed}>
+      <Timeline.Group label="История работ">
+        <Timeline.Gap>
+          Без обслуживания 26 дней · 300 км
+          <Timeline.GapMeta>сейчас</Timeline.GapMeta>
+        </Timeline.Gap>
+        <Timeline.Item color="blue">
+          <Timeline.Title>ТО: замена масла</Timeline.Title>
+          <Timeline.Meta>
+            <Timeline.MetaPrimary>10.09.26</Timeline.MetaPrimary> · 16 500 км
+          </Timeline.Meta>
+          <Timeline.Value>
+            900 ₽<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
+          </Timeline.Value>
+        </Timeline.Item>
+        <Timeline.Gap>40 дней · 2 200 км без обслуживания</Timeline.Gap>
+        <Timeline.Item color="blue">
+          <Timeline.Title>ТО: масло + колодки</Timeline.Title>
+          <Timeline.Meta>
+            <Timeline.MetaPrimary>01.08.26</Timeline.MetaPrimary> · 14 300 км
+          </Timeline.Meta>
+          <Timeline.Value>
+            1 500 ₽<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
+          </Timeline.Value>
+        </Timeline.Item>
+        <Timeline.Gap>55 дней · 2 200 км без обслуживания</Timeline.Gap>
+        <Timeline.Item color="red">
+          <Timeline.Title>Ремонт: замена ремня</Timeline.Title>
+          <Timeline.Meta>
+            <Timeline.MetaPrimary>07.06.26</Timeline.MetaPrimary> · 12 100 км
+          </Timeline.Meta>
+          <Timeline.Value>
+            2 800 ₽<Timeline.ValueMeta>Ремонт</Timeline.ValueMeta>
+          </Timeline.Value>
+        </Timeline.Item>
+        <Timeline.Gap tone="warning">100 дней · 4 400 км без обслуживания</Timeline.Gap>
+        <Timeline.Item color="blue">
+          <Timeline.Title>Резина зад + работа</Timeline.Title>
+          <Timeline.Meta>
+            <Timeline.MetaPrimary>27.02.26</Timeline.MetaPrimary> · 7 700 км
+          </Timeline.Meta>
+          <Timeline.Value>
+            1 516 ₽<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
+          </Timeline.Value>
+        </Timeline.Item>
+      </Timeline.Group>
+    </Timeline.Root>
+  );
+}

package/dist/skill/reference/components/timeline/examples/variants.tsx

@@ -0,0 +1,56 @@
+/** Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. */
+import { type PaletteColor, Timeline, type Tone } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const COLORS: PaletteColor[] = [
+  "gray",
+  "blue",
+  "sky",
+  "teal",
+  "green",
+  "yellow",
+  "orange",
+  "red",
+  "pink",
+  "purple",
+];
+
+const TONES: { tone: Tone; title: string; value: string }[] = [
+  { tone: "neutral", title: "Черновик сохранён", value: "0 ₽" },
+  { tone: "accent", title: "Счёт выставлен", value: "4 200 ₽" },
+  { tone: "success", title: "Оплата получена", value: "+4 200 ₽" },
+  { tone: "warning", title: "Оплата просрочена", value: "4 200 ₽" },
+  { tone: "danger", title: "Возврат средств", value: "−4 200 ₽" },
+  { tone: "info", title: "Напоминание отправлено", value: "—" },
+];
+
+export default function TimelineVariantsExample() {
+  return (
+    <div className={styles.stack}>
+      <Timeline.Root>
+        <Timeline.Group label="color">
+          {COLORS.map((color) => (
+            <Timeline.Item key={color} color={color}>
+              <Timeline.Title>{color}</Timeline.Title>
+              <Timeline.Meta>Категория события</Timeline.Meta>
+            </Timeline.Item>
+          ))}
+        </Timeline.Group>
+      </Timeline.Root>
+      <Timeline.Root>
+        <Timeline.Group label="tone">
+          {TONES.map(({ tone, title, value }) => (
+            <Timeline.Item key={tone} tone={tone}>
+              <Timeline.Title>{title}</Timeline.Title>
+              <Timeline.Meta>{tone}</Timeline.Meta>
+              <Timeline.Value tone={tone}>{value}</Timeline.Value>
+            </Timeline.Item>
+          ))}
+          <Timeline.Gap tone="warning">Оплата задерживается 10 дней</Timeline.Gap>
+          <Timeline.Gap tone="danger">Просрочка 30 дней</Timeline.Gap>
+        </Timeline.Group>
+      </Timeline.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/tooltip/COMPONENT.md

@@ -0,0 +1,167 @@
+# Tooltip
+
+**Category:** overlays
+**Kind:** overlay
+
+> A short hint that appears next to an element on hover or keyboard focus.
+
+## When to use
+- Name and shortcut of an icon-only button.
+- Why a control is disabled: put the disabled control straight into `Tooltip.Trigger`.
+- What a status badge, an avatar or an information icon means.
+- A one-line definition of a term or abbreviation.
+
+## When not to use
+- Content with links, buttons or fields, or anything the user must read to continue → use [Popover](../popover/COMPONENT.md).
+- A list of actions → use [Dropdown](../dropdown/COMPONENT.md).
+- Help text under a field → use the field `hint` or [Hint](../hint/COMPONENT.md).
+- Status messages → use [Notification](../notification/COMPONENT.md) or [Banner](../banner/COMPONENT.md).
+- The only label of an icon-only button → the button still needs `aria-label`; the tooltip only repeats it.
+
+## Import
+```tsx
+import { Tooltip } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Tooltip.Provider        optional; delay and skip-delay group for a subtree
+└── Tooltip.Root        state of one tooltip (no DOM)
+    ├── Tooltip.Trigger clones its single child element and adds handlers
+    │                   (a focusable <span> around a disabled control)
+    └── Tooltip.Content portaled role="tooltip" chip
+        └── arrow       decorative svg pointing at the trigger's centre
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Tooltip.Root
+No DOM, no ref. State of one tooltip; without a Provider it joins the kit-wide default group (400 / 300).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
+| `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on hover, focus, blur, pointer-leave, press, Escape, and when a neighbour in the group opens. |
+| `delayDuration` | `number` | `400` | Show delay in ms for this tooltip (the Provider's when omitted); hiding never waits for it. |
+| `children` | `ReactNode` | — (required) | Tooltip.Trigger and Tooltip.Content. |
+
+### Tooltip.Provider
+No DOM, no ref. Its tooltips form a group: one is open at a time, and once one has been shown the next opens at once and without motion, until `skipDelayDuration` passes with none open.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `delayDuration` | `number` | `400` | Show delay in ms for every Tooltip.Root inside. |
+| `skipDelayDuration` | `number` | `300` | Window in ms after a tooltip closes during which the next one opens instantly. |
+| `children` | `ReactNode` | — (required) | Subtree. |
+
+### Tooltip.Trigger
+No DOM of its own: clones the single child and links it to the tooltip with `aria-describedby`. A `disabled` child is wrapped in a focusable `<span>`; a child that is no tab stop becomes one.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element: a control, a disabled control or a non-interactive element such as a Badge. |
+
+### Tooltip.Content
+`ref` → `HTMLDivElement`. Portaled `role="tooltip"` chip with an arrow; renders while open and during its exit animation, placed before paint.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Preferred side; flips to the opposite one when it does not fit, then shifts inside the viewport. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the trigger: its start edge, centre or end edge; the arrow keeps pointing at the trigger. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text and padding tier; also the size context of controls inside (a Kbd). |
+| `children` | `ReactNode` | — (required) | Hint text, optionally with a Kbd. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "role" \| "onPointerEnter" \| "onPointerLeave">` | — | `className`, `style` and the other attributes of the chip. |
+
+## Variants
+Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-bg`, `tooltip-text`) — dark in the light theme, light in the dark one — with an arrow and no shadow, so it reads the same on every layer. The chip is a host of its own: it points the text and fill roles at `tooltip-muted` / `tooltip-fill`, so a Kbd or a secondary line inside reads on it. Content flows inline: a label and its key stay on one line, block children stack. The arrow (`--prime-tooltip-arrow-width` × `--prime-tooltip-arrow-height`) always points at the trigger's centre, also after flipping, aligning or shifting, and never slides into the chip's rounded corner.
+
+### size (Content)
+A chip of tier T is as tall as a menu item of tier T; text, padding and radius step together (`--prime-tooltip-<tier>-*`).
+
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 12/16, padding 4 × 6, radius 4 — 24 tall | Next to xs controls | |
+| `s` | 12/16, padding 6 × 8, radius 6 — 28 tall | Dense toolbars, s controls | |
+| `m` | 13/20, padding 6 × 10, radius 6 — 32 tall | Most controls | yes |
+| `l` | 14/20, padding 8 × 12, radius 8 — 36 tall | l controls, longer sentences | |
+| `xl` | 16/24, padding 8 × 16, radius 8 — 40 tall | xl controls | |
+
+### side (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `top` | Centred above the trigger, `--prime-tooltip-offset` away (the arrow sits in the gap) | Buttons in content | yes |
+| `bottom` | Centred below the trigger | Toolbars at the top of a screen | |
+| `left` | Vertically centred, to the left | Triggers near the right edge | |
+| `right` | Vertically centred, to the right | Sidebar / rail icons | |
+
+### align (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | Chip starts at the trigger's start edge | Wide triggers, triggers at a container's start | |
+| `center` | Chip centred on the trigger | Most triggers | yes |
+| `end` | Chip ends at the trigger's end edge | Triggers at a container's end | |
+
+**Combinations** — size of the tooltip = size of the trigger control; a Kbd inside takes the tier one step down by itself.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| open / closed | hover (mouse, pen) or focus after `delayDuration`; `open` / `onOpenChange` | `data-state="open" \| "closed"` on the chip (closed during the exit) and on the trigger |
+| closing | blur, a press on the trigger, Escape, pointer leaving (unless it moves onto the chip) | — |
+| warm group | another tooltip of the Provider was just shown | `data-instant="true"`: opens and leaves without motion |
+| side | `side` and the room around the trigger | `data-side` (resolved), `data-align` |
+| size | `size` | `data-size` |
+
+## Layout & spacing
+- Max width `--prime-tooltip-max-width`, never wider than the viewport minus `--prime-space-4`; text wraps (`overflow-wrap: anywhere`).
+- Kept `--prime-space-2` from viewport edges; repositions on scroll and resize.
+- Enter / exit come from the shared overlay motion (fade + `--prime-space-1` + scale 0.98, fast), growing from the arrow tip; instant inside a warm group.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focus on the trigger opens the tooltip after the delay. |
+| `Escape` | Hides the tooltip; focus stays on the trigger. |
+
+### ARIA
+- The chip is `role="tooltip"`; while open the trigger points at it with `aria-describedby` (appended to the child's own).
+- `Tooltip.Trigger` composes the child's `ref`, sets `data-state` and chains the child's `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus` and `onBlur`.
+- The tooltip is a description, not the name: an icon-only button needs its own `aria-label`.
+- The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, focus does.
+- A `disabled` control is wrapped by the kit in a focusable `<span>`: the host takes hover and Tab, the focus ring is drawn on the control.
+- A trigger that is no tab stop (Badge, Avatar, ProgressCircle, `Icon` with `label`) gets `tabIndex={0}` and the focus ring; its name comes from `aria-label` or the icon `label`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | An icon-only button with a tooltip that repeats its name on hover and keyboard focus — `Tooltip.Trigger`, `Tooltip.Content`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier next to buttons of the same tier; take the tier of the control it describes — `size`. |
+| [placement.tsx](examples/placement.tsx) | Every side, and start / end alignment along the trigger; without room the chip flips and shifts, the arrow keeps pointing at the trigger — `side`, `align`. |
+| [toolbar.tsx](examples/toolbar.tsx) | A formatting toolbar in one group: after the first tooltip the neighbours open at once, each with its name and shortcut — `Tooltip.Provider`. |
+| [disabled-trigger.tsx](examples/disabled-trigger.tsx) | Why an action is unavailable: the disabled button still shows its tooltip on hover and Tab, no wrapper needed — `Tooltip.Trigger`. |
+| [non-interactive-trigger.tsx](examples/non-interactive-trigger.tsx) | A status badge, an avatar and an information icon explain themselves: the kit makes each a tab stop, so the tooltip opens from the keyboard too — `Tooltip.Trigger`. |
+| [delay.tsx](examples/delay.tsx) | The show delay of one tooltip: at once, the default 400 ms and one second — `delayDuration`. |
+| [long-content.tsx](examples/long-content.tsx) | A sentence of explanation wraps at the tooltip max width; anything with actions belongs in a Popover — `Tooltip.Content`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: a switch shows the tooltip from code, hover and focus still work — `open`, `onOpenChange`. |
+
+## Mistakes
+- Your own `<span tabIndex={0}>` around a disabled button → the trigger does it; a second wrapper adds a second tab stop.
+- An unnamed Badge or Icon as the trigger → give the icon `label` (or the element `aria-label`): the tooltip describes, it does not name.
+- Links or buttons inside Tooltip.Content → use Popover.
+- Several children inside Tooltip.Trigger → exactly one element.
+- Relying on the tooltip as the button's name → add `aria-label` to the button.
+- A Provider per tooltip in a toolbar → one Provider around the toolbar, so neighbours open instantly.
+
+## Related
+- **Built from:** —
+- **See also:** [Popover](../popover/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Button](../button/COMPONENT.md), [Hint](../hint/COMPONENT.md)