@estiva-app/ui 0.9.0 → 0.10.1

package/src/Toolbar.stories.tsx

@@ -0,0 +1,142 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconArrowBackUp, IconArrowForwardUp, IconBold, IconItalic, IconLink, IconSquareRounded, IconUnderline } from '@tabler/icons-react'
+import { useState } from 'react'
+import { IconButton } from './IconButton'
+import { Popover } from './Popover'
+import { Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from './Toolbar'
+
+/**
+ * A strip of controls that behaves as **one** control: Tab in, arrow keys
+ * along, Tab out.
+ *
+ * It draws the elevated box a floating strip needs — the same one a `Menu`
+ * draws — so a toolbar over a card, a paragraph or an image is separated from
+ * it without the caller drawing anything.
+ */
+const meta = {
+  title: 'Primitives/Toolbar',
+  component: Toolbar,
+  args: { 'aria-label': 'Formatting', children: null },
+  argTypes: { children: { control: false } },
+} satisfies Meta<typeof Toolbar>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const icon = <IconSquareRounded size={16} stroke={1.5} />
+
+/** Four controls, one Tab stop. */
+export const Default: Story = {
+  render: (args) => (
+    <Toolbar {...args}>
+      <ToolbarButton aria-label="Item one" tooltip="Item one">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item two" tooltip="Item two">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item three" tooltip="Item three">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item four" tooltip="Item four">{icon}</ToolbarButton>
+    </Toolbar>
+  ),
+}
+
+/** Groups, divided. The separator carries the role as well as the hairline. */
+export const Grouped: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Toolbar aria-label="Formatting">
+      <ToolbarButton aria-label="Undo" tooltip="Undo" tooltipShortcut="Cmd+Z">
+        <IconArrowBackUp size={16} stroke={1.5} />
+      </ToolbarButton>
+      <ToolbarButton aria-label="Redo" tooltip="Redo" tooltipShortcut="Cmd+Shift+Z">
+        <IconArrowForwardUp size={16} stroke={1.5} />
+      </ToolbarButton>
+      <ToolbarSeparator />
+      <ToolbarButton aria-label="Bold" tooltip="Bold" tooltipShortcut="Cmd+B">
+        <IconBold size={16} stroke={1.5} />
+      </ToolbarButton>
+      <ToolbarButton aria-label="Italic" tooltip="Italic" tooltipShortcut="Cmd+I">
+        <IconItalic size={16} stroke={1.5} />
+      </ToolbarButton>
+      <ToolbarButton aria-label="Underline" tooltip="Underline" tooltipShortcut="Cmd+U">
+        <IconUnderline size={16} stroke={1.5} />
+      </ToolbarButton>
+    </Toolbar>
+  ),
+}
+
+/**
+ * A field in the strip. While it has focus the arrow keys are the caret's —
+ * which is what a field is for — and Tab resumes the walk. That is why a field
+ * in a toolbar is `ToolbarInput` rather than a `TextInput` dropped in the row.
+ */
+export const WithAField: Story = {
+  parameters: { controls: { disable: true } },
+  render: function WithField() {
+    const [url, setUrl] = useState('')
+    return (
+      <Toolbar aria-label="Link">
+        <ToolbarButton aria-label="Link" tooltip="Link">
+          <IconLink size={16} stroke={1.5} />
+        </ToolbarButton>
+        <ToolbarSeparator />
+        <ToolbarInput value={url} onChange={(e) => setUrl(e.target.value)} placeholder="Paste a link" aria-label="Link address" className="h-7 w-48" />
+      </Toolbar>
+    )
+  },
+}
+
+/**
+ * A control that cannot be used **keeps its place in the walk**. A strip whose
+ * controls come and go from the arrow keys as their state changes is a strip
+ * you cannot learn — and a `disabledReason` you cannot reach is a reason
+ * nobody reads.
+ */
+export const WithADisabledControl: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Toolbar aria-label="Formatting">
+      <ToolbarButton aria-label="Item one" tooltip="Item one">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item two" disabledReason="Available once there is a selection">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item three" tooltip="Item three">{icon}</ToolbarButton>
+    </Toolbar>
+  ),
+}
+
+/** Down rather than across: ↑ and ↓ walk it. */
+export const Vertical: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Toolbar aria-label="Formatting" orientation="vertical">
+      <ToolbarButton aria-label="Item one" tooltip="Item one" tooltipPlacement="bottom">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item two" tooltip="Item two" tooltipPlacement="bottom">{icon}</ToolbarButton>
+      <ToolbarButton aria-label="Item three" tooltip="Item three" tooltipPlacement="bottom">{icon}</ToolbarButton>
+    </Toolbar>
+  ),
+}
+
+/**
+ * **Inside something that already draws a box** — a `Popover`, a dialog, a
+ * card's own panel — the strip drops its own with `surface={false}`. Two
+ * boxes inside each other is the tell.
+ */
+export const OnAnExistingSurface: Story = {
+  parameters: { controls: { disable: true }, layout: 'fullscreen' },
+  render: () => (
+    <div className="flex h-[220px] w-full items-end justify-center pb-4">
+    <Popover
+      /* An `IconButton`, not a `ToolbarButton`: the trigger stands outside the
+         strip, and a toolbar part outside a `Toolbar` throws. */
+      trigger={<IconButton aria-label="Open" tooltip="Open">{icon}</IconButton>}
+      ariaLabel="Formatting"
+      /* Above the control that opened it: a strip acts on what is under it.
+         `side` is the preference; Base UI flips it when there is no room. */
+      side="top"
+      className="w-auto min-w-0 p-1"
+    >
+      <Toolbar aria-label="Formatting" surface={false}>
+        <ToolbarButton aria-label="Item one" tooltip="Item one">{icon}</ToolbarButton>
+        <ToolbarButton aria-label="Item two" tooltip="Item two">{icon}</ToolbarButton>
+        <ToolbarButton aria-label="Item three" tooltip="Item three">{icon}</ToolbarButton>
+      </Toolbar>
+    </Popover>
+    </div>
+  ),
+}

package/src/Toolbar.test.tsx

@@ -0,0 +1,253 @@
+// @vitest-environment jsdom
+/**
+ * What the Toolbar page claims, pinned — and the reason the component exists
+ * is the first test: a strip of controls is one Tab stop, not one per button.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { IconButton } from './IconButton'
+import { Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from './Toolbar'
+import { Menu, MenuItem } from './Menu'
+import { Popover } from './Popover'
+
+afterEach(cleanup)
+
+const dot = <span aria-hidden="true">·</span>
+
+function Strip({ label = 'Formatting' }: { label?: string }) {
+  return (
+    <>
+      <button type="button">Before</button>
+      <Toolbar aria-label={label}>
+        <ToolbarButton aria-label="One">{dot}</ToolbarButton>
+        <ToolbarButton aria-label="Two">{dot}</ToolbarButton>
+        <ToolbarButton aria-label="Three">{dot}</ToolbarButton>
+      </Toolbar>
+      <button type="button">After</button>
+    </>
+  )
+}
+
+const focused = () => document.activeElement?.getAttribute('aria-label') ?? document.activeElement?.textContent
+
+describe('Toolbar', () => {
+  it('is a named toolbar', () => {
+    render(<Strip />)
+    expect(screen.getByRole('toolbar', { name: 'Formatting' })).toBeTruthy()
+  })
+
+  /** The whole point. Three buttons, one stop. */
+  it('is one Tab stop, whatever it holds', async () => {
+    const user = userEvent.setup()
+    render(<Strip />)
+    screen.getByRole('button', { name: 'Before' }).focus()
+    await user.tab()
+    expect(focused()).toBe('One')
+    await user.tab()
+    expect(focused()).toBe('After')
+  })
+
+  it('and coming back lands on the toolbar, not inside it', async () => {
+    const user = userEvent.setup()
+    render(<Strip />)
+    screen.getByRole('button', { name: 'After' }).focus()
+    await user.tab({ shift: true })
+    expect(focused()).toBe('One')
+  })
+
+  it('the arrow keys walk it, and wrap', async () => {
+    const user = userEvent.setup()
+    render(<Strip />)
+    screen.getByRole('button', { name: 'One' }).focus()
+    await user.keyboard('{ArrowRight}')
+    expect(focused()).toBe('Two')
+    await user.keyboard('{ArrowRight}{ArrowRight}')
+    expect(focused()).toBe('One')
+    await user.keyboard('{ArrowLeft}')
+    expect(focused()).toBe('Three')
+  })
+
+  /**
+   * The gap, pinned as a gap. Base UI's composite implements Home and End
+   * behind `enableHomeAndEndKeys`, and `Toolbar.Root` does not pass it — so
+   * they do nothing here, the page does not claim them, and this test fails
+   * the day that changes.
+   */
+  it('Home and End do nothing, which is Base UI’s choice and is stated', async () => {
+    const user = userEvent.setup()
+    render(<Strip />)
+    screen.getByRole('button', { name: 'Two' }).focus()
+    await user.keyboard('{End}')
+    expect(focused()).toBe('Two')
+    await user.keyboard('{Home}')
+    expect(focused()).toBe('Two')
+  })
+
+  it('a vertical toolbar walks with ↑ and ↓', async () => {
+    const user = userEvent.setup()
+    render(
+      <Toolbar aria-label="Formatting" orientation="vertical">
+        <ToolbarButton aria-label="One">{dot}</ToolbarButton>
+        <ToolbarButton aria-label="Two">{dot}</ToolbarButton>
+      </Toolbar>,
+    )
+    expect(screen.getByRole('toolbar').getAttribute('aria-orientation')).toBe('vertical')
+    screen.getByRole('button', { name: 'One' }).focus()
+    await user.keyboard('{ArrowDown}')
+    expect(focused()).toBe('Two')
+  })
+
+  it('a button still runs its onClick, and is still an IconButton', async () => {
+    const user = userEvent.setup()
+    const onClick = vi.fn()
+    render(
+      <Toolbar aria-label="Formatting">
+        <ToolbarButton aria-label="One" onClick={onClick}>{dot}</ToolbarButton>
+      </Toolbar>,
+    )
+    const button = screen.getByRole('button', { name: 'One' })
+    expect(button.tagName).toBe('BUTTON')
+    await user.click(button)
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  /**
+   * A strip whose controls come and go from the arrow keys as their state
+   * changes is a strip you cannot learn — and a `disabledReason` you cannot
+   * reach is a reason nobody reads.
+   */
+  it('a disabled control keeps its place in the walk', async () => {
+    const user = userEvent.setup()
+    render(
+      <Toolbar aria-label="Formatting">
+        <ToolbarButton aria-label="One">{dot}</ToolbarButton>
+        <ToolbarButton aria-label="Two" disabledReason="Not yet">{dot}</ToolbarButton>
+        <ToolbarButton aria-label="Three">{dot}</ToolbarButton>
+      </Toolbar>,
+    )
+    screen.getByRole('button', { name: 'One' }).focus()
+    await user.keyboard('{ArrowRight}')
+    expect(focused()).toBe('Two')
+    expect(screen.getByRole('button', { name: 'Two' }).getAttribute('aria-disabled')).toBe('true')
+  })
+
+  /** The box, which a floating strip needs and Peek had drawn twice. */
+  it('draws the elevated box, and drops it on request', () => {
+    const withBox = render(<Toolbar aria-label="Formatting"><ToolbarButton aria-label="One">{dot}</ToolbarButton></Toolbar>)
+    const panel = withBox.container.firstElementChild as HTMLElement
+    expect(panel.className).toContain('bg-bg-elevated')
+    expect(panel.querySelector('[role="toolbar"]')).toBeTruthy()
+    // The strip stays a row inside a panel that is a column for a menu's rows.
+    expect(panel.querySelector('[role="toolbar"]')!.className).not.toContain('flex-col')
+    withBox.unmount()
+
+    const bare = render(<Toolbar aria-label="Formatting" surface={false}><ToolbarButton aria-label="One">{dot}</ToolbarButton></Toolbar>)
+    expect((bare.container.firstElementChild as HTMLElement).getAttribute('role')).toBe('toolbar')
+  })
+
+  it('a separator is a separator, not just a hairline', () => {
+    render(
+      <Toolbar aria-label="Formatting">
+        <ToolbarButton aria-label="One">{dot}</ToolbarButton>
+        <ToolbarSeparator />
+        <ToolbarButton aria-label="Two">{dot}</ToolbarButton>
+      </Toolbar>,
+    )
+    expect(screen.getByRole('separator')).toBeTruthy()
+  })
+
+  /** While a field has focus the arrow keys are the caret's, which is what a
+   *  field is for; Tab resumes the walk. */
+  it('a field in the strip keeps the arrow keys for its caret', async () => {
+    const user = userEvent.setup()
+    render(
+      <Toolbar aria-label="Link">
+        <ToolbarButton aria-label="One">{dot}</ToolbarButton>
+        <ToolbarInput aria-label="Link address" defaultValue="abc" />
+      </Toolbar>,
+    )
+    const field = screen.getByRole('textbox', { name: 'Link address' }) as HTMLInputElement
+    field.focus()
+    field.setSelectionRange(3, 3)
+    await user.keyboard('{ArrowLeft}')
+    expect(document.activeElement).toBe(field)
+    expect(field.selectionStart).toBe(2)
+  })
+})
+
+describe('a loose row, for comparison', () => {
+  /** The measurement the component exists to change: the same three buttons
+   *  outside a toolbar are three Tab stops. */
+  it('is one Tab stop per button', async () => {
+    const user = userEvent.setup()
+    render(
+      <>
+        <button type="button">Before</button>
+        <div className="flex">
+          <IconButton aria-label="One">{dot}</IconButton>
+          <IconButton aria-label="Two">{dot}</IconButton>
+          <IconButton aria-label="Three">{dot}</IconButton>
+        </div>
+        <button type="button">After</button>
+      </>,
+    )
+    screen.getByRole('button', { name: 'Before' }).focus()
+    const walk: (string | null | undefined)[] = []
+    for (let i = 0; i < 4; i++) { await user.tab(); walk.push(focused()) }
+    expect(walk).toEqual(['One', 'Two', 'Three', 'After'])
+  })
+})
+
+describe('a ToolbarButton with a reason, as a trigger', () => {
+  /*
+    Found by Ship's adoption (2026-09-08, Finding 39): the message's tools put
+    "React" (a Popover trigger) and "…" (a Menu trigger) on one strip, and with
+    a `disabledReason` both came out `aria-disabled="false"`. The part that
+    renders the trigger writes its own disabled state over the button's.
+  */
+  it('stays disabled, reachable, and closed as a Popover trigger', async () => {
+    const user = userEvent.setup()
+    render(
+      <Toolbar aria-label="Tools">
+        <Popover
+          ariaLabel="Reactions"
+          trigger={
+            <ToolbarButton aria-label="React" disabledReason="Sign in to react.">
+              {dot}
+            </ToolbarButton>
+          }
+        >
+          <p>the picker</p>
+        </Popover>
+      </Toolbar>,
+    )
+    const button = screen.getByRole('button', { name: 'React' })
+    expect(button.getAttribute('aria-disabled')).toBe('true')
+    expect(button.getAttribute('tabindex')).toBe('0')
+    await user.click(button)
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  it('stays disabled, reachable, and closed as a Menu trigger', async () => {
+    const user = userEvent.setup()
+    render(
+      <Toolbar aria-label="Tools">
+        <Menu
+          trigger={
+            <ToolbarButton aria-label="More" disabledReason="Sign in first.">
+              {dot}
+            </ToolbarButton>
+          }
+        >
+          <MenuItem label="Delete" onClick={() => {}} />
+        </Menu>
+      </Toolbar>,
+    )
+    const button = screen.getByRole('button', { name: 'More' })
+    expect(button.getAttribute('aria-disabled')).toBe('true')
+    expect(button.getAttribute('tabindex')).toBe('0')
+    await user.click(button)
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+})

package/src/Toolbar.tsx

@@ -0,0 +1,158 @@
+import type { ReactNode, Ref } from 'react'
+import { Toolbar as BaseToolbar } from '@base-ui/react/toolbar'
+import { cn } from './cn'
+import { IconButton, type IconButtonProps } from './IconButton'
+import { MenuPanel } from './Menu'
+import { TextInput, type TextInputProps } from './TextInput'
+
+/**
+ * A strip of controls that behaves as **one** control.
+ *
+ * New at Katerina's request, 2026-09-08, pulled forward from stage 6.
+ *
+ * **It exists because every strip in the suite is as many Tab stops as it has
+ * buttons.** Ship's reaction row, Peek's composer strip and the editor's
+ * formatting strip are each a hand-rolled `<div class="flex">` of
+ * `IconButton`s: eight buttons, eight stops, and no way to get past them but
+ * through them. A toolbar is one stop — Tab in, arrow keys along, Tab out —
+ * which is what the `toolbar` role means and what Base UI's part implements.
+ *
+ * What it is not: a `Menu` (that is a list of *verbs* you open and choose
+ * from, and it closes when you do) or a row of unrelated buttons (a form's
+ * Cancel and Save are two separate answers, and each deserves its own stop).
+ * A toolbar is a set of things you do *to* something that is still there.
+ *
+ * **It draws the box.** A toolbar floats over what it acts on — a card, a
+ * paragraph, an image — so it carries the elevated surface that separates it
+ * from that: the same `MenuPanel` a `Menu` draws, because a floating strip and
+ * a floating list are the same box. Peek had built this twice and the two had
+ * already drifted — `ConversationQuickMenu` is `rounded-sm` with `shadow-sm`
+ * and a subtle border, `ReactionPicker` `rounded-lg` with `shadow-lg` and a
+ * default one. There is one box now. `surface={false}` for a strip inside
+ * something that already draws it.
+ *
+ * **The gap, stated: Home and End do nothing.** Base UI's composite has them
+ * and its `Toolbar` does not switch them on (`enableHomeAndEndKeys`, read in
+ * `useCompositeRoot`, not passed by `ToolbarRoot`) — so this page does not
+ * claim them. The arrow keys wrap, which reaches both ends in one press of a
+ * strip this size.
+ */
+export interface ToolbarProps {
+  /**
+   * Names the strip for assistive tech — "Formatting", "Reactions". A toolbar
+   * is a landmark-ish grouping and is announced as a bare "toolbar" without
+   * one, which says nothing when a page has two.
+   */
+  'aria-label': string
+  /** `horizontal` walks with ← →, `vertical` with ↑ ↓. Default horizontal. */
+  orientation?: 'horizontal' | 'vertical'
+  /** Whether the arrow keys wrap at the ends. Default true, as Base UI's. */
+  loopFocus?: boolean
+  /**
+   * The elevated box around the strip. **On by default** — a toolbar floats,
+   * and this is what floating looks like here.
+   *
+   * Off for a strip inside a surface that already draws one: a `Popover`, a
+   * dialog, a card's own panel. Two boxes inside each other is the tell.
+   */
+  surface?: boolean
+  children: ReactNode
+  /** The row's own layout — its gap, its padding, its wrapping. */
+  className?: string
+}
+
+export function Toolbar({ 'aria-label': ariaLabel, orientation = 'horizontal', loopFocus = true, surface = true, children, className }: ToolbarProps) {
+  const strip = (
+    <BaseToolbar.Root
+      aria-label={ariaLabel}
+      orientation={orientation}
+      loopFocus={loopFocus}
+      className={cn('flex items-center gap-1', orientation === 'vertical' && 'flex-col', className)}
+    >
+      {children}
+    </BaseToolbar.Root>
+  )
+  if (!surface) return strip
+  /*
+    The box WRAPS the strip rather than being composed onto it. `MenuPanel` is
+    a flex COLUMN — right for a menu's rows, wrong for a row of controls — and
+    Tailwind emits `flex-col` after `flex-row`, so a merged class list would
+    stand the toolbar on its end whatever order the classes arrived in. One
+    extra element, and the box keeps its single definition.
+
+    `p-1` is the tighter of Peek's two paddings and the right one for a strip
+    of 24px controls; `MenuPanel`'s own `p-2` is a menu's, where the rows run
+    the full width.
+  */
+  return <MenuPanel className="w-fit p-1">{strip}</MenuPanel>
+}
+
+/**
+ * One control in the strip. It is this package's `IconButton` — the same
+ * square, the same variants, the same `tooltip` and `disabledReason` — joined
+ * to the toolbar's roving focus.
+ *
+ * A disabled button **keeps its place in the walk**: a strip whose controls
+ * come and go from the arrow keys as their state changes is a strip you cannot
+ * learn. It is also what lets a `disabledReason` be read.
+ *
+ * **It must be inside a `Toolbar`.** Base UI throws otherwise —
+ * "ToolbarRootContext is missing" — because a part with no strip has no walk
+ * to join. A control beside a strip is an `IconButton`.
+ */
+export interface ToolbarButtonProps extends IconButtonProps {
+  ref?: Ref<HTMLButtonElement>
+}
+
+export function ToolbarButton({ ref, disabled, disabledReason, ...props }: ToolbarButtonProps) {
+  return (
+    <BaseToolbar.Button
+      ref={ref}
+      /*
+        The part has to be told, not only the button inside it. The toolbar
+        keeps its own map of which items are disabled — it is what decides
+        where an arrow key lands — and a `Toolbar.Button` that renders a
+        disabled `IconButton` without saying so leaves the two disagreeing:
+        measured, the element came out `aria-disabled="false"` over a button
+        that was disabled.
+      */
+      disabled={disabled || !!disabledReason}
+      /* Keep it in the walk either way. A strip whose controls come and go
+         from the arrow keys as their state changes is a strip you cannot
+         learn, and a `disabledReason` you cannot reach is a reason nobody
+         reads. */
+      focusableWhenDisabled
+      render={<IconButton disabled={disabled} disabledReason={disabledReason} {...props} />}
+    />
+  )
+}
+
+/**
+ * A text field inside the strip — the link editor in a selection toolbar.
+ *
+ * The arrow keys belong to the field while it has focus, which is the whole
+ * point: ← and → move the caret. The toolbar's walk resumes at Tab. That is
+ * Base UI's `Toolbar.Input`, and it is why a field in a toolbar cannot just be
+ * a `TextInput` dropped in the row.
+ */
+export type ToolbarInputProps = TextInputProps
+
+export function ToolbarInput(props: ToolbarInputProps) {
+  return <BaseToolbar.Input render={<TextInput />} {...props} />
+}
+
+/**
+ * The hairline between two groups of controls. It is `Divider`'s rule and
+ * `Toolbar.Separator`'s role, so a screen reader hears the grouping a sighted
+ * reader sees.
+ */
+export function ToolbarSeparator({ className }: { className?: string }) {
+  return (
+    <BaseToolbar.Separator
+      orientation="vertical"
+      /* `shrink-0` on a hairline in a flex row, always: without it a 1px rule
+         renders at 0px and nobody notices (the package's own trap table). */
+      className={cn('mx-1 h-4 w-px shrink-0 bg-border-default', className)}
+    />
+  )
+}

package/src/Tooltip.mdx

@@ -6,8 +6,7 @@ import * as TooltipStories from './Tooltip.stories'
 # Tooltip
 
 A 30px elevated pill with a caption, and **WithTooltip**, the wrapper that
-shows it above or below a trigger on hover — portalled, fixed to the
-viewport, kept 8px inside its edges.
+shows it beside a trigger — on hover, and on keyboard focus.
 
 <Canvas of={TooltipStories.OnHoverTop} />
 
@@ -32,7 +31,7 @@ viewport, kept 8px inside its edges.
 - Anything the person must read to proceed → put it in the surface, not
   behind a hover.
 - Anything interactive inside → **Menu** or **DialogShell**; a tooltip is
-  `pointer-events: none` by design.
+  `pointer-events: none` by design and cannot be pointed at.
 
 ## How
 
@@ -48,13 +47,52 @@ import { WithTooltip } from '@estiva-app/ui'
   shrinks nothing, so a wrapped block collapses to its content width.
 - A truncating label keeps truncating if you pass
   `wrapperClassName="min-w-0 shrink"`.
-- It shows on **hover only** — there is no focus or touch trigger. Don't
-  put anything behind it that a keyboard user must reach.
+- **`Button` and `IconButton` need no wrapper**: pass `tooltip` (or
+  `disabledReason`) and the button itself becomes the trigger. That is what
+  lets a `Dialog.Close` or a `Menu.Trigger` be one of them — the component's
+  root is the `<button>`, with nothing in between.
 - `shortcut` renders, it does not format. A modifier is called Cmd on Apple
   platforms and Ctrl elsewhere, and only the caller knows which it is
   looking at — so pass the finished label. `IconButton` forwards its own
   `tooltipShortcut` here.
 
+### The delay, and why a toolbar only pauses once
+
+A tooltip waits **300ms** before it opens. Mount **one `TooltipProvider` at
+the top of the app** and every tooltip below it shares that delay: the first
+waits, and while the group stays warm the neighbours open as the pointer
+arrives — so reading along a row of icon buttons is one pause, not one per
+button. Without the provider nothing breaks; each simply waits its own 300ms.
+
+```tsx
+import { TooltipProvider } from '@estiva-app/ui'
+
+<TooltipProvider>
+  <App />
+</TooltipProvider>
+```
+
+<Canvas of={TooltipStories.InAToolbar} />
+
+### The motion
+
+It fades in over **120ms** and travels **4px** away from the trigger — up
+from below when it stands above a control, down from above when it hangs
+beneath one — and fades out over **80ms**. Moving between triggers inside a
+warm group skips the animation entirely, so a toolbar sweep does not flicker.
+`prefers-reduced-motion` removes it.
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| pointer rests on the trigger | opens after 300ms — instantly if a neighbour's tooltip was just up |
+| pointer leaves | closes |
+| Tab onto the control | opens, with no delay |
+| Tab away | closes |
+| Escape while it is up | closes |
+| a click on the trigger | closes it — the tooltip has said its piece |
+
 ## Props
 
 <Controls of={TooltipStories.Default} />

package/src/Tooltip.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconArchive, IconPin, IconTrash } from '@tabler/icons-react'
 import { Button } from './Button'
+import { IconButton } from './IconButton'
 import { Tooltip, WithTooltip } from './Tooltip'
 
 const meta = {
@@ -60,3 +62,27 @@ export const OnADisabledControl: Story = {
     </WithTooltip>
   ),
 }
+
+
+/**
+ * A row of controls, which is where the shared delay shows itself: the first
+ * tooltip waits 300ms, and while the group stays warm the neighbours open as
+ * the pointer arrives — and the pill moves between them without re-animating.
+ * An app gets this by mounting one `TooltipProvider` at its root.
+ */
+export const InAToolbar: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-1 rounded-lg border border-border-default bg-bg-elevated p-1">
+      <IconButton aria-label="Pin" tooltip="Pin">
+        <IconPin size={16} stroke={1.5} />
+      </IconButton>
+      <IconButton aria-label="Archive" tooltip="Archive">
+        <IconArchive size={16} stroke={1.5} />
+      </IconButton>
+      <IconButton aria-label="Delete" tooltip="Delete" tooltipShortcut="Del">
+        <IconTrash size={16} stroke={1.5} />
+      </IconButton>
+    </div>
+  ),
+}