prime-ui-kit 0.9.0 → 0.9.1

package/src/components/timeline/examples/sizes.tsx

@@ -1,38 +1,32 @@
-/** `size` scales text, dot and row rhythm: rows 40 · 52 · 64 · 68 · 76, default `m`. Use `s` in side panels, `m` in page content. */
-
-import { type ControlSize, Timeline, Typography } from "prime-ui-kit";
+/** 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: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TimelineSizesExample() {
   return (
     <div className={styles.stack}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.cell}>
-          <Typography.Root variant="code" tone="muted">
-            size="{size}"
-          </Typography.Root>
-          <Timeline.Root size={size}>
-            <Timeline.Group label="Недавно">
-              <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 active>
-                <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>
+      {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/src/components/timeline/examples/{service-history.tsx → structure.tsx}

@@ -1,21 +1,23 @@
-/** Service history: events and the intervals between them with `Timeline.Gap` (dashed segment, hollow dot, muted caption, `trailing`); `tone="warning"` flags a long interval, `Timeline.ValueMeta` adds a second value line. Use for maintenance and audit histories. */
-
+/** 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 TimelineServiceHistoryExample() {
+export default function TimelineStructureExample() {
   return (
     <Timeline.Root className={styles.feed}>
       <Timeline.Group label="История работ">
-        <Timeline.Gap trailing="сейчас">Без обслуживания 26 дней · 300 км</Timeline.Gap>
+        <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>
+            900 ₽<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
           </Timeline.Value>
         </Timeline.Item>
         <Timeline.Gap>40 дней · 2 200 км без обслуживания</Timeline.Gap>
@@ -25,7 +27,7 @@ export default function TimelineServiceHistoryExample() {
             <Timeline.MetaPrimary>01.08.26</Timeline.MetaPrimary> · 14 300 км
           </Timeline.Meta>
           <Timeline.Value>
-            1 500 ฿<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
+            1 500 ₽<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
           </Timeline.Value>
         </Timeline.Item>
         <Timeline.Gap>55 дней · 2 200 км без обслуживания</Timeline.Gap>
@@ -35,7 +37,7 @@ export default function TimelineServiceHistoryExample() {
             <Timeline.MetaPrimary>07.06.26</Timeline.MetaPrimary> · 12 100 км
           </Timeline.Meta>
           <Timeline.Value>
-            2 800 ฿<Timeline.ValueMeta>Ремонт</Timeline.ValueMeta>
+            2 800 ₽<Timeline.ValueMeta>Ремонт</Timeline.ValueMeta>
           </Timeline.Value>
         </Timeline.Item>
         <Timeline.Gap tone="warning">100 дней · 4 400 км без обслуживания</Timeline.Gap>
@@ -45,7 +47,7 @@ export default function TimelineServiceHistoryExample() {
             <Timeline.MetaPrimary>27.02.26</Timeline.MetaPrimary> · 7 700 км
           </Timeline.Meta>
           <Timeline.Value>
-            1 516 ฿<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
+            1 516 ₽<Timeline.ValueMeta>ТО</Timeline.ValueMeta>
           </Timeline.Value>
         </Timeline.Item>
       </Timeline.Group>

package/src/components/timeline/examples/{colors-and-tones.tsx → variants.tsx}

@@ -1,10 +1,9 @@
-/** Dot hues via `color` (decorative, reduced emphasis) and status via `tone` on items, values and gaps (full emphasis). Use `color` for categories, `tone` when the event has a status. */
-
+/** 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[] = [
+const COLORS: PaletteColor[] = [
   "gray",
   "blue",
   "sky",
@@ -17,21 +16,21 @@ const colors: PaletteColor[] = [
   "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 ฿" },
+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 TimelineColorsAndTonesExample() {
+export default function TimelineVariantsExample() {
   return (
     <div className={styles.stack}>
       <Timeline.Root>
         <Timeline.Group label="color">
-          {colors.map((color) => (
+          {COLORS.map((color) => (
             <Timeline.Item key={color} color={color}>
               <Timeline.Title>{color}</Timeline.Title>
               <Timeline.Meta>Категория события</Timeline.Meta>
@@ -41,19 +40,15 @@ export default function TimelineColorsAndTonesExample() {
       </Timeline.Root>
       <Timeline.Root>
         <Timeline.Group label="tone">
-          {tones.map(({ tone, title, value }) => (
+          {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="neutral">14 дней без событий</Timeline.Gap>
-          <Timeline.Gap tone="accent">Ожидаем ответ клиента</Timeline.Gap>
-          <Timeline.Gap tone="success">Оплачено в срок</Timeline.Gap>
           <Timeline.Gap tone="warning">Оплата задерживается 10 дней</Timeline.Gap>
           <Timeline.Gap tone="danger">Просрочка 30 дней</Timeline.Gap>
-          <Timeline.Gap tone="info">Автоматическое напоминание</Timeline.Gap>
         </Timeline.Group>
       </Timeline.Root>
     </div>

package/src/components/tooltip/COMPONENT.md

@@ -1,13 +1,14 @@
 # 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 (wrap the disabled control in a focusable element).
-- A one-line definition of a term or abbreviation in text.
+- 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).
@@ -23,58 +24,62 @@ import { Tooltip } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Tooltip.Provider        optional; shared show delay for a subtree
+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
     └── Tooltip.Content portaled role="tooltip" chip
+        └── arrow       decorative svg pointing at the trigger's centre
 ```
 
 ## API
 
-### Tooltip.Provider
-No DOM, no ref.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `delayDuration` | `number` | `400` | Show delay in ms for every Tooltip.Root inside. |
-| `children` | `ReactNode` | — (required) | Subtree. |
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Tooltip.Root
-No DOM, no ref. Works without a Provider (delay 400).
+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. |
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on hover, focus, blur, pointer-leave and Escape. |
-| `delayDuration` | `number` | from Provider (`400`) | Show delay in ms for this tooltip; hiding is immediate. |
+| `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 child (`cloneElement`), like `asChild`. Sets the child's `ref` (a `ref` on the child is replaced), merges `className`, appends `aria-describedby` while open, sets `data-state`, and chains `onMouseEnter`, `onMouseLeave`, `onFocus`, `onBlur`.
+No DOM: clones the single child, composes its `ref`, appends the tooltip id to its `aria-describedby` while open, sets `data-state` and chains `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus`, `onBlur`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactElement` | — (required) | Exactly one focusable element (Button, a `<button>`, a `tabIndex={0}` span around a disabled control). |
-| `className` | `string` | — | Merged with the child's `className`. |
+| `children` | `ReactElement` | — (required) | One focusable element: a Button, or a `tabIndex={0}` wrapper around a disabled control. |
 
 ### Tooltip.Content
-No ref. Rendered in a portal only while open (and during its exit animation).
+`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 side when it does not fit, then shifts inside the viewport. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text and padding tier; also the size context for controls inside (e.g. Kbd). |
-| `className` | `string` | — | Extra class on the chip. |
+| `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`), no arrow, no shadow, so it reads the same on canvas, cards and floating layers.
+Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-bg`, `tooltip-text`) with an arrow and no shadow, so it reads the same on canvas, cards and floating layers. 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)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | caption 12/16, padding 4 × 8, radius 6 | Next to xs controls | |
+| `xs` | caption 12/16, padding 4 × 8 | Next to xs controls | |
 | `s` | caption 12/16, padding 4 × 8 | Dense toolbars, s controls | |
 | `m` | caption 12/16, padding 4 × 8 | Most controls | yes |
 | `l` | body-s 13/20, padding 4 × 8 | l controls, longer sentences | |
@@ -83,65 +88,72 @@ Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-b
 ### side (Content)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `top` | Centred above the trigger, `--prime-space-1` away | Default for buttons in content | yes |
+| `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 | |
 
-**Combinations** — size of the tooltip = size of the trigger control; inside the chip use `Kbd` one tier smaller (`size="s"` tooltip → `size="xs"` Kbd).
+### 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
-- Closed / open: uncontrolled by default; `open` + `onOpenChange` for controlled. Opens after `delayDuration` on mouse-enter or focus; closes immediately on mouse-leave, blur or Escape.
-- Content DOM: `data-state="open" | "closed"` (closed during the fade-out), `data-size`, `data-side` (the resolved side after flipping), `data-positioned="true"` after the first measurement (invisible before), `data-overlay-portal-layer` (z-index layer when inside Modal / Drawer).
-- Trigger DOM: `data-state="open" | "closed"` on the child.
-- The chip has `pointer-events: none`, so it never blocks clicks on the trigger.
+| 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 motion comes from the shared overlay motion (fade + 4px from the anchor, fast).
+- 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
-- Content has `role="tooltip"`; the trigger gets `aria-describedby` pointing at it while open.
-- Opens on keyboard focus, closes on Escape with focus staying on the trigger (WAI-ARIA tooltip pattern).
-- The trigger must be focusable. A natively `disabled` button gets no pointer or focus events: wrap it in `<span tabIndex={0}>`.
-- Icon-only buttons need their own `aria-label`; the tooltip is a description, not the name.
-- No `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | `size` xs → xl next to matching buttons | Matching the tooltip to the control tier |
-| [long-content.tsx](examples/long-content.tsx) | Long text wrapping at max width (also shown on canvas, card and floating surfaces) | One-sentence explanations |
-| [states.tsx](examples/states.tsx) | Hover/focus, disabled button in a focusable span, inline term | Explaining unavailable actions and terms |
-| [side.tsx](examples/side.tsx) | `side` top · bottom · left · right | Placing near edges and in toolbars |
-| [controlled.tsx](examples/controlled.tsx) | `open` + `onOpenChange` driven by a Switch | Showing the hint programmatically |
-| [composition.tsx](examples/composition.tsx) | Icon-only toolbar with names and Kbd shortcuts | Toolbars |
-| [delay.tsx](examples/delay.tsx) | `delayDuration` 0 · default · 1000 | Tuning the show delay |
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focus on the trigger opens the tooltip after the delay. |
+| `Escape` | Hides the tooltip; focus stays on the trigger. |
 
-```tsx
-import { Button, Tooltip } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Tooltip.Root>
-      <Tooltip.Trigger>
-        <Button.Root variant="soft" tone="neutral">
-          Экспорт
-        </Button.Root>
-      </Tooltip.Trigger>
-      <Tooltip.Content>Выгрузка займёт около минуты</Tooltip.Content>
-    </Tooltip.Root>
-  );
-}
-```
+### ARIA
+- The chip is `role="tooltip"`; while open the trigger points at it with `aria-describedby`.
+- 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 natively `disabled` button gets no events: wrap it in `<span tabIndex={0}>`.
+
+### 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: a disabled button inside a focusable wrapper still shows its tooltip on hover and Tab — `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
 - Tooltip on a `disabled` button directly → wrap the button in a focusable `span`.
 - 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.
-- Passing a `ref` to the trigger child and expecting it to be kept → the trigger replaces it.
+- A Provider per tooltip in a toolbar → one Provider around the toolbar, so neighbours open instantly.
 
 ## Related
-[Popover](../popover/COMPONENT.md) · [Kbd](../kbd/COMPONENT.md) · [Button](../button/COMPONENT.md) · [Hint](../hint/COMPONENT.md)
+- **Built from:** —
+- **See also:** [Popover](../popover/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Button](../button/COMPONENT.md), [Hint](../hint/COMPONENT.md)

package/src/components/tooltip/examples/{controlled.tsx → controlled-open.tsx}

@@ -1,18 +1,16 @@
-/** Controlled tooltip: `open` + `onOpenChange` shared by hover and a switch. Use when another control or an onboarding step must show the hint. */
+/** The parent owns the open state: a switch shows the tooltip from code, hover and focus still work — `open`, `onOpenChange`. */
 import { Button, Switch, Tooltip } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
-export default function TooltipControlledExample() {
+export default function TooltipControlledOpenExample() {
   const [open, setOpen] = React.useState(false);
 
   return (
-    <div className={styles.column}>
+    <>
       <Switch.Root checked={open} onCheckedChange={setOpen}>
         <Switch.Label>Показать подсказку</Switch.Label>
       </Switch.Root>
-      <Tooltip.Root open={open} onOpenChange={setOpen} delayDuration={0}>
+      <Tooltip.Root open={open} onOpenChange={setOpen}>
         <Tooltip.Trigger>
           <Button.Root variant="soft" tone="neutral">
             Экспорт
@@ -20,6 +18,6 @@ export default function TooltipControlledExample() {
         </Tooltip.Trigger>
         <Tooltip.Content side="bottom">Выгрузка займёт около минуты</Tooltip.Content>
       </Tooltip.Root>
-    </div>
+    </>
   );
 }

package/src/components/tooltip/examples/delay.tsx

@@ -1,34 +1,25 @@
-/** `delayDuration` per Tooltip.Root: instant, default 400 ms and one second. Set it on Tooltip.Provider for a whole area or on one Root. */
+/** The show delay of one tooltip: at once, the default 400 ms and one second — `delayDuration`. */
 import { Button, Tooltip } from "prime-ui-kit";
-import styles from "./examples.module.css";
+
+const DELAYS = [
+  { label: "Сразу", delay: 0 },
+  { label: "400 мс", delay: 400 },
+  { label: "1 секунда", delay: 1000 },
+];
 
 export default function TooltipDelayExample() {
   return (
-    <div className={styles.row}>
-      <Tooltip.Root delayDuration={0}>
-        <Tooltip.Trigger>
-          <Button.Root variant="soft" tone="neutral">
-            Сразу
-          </Button.Root>
-        </Tooltip.Trigger>
-        <Tooltip.Content>delayDuration=0</Tooltip.Content>
-      </Tooltip.Root>
-      <Tooltip.Root>
-        <Tooltip.Trigger>
-          <Button.Root variant="soft" tone="neutral">
-            По умолчанию
-          </Button.Root>
-        </Tooltip.Trigger>
-        <Tooltip.Content>400 мс</Tooltip.Content>
-      </Tooltip.Root>
-      <Tooltip.Root delayDuration={1000}>
-        <Tooltip.Trigger>
-          <Button.Root variant="soft" tone="neutral">
-            Через секунду
-          </Button.Root>
-        </Tooltip.Trigger>
-        <Tooltip.Content>delayDuration=1000</Tooltip.Content>
-      </Tooltip.Root>
-    </div>
+    <>
+      {DELAYS.map(({ label, delay }) => (
+        <Tooltip.Root key={label} delayDuration={delay}>
+          <Tooltip.Trigger>
+            <Button.Root variant="soft" tone="neutral">
+              {label}
+            </Button.Root>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Черновик сохранится на сервере</Tooltip.Content>
+        </Tooltip.Root>
+      ))}
+    </>
   );
 }

package/src/components/tooltip/examples/disabled-trigger.tsx

@@ -0,0 +1,18 @@
+/** Why an action is unavailable: a disabled button inside a focusable wrapper still shows its tooltip on hover and Tab — `Tooltip.Trigger`. */
+import { Button, Tooltip } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TooltipDisabledTriggerExample() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        {/* biome-ignore lint/a11y/noNoninteractiveTabindex: the wrapper must be focusable to explain the disabled button */}
+        <span className={styles.disabledWrap} tabIndex={0}>
+          <Button.Root disabled>Опубликовать</Button.Root>
+        </span>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Заполните обязательные поля, чтобы опубликовать</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}

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

@@ -1,20 +1,6 @@
-/* Layout for the Tooltip examples: layout only, text goes through Typography. */
-
-.row {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: var(--prime-space-3);
-}
-
-.column {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-4);
-}
+/* Layout of the Tooltip scenarios: semantic tokens only. */
 
+/* toolbar.tsx: a raised strip of icon buttons. */
 .toolbar {
   display: flex;
   align-items: center;
@@ -25,23 +11,7 @@
   box-shadow: var(--prime-card-shadow);
 }
 
-.inlineHelpTrigger {
-  padding: 0;
-  border: 0;
-  background: none;
-  color: inherit;
-  font: inherit;
-  text-decoration: underline dotted;
-  text-underline-offset: var(--prime-space-1);
-  cursor: help;
-}
-
-.inlineHelpTrigger:focus-visible {
-  outline: var(--prime-focus-width) solid var(--prime-color-focus-ring);
-  outline-offset: var(--prime-focus-offset);
-  border-radius: var(--prime-radius-xs);
-}
-
+/* disabled-trigger.tsx: a focusable wrapper around the disabled button, with the outer ring. */
 .disabledWrap {
   display: inline-flex;
   border-radius: var(--prime-control-m-radius);

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

@@ -1,21 +1,18 @@
-/** A long hint that wraps at the tooltip max width. Use for a sentence of explanation; anything with actions belongs in a Popover. */
+/** A sentence of explanation wraps at the tooltip max width; anything with actions belongs in a Popover — `Tooltip.Content`. */
 import { Button, Tooltip } from "prime-ui-kit";
-import styles from "./examples.module.css";
 
 export default function TooltipLongContentExample() {
   return (
-    <div className={styles.row}>
-      <Tooltip.Root delayDuration={200}>
-        <Tooltip.Trigger>
-          <Button.Root variant="soft" tone="neutral">
-            Требования к паролю
-          </Button.Root>
-        </Tooltip.Trigger>
-        <Tooltip.Content size="l">
-          Не короче 12 символов, буквы разного регистра и цифры. Не используйте пароль от других
-          сервисов.
-        </Tooltip.Content>
-      </Tooltip.Root>
-    </div>
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Требования к паролю
+        </Button.Root>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        Не короче 12 символов, буквы разного регистра и цифры. Не используйте пароль от других
+        сервисов.
+      </Tooltip.Content>
+    </Tooltip.Root>
   );
 }

package/src/components/tooltip/examples/overview.tsx

@@ -0,0 +1,17 @@
+/** An icon-only button with a tooltip that repeats its name on hover and keyboard focus — `Tooltip.Trigger`, `Tooltip.Content`. */
+import { Button, Icon, Tooltip } from "prime-ui-kit";
+
+export default function TooltipOverviewExample() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <Button.Root variant="ghost" tone="neutral" aria-label="Скопировать ссылку">
+          <Button.Icon>
+            <Icon name="action.copy" />
+          </Button.Icon>
+        </Button.Root>
+      </Tooltip.Trigger>
+      <Tooltip.Content>Скопировать ссылку</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}