@estiva-app/ui 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/Avatar.mdx

@@ -42,6 +42,23 @@ import { Avatar } from '@estiva-app/ui'
   rounder geometry wraps the Avatar concentrically — it does not override
   the Avatar's own radius.
 
+### What it says out loud
+
+**A face is silent by default**, and that is the important half: almost every
+face in the suite sits beside the name it belongs to — in a `Person`, in a
+`MenuItem`'s `leading`, in a row — and a picture that spoke there would say the
+name twice. It used to. Measured 2026-09-08, before this was true: a `Person`
+inside a button announced **"AD Ana Duarte"** (the initials read as text), and
+with a picture **"Ana Duarte Ana Duarte"**.
+
+**`label` names a face that stands on its own** — the compact `PersonTrigger`,
+a stack of members — and the tile becomes one image with one name.
+
+```tsx
+<Avatar name={person.name} />                     {/* beside a name: silent */}
+<Avatar name={person.name} label={person.name} /> {/* alone: says who it is */}
+```
+
 <Canvas of={AvatarStories.Palette} />
 
 ## Props

package/src/Avatar.name.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+/**
+ * What a face is called, everywhere one appears.
+ *
+ * These are the names an app's own tests compute — `getByRole('button', { name })`
+ * runs the same algorithm — and every one of them was wrong until 2026-09-08:
+ * a face read as its initials, and a face beside a name read the name twice.
+ * The initials are a drawing of a name, not text.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { Avatar } from './Avatar'
+import { AvatarGroup } from './AvatarGroup'
+import { MenuItem, MenuPanel } from './Menu'
+import { Person } from './Person'
+import { PersonTrigger } from './PersonTrigger'
+
+afterEach(cleanup)
+
+/**
+ * `getByRole`'s `name` matches the *accessible* name exactly, computed by the
+ * same algorithm a browser uses — so a query that finds nothing is the failure
+ * being asserted, and the message names what it looked for. This is also how
+ * both apps query their own controls, which is what makes it the right test.
+ */
+
+describe('a face beside a name says nothing of its own', () => {
+  it('a button holding a Person is called the person, once', () => {
+    render(
+      <button type="button">
+        <Person name="Ana Duarte" />
+      </button>,
+    )
+    // "AD Ana Duarte" before: the initials were read as text.
+    expect(screen.getByRole('button', { name: 'Ana Duarte' })).toBeTruthy()
+  })
+
+  it('and once when there is a picture rather than initials', () => {
+    render(
+      <button type="button">
+        <Person name="Ana Duarte" picture="/a.png" />
+      </button>,
+    )
+    // "Ana Duarte Ana Duarte" before: the alt text and the name were both read.
+    expect(screen.getByRole('button', { name: 'Ana Duarte' })).toBeTruthy()
+  })
+
+  it('a menu row led by a face is called by its label', () => {
+    render(
+      <MenuPanel>
+        <MenuItem label="Ana Duarte" leading={<Avatar name="Ana Duarte" size={32} />} onClick={() => {}} />
+      </MenuPanel>,
+    )
+    expect(screen.getByRole('button', { name: 'Ana Duarte' })).toBeTruthy()
+  })
+
+  it('a bare face is not in the accessibility tree at all', () => {
+    const { container } = render(<Avatar name="Ana Duarte" />)
+    expect(container.firstElementChild?.getAttribute('aria-hidden')).toBe('true')
+  })
+})
+
+describe('a face that stands on its own says whose it is', () => {
+  it('the compact PersonTrigger is called the person', () => {
+    render(<PersonTrigger name="Ana Duarte" compact />)
+    // "AD" before — the initials, and the only name the control had.
+    expect(screen.getByRole('button', { name: 'Ana Duarte' })).toBeTruthy()
+  })
+
+  it('a caller may name the destination instead', () => {
+    render(<PersonTrigger name="Ana Duarte" compact aria-label="Account menu" />)
+    expect(screen.getByRole('button', { name: 'Account menu' })).toBeTruthy()
+  })
+
+  it('an unnamed person falls back to what the caller calls them', () => {
+    render(<PersonTrigger fallback="Anonymous" compact />)
+    expect(screen.getByRole('button', { name: 'Anonymous' })).toBeTruthy()
+  })
+
+  it('the row shape is called the person, without the initials in front', () => {
+    render(<PersonTrigger name="Ana Duarte" />)
+    expect(screen.getByRole('button', { name: 'Ana Duarte' })).toBeTruthy()
+  })
+
+  it('a stack of faces names each of them', () => {
+    render(<AvatarGroup members={[{ name: 'Ana Duarte' }, { name: 'Ben Carter' }]} />)
+    // "AD" and "BC" before.
+    expect(screen.getAllByRole('img').map((el) => el.getAttribute('aria-label'))).toEqual(['Ana Duarte', 'Ben Carter'])
+  })
+})
+
+describe('the compact trigger keeps a focus ring', () => {
+  /** `focus:outline-none` took the browser's ring away and put nothing back,
+   *  so the account trigger had no visible focus at all. */
+  it('does not remove its own outline', () => {
+    render(<PersonTrigger name="Ana Duarte" compact />)
+    expect(screen.getByRole('button').className).not.toContain('outline-none')
+  })
+})

package/src/Avatar.tsx

@@ -52,17 +52,36 @@ export interface AvatarProps {
   alt?: string
   /** Pixels. The scale: 16 · 24 · 32 · 36 (default). */
   size?: number
+  /**
+   * **Say the person's name out loud**, for a face that stands on its own —
+   * `PersonTrigger`'s compact shape, a stack of members.
+   *
+   * A face is silent by default, because almost every face in the suite sits
+   * beside the name it belongs to: `Person`, a `MenuItem`'s `leading`, a row.
+   * A picture that spoke there would double the name — measured 2026-09-08,
+   * before this existed: a `Person` in a button announced **"AD Ana Duarte"**,
+   * and with a picture **"Ana Duarte Ana Duarte"**. The initials are a drawing
+   * of a name, not text, and a screen reader was reading them as text.
+   */
+  label?: string
   className?: string
 }
 
-export function Avatar({ src, name, alt = '', size = 36, className }: AvatarProps) {
+export function Avatar({ src, name, alt = '', size = 36, label: spoken, className }: AvatarProps) {
   const [broken, setBroken] = useState(false)
   const label = name || alt
   const picture = src && !broken ? src : undefined
   return (
-    <div className={cn('rounded-sm overflow-hidden shrink-0 bg-bg-inset', className)} style={{ width: size, height: size }}>
+    <div
+      /* Named or silent, never half of either: with a `label` the tile is one
+         image with one name, and everything inside it is that image's pixels;
+         without one it is not in the accessibility tree at all. */
+      {...(spoken ? { role: 'img', 'aria-label': spoken } : { 'aria-hidden': true })}
+      className={cn('rounded-sm overflow-hidden shrink-0 bg-bg-inset', className)}
+      style={{ width: size, height: size }}
+    >
       {picture ? (
-        <img src={picture} alt={alt || name || ''} className="w-full h-full object-cover" onError={() => setBroken(true)} />
+        <img src={picture} alt="" className="w-full h-full object-cover" onError={() => setBroken(true)} />
       ) : label ? (
         <div
           /*
@@ -80,6 +99,9 @@ export function Avatar({ src, name, alt = '', size = 36, className }: AvatarProp
           */
           className="w-full h-full flex items-center justify-center font-semibold leading-none"
           style={{
+            // The one ink colour that reads on all eight hues, which are a
+            // palette rather than tokens (see the note at the top) — so its
+            // ink cannot be a token either.
             color: '#08121c',
             fontSize: Math.round(size * 0.36),
             background: `linear-gradient(160deg, color-mix(in srgb, ${hueFor(label)} 92%, #fff) 0%, color-mix(in srgb, ${hueFor(label)} 70%, #0b0d11) 100%)`,

package/src/AvatarGroup.tsx

@@ -57,7 +57,10 @@ export function AvatarGroup({ members, size = 24 }: AvatarGroupProps) {
           className="relative flex rounded-sm"
           style={{ marginRight: -overlap, boxShadow: `0 0 0 ${ring}px var(--bg-surface)` }}
         >
-          <Avatar size={size} name={member.name} src={member.picture} alt={member.name} />
+          {/* Each face says whose it is: a stack stands on its own, with no
+              name beside it to borrow. It read as its initials before —
+              "AD BC CD" — which is the drawing, not the person. */}
+          <Avatar size={size} name={member.name} src={member.picture} label={member.name} />
         </span>
       ))}
     </div>

package/src/Banner.mdx

@@ -23,6 +23,10 @@ line, one of four tones, gone when there is nothing to say.
 ## When not
 
 - Feedback about one action, briefly → **Toast**.
+- Something that floats over the page and must **not** fade → still
+  **Toast**, with `durationMs: 0` and an action. A banner is the strip
+  under the header at the app's full width; a floating pill is not one, even
+  a permanent one (Katerina, D21).
 - A standing property of one thing → **Chip** on that thing.
 - A notice inside the content flow with its own action — that is a
   different component (not in the package yet).
@@ -37,8 +41,12 @@ import { Banner } from '@estiva-app/ui'
 
 - Render it only while there is something to say — an empty strip is not
   a state.
-- One line of plain text, `body-2`. If it needs a button or a second
-  line, it has outgrown this component.
+- One line of plain text, `body-2`. If it needs a **second line or an
+  action of its own**, it has outgrown this component.
+- `onDismiss` adds an ✕ at the right-hand end (Katerina, D21). Use it where
+  the reader decides the notice is done with, rather than the app. The row
+  is 40px rather than 36px with it, because the button is taller than the
+  line of text; without it, nothing about the strip changes.
 
 ## Props
 

package/src/Banner.stories.tsx

@@ -26,6 +26,14 @@ export const Info: Story = { args: { tone: 'info', children: 'A new version is a
 
 export const Warning: Story = { args: { tone: 'warning', children: 'This workspace is read-only until sign-in.' } }
 
+/**
+ * With a dismiss (D21). The row is 40px rather than 36px, because the button
+ * is taller than the line of text.
+ */
+export const Dismissible: Story = {
+  args: { tone: 'warning', children: 'This workspace is read-only until sign-in.', onDismiss: () => {} },
+}
+
 /** All four tones, stacked. */
 export const AllTones: Story = {
   parameters: { controls: { disable: true } },
@@ -38,3 +46,24 @@ export const AllTones: Story = {
     </div>
   ),
 }
+
+/** The same four with a dismiss, so the two heights can be compared. */
+export const AllTonesDismissible: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Banner tone="ok" onDismiss={() => {}}>
+        Public key copied.
+      </Banner>
+      <Banner tone="info" onDismiss={() => {}}>
+        A new version is available. Reload when convenient.
+      </Banner>
+      <Banner tone="warning" onDismiss={() => {}}>
+        This workspace is read-only until sign-in.
+      </Banner>
+      <Banner tone="error" onDismiss={() => {}}>
+        The last read failed — reconnecting.
+      </Banner>
+    </div>
+  ),
+}

package/src/Banner.test.tsx

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+/**
+ * What `Banner.mdx` claims about the dismiss added at stage 3 (D21).
+ *
+ * The point of the first test is the one that is easy to lose: a banner
+ * without `onDismiss` must render exactly what it always did. Every banner in
+ * both apps is that one, and a prop that quietly changed their DOM would be a
+ * change nobody asked for.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Banner } from './Banner'
+
+afterEach(cleanup)
+
+describe('Banner', () => {
+  it('is one element with the text in it when there is no dismiss', () => {
+    const { container } = render(<Banner tone="info">Two people are editing this.</Banner>)
+    const root = container.firstElementChild!
+    expect(root.children).toHaveLength(0)
+    expect(root.textContent).toBe('Two people are editing this.')
+    expect(screen.queryByRole('button')).toBeNull()
+  })
+
+  it('offers a dismiss when asked, and reports it', async () => {
+    const onDismiss = vi.fn()
+    const user = userEvent.setup()
+    render(
+      <Banner tone="warning" onDismiss={onDismiss}>
+        The relay is not answering.
+      </Banner>,
+    )
+    await user.click(screen.getByRole('button', { name: 'Dismiss' }))
+    expect(onDismiss).toHaveBeenCalledTimes(1)
+  })
+
+  it('lets the caller name the dismiss', () => {
+    render(
+      <Banner tone="ok" onDismiss={() => {}} dismissLabel="Hide this notice">
+        Saved.
+      </Banner>,
+    )
+    expect(screen.getByRole('button', { name: 'Hide this notice' })).toBeTruthy()
+  })
+
+  it('announces an error and stays polite otherwise', () => {
+    const { rerender, container } = render(<Banner tone="error">Could not save.</Banner>)
+    expect(container.firstElementChild!.getAttribute('role')).toBe('alert')
+    rerender(<Banner tone="warning">Could not save.</Banner>)
+    expect(container.firstElementChild!.getAttribute('role')).toBe('status')
+    // and the same either side of the dismiss
+    rerender(
+      <Banner tone="error" onDismiss={() => {}}>
+        Could not save.
+      </Banner>,
+    )
+    expect(container.firstElementChild!.getAttribute('role')).toBe('alert')
+  })
+})

package/src/Banner.tsx

@@ -1,4 +1,6 @@
+import { IconX } from '@tabler/icons-react'
 import { cn } from './cn'
+import { IconButton } from './IconButton'
 
 /**
  * The strip under the header where the app says something happened —
@@ -10,12 +12,27 @@ import { cn } from './cn'
  * rendered, so 14px is what it has always been and what she kept.
  * An `error` announces itself (`role="alert"`); the other tones are
  * polite (`role="status"`).
+ *
+ * `onDismiss` adds an `✕` at the right-hand end (Katerina, D21,
+ * 2026-09-07). Without it the strip is exactly what it was — a banner an
+ * app removes by not rendering it. With it the row is 40px rather than
+ * 36px, because the button is taller than the line of text.
+ *
+ * **A banner is not a toast.** This is the strip under the header, at the
+ * app's full width, for something that stays true. Transient feedback is
+ * `Toast`, and something that floats over the page and must not fade is a
+ * `Toast` with `durationMs: 0` — which is what Peek's "topic deleted"
+ * notice is (D21), not this.
  */
 export type BannerTone = 'ok' | 'error' | 'info' | 'warning'
 
 export interface BannerProps {
   tone: BannerTone
   children: string
+  /** Adds an `✕` at the right-hand end. Absent: the app removes the banner. */
+  onDismiss?: () => void
+  /** The dismiss button's accessible name. Defaults to "Dismiss". */
+  dismissLabel?: string
   className?: string
 }
 
@@ -26,10 +43,25 @@ const TONE_STYLES: Record<BannerTone, string> = {
   warning: 'bg-warning-muted text-warning-default',
 }
 
-export function Banner({ tone, children, className }: BannerProps) {
+export function Banner({ tone, children, onDismiss, dismissLabel = 'Dismiss', className }: BannerProps) {
+  const role = tone === 'error' ? 'alert' : 'status'
+  // No dismiss, no row: every banner that predates the prop keeps the DOM and
+  // the height it had.
+  if (!onDismiss) {
+    return (
+      <div role={role} className={cn('px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
+        {children}
+      </div>
+    )
+  }
   return (
-    <div role={tone === 'error' ? 'alert' : 'status'} className={cn('px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
-      {children}
+    <div role={role} className={cn('flex items-center gap-3 px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
+      <span className="min-w-0 flex-1">{children}</span>
+      {/* `text-current` so the ✕ takes the tone's colour rather than the
+          muted grey an IconButton wears on a neutral surface. */}
+      <IconButton aria-label={dismissLabel} onClick={onDismiss} className="-mr-1 shrink-0 text-current hover:text-current">
+        <IconX size={16} stroke={1.5} />
+      </IconButton>
     </div>
   )
 }

package/src/Breadcrumb.mdx

@@ -35,13 +35,16 @@ import { Breadcrumb } from '@estiva-app/ui'
 
 <Breadcrumb
   items={[
-    { label: 'Documents', href: '#/documents' },
-    { label: 'Quarterly plan', href: '#/documents/12' },
+    { label: 'Documents', href: '/documents' },
+    { label: 'Quarterly plan', href: '/documents/12' },
     { label: 'DOC-12', mono: true },
   ]}
 />
 ```
 
+- A crumb is a plain anchor. In a router app pass `onClick` per crumb and
+  navigate in place there — NavItem's rule — and keep the `href` a real
+  address, so the link can still be copied or opened in a new tab.
 - Truncation is re-measured as the trail resizes; the tooltip appears and
   disappears with the room the trail actually has. Give the trail a
   `min-w-0` container so it can truncate at all.

package/src/Breadcrumb.test.tsx

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+/**
+ * What the Breadcrumb page claims, pinned: a crumb with an href is a link
+ * (even the last one), the last crumb without one is where you are, the
+ * separators are never read aloud — and a router app can take the click,
+ * which is the one prop the trail lacked (ADOPTION S15, 2026-09-08).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Breadcrumb } from './Breadcrumb'
+
+afterEach(cleanup)
+
+describe('Breadcrumb', () => {
+  it('a crumb with an href is a link, and the last one without is where you are', () => {
+    render(<Breadcrumb items={[{ label: 'Documents', href: '/documents' }, { label: 'DOC-12', mono: true }]} />)
+    expect(screen.getByRole('link', { name: 'Documents' }).getAttribute('href')).toBe('/documents')
+    const here = screen.getByText('DOC-12')
+    expect(here.tagName).toBe('SPAN')
+    expect(here.getAttribute('aria-current')).toBe('page')
+  })
+
+  it('a last crumb with an href is still a link — a page may end its trail on somewhere to go', () => {
+    render(<Breadcrumb items={[{ label: 'Documents', href: '/documents' }, { label: 'Quarterly plan', href: '/documents/12' }]} />)
+    const last = screen.getByRole('link', { name: 'Quarterly plan' })
+    expect(last.getAttribute('href')).toBe('/documents/12')
+    expect(last.getAttribute('aria-current')).toBeNull()
+  })
+
+  it('a router app takes the click through onClick, and the href stays a real address', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(<Breadcrumb items={[{ label: 'Documents', href: '/documents', onClick }, { label: 'DOC-12' }]} />)
+    await userEvent.click(screen.getByRole('link', { name: 'Documents' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(screen.getByRole('link', { name: 'Documents' }).getAttribute('href')).toBe('/documents')
+  })
+
+  it('the separators are drawn but never read aloud', () => {
+    render(<Breadcrumb items={[{ label: 'Documents', href: '/documents' }, { label: 'DOC-12' }]} />)
+    expect(screen.getByRole('navigation', { name: 'Breadcrumb' }).textContent).toContain('/')
+    expect(screen.queryByText('/', { ignore: '[aria-hidden="true"]' })).toBeNull()
+  })
+})

package/src/Breadcrumb.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useCallback, useLayoutEffect, useRef, useState } from 'react'
+import { Fragment, useCallback, useLayoutEffect, useRef, useState, type MouseEventHandler } from 'react'
 import { cn } from './cn'
 import { WithTooltip } from './Tooltip'
 
@@ -15,10 +15,18 @@ import { WithTooltip } from './Tooltip'
  * (Katerina, 2026-09-01); one that fits shows nothing extra. Truncation is
  * re-measured when the trail resizes, so the tooltip appears and disappears
  * with the room the trail actually has.
+ *
+ * A crumb with an `href` is a plain anchor, so in a router app a click on it
+ * reloads the page. Such an app passes `onClick` per crumb and navigates in
+ * place there — NavItem's rule — and the `href` stays a real address so the
+ * link can still be copied or opened in a new tab. Ship's breadcrumbs were
+ * the last links reloading the whole app (ADOPTION S15, 2026-09-08).
  */
 export interface Crumb {
   label: string
   href?: string
+  /** A router app intercepts the click here. Called only on a crumb with an `href`. */
+  onClick?: MouseEventHandler<HTMLAnchorElement>
   /** Set the item in the mono face — a ref, an id. */
   mono?: boolean
   /** Quieter — a label that is not a place. */
@@ -73,7 +81,7 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
           labelRefs.current[index] = el
         }
         const crumb = item.href ? (
-          <a ref={setLabelRef} href={item.href} className={cn(text, 'hover:text-text-primary')}>
+          <a ref={setLabelRef} href={item.href} onClick={item.onClick} className={cn(text, 'hover:text-text-primary')}>
             {item.label}
           </a>
         ) : (

package/src/Button.compose.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment jsdom
+/**
+ * The buttons carry a ref, and a Base UI part can therefore *be* one.
+ *
+ * `Button` and `IconButton` typed their props as `ButtonHTMLAttributes`, which
+ * has no `ref`. React 19 hands `ref` to a function component as an ordinary
+ * prop, so it was already riding in on the spread and reaching the element —
+ * the type was the only thing stopping a caller. These tests pin both halves:
+ * that the ref lands, and that composition through `render` works, which is
+ * the shape all of stage 4 is built from (`Menu.Trigger`, `Dialog.Close`).
+ */
+import { createRef } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Dialog } from '@base-ui/react/dialog'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { Button } from './Button'
+import { IconButton } from './IconButton'
+
+afterEach(cleanup)
+
+describe('the buttons take a ref', () => {
+  it('Button: the ref is the button element', () => {
+    const ref = createRef<HTMLButtonElement>()
+    render(<Button ref={ref}>Label</Button>)
+    expect(ref.current).toBe(screen.getByRole('button', { name: 'Label' }))
+    expect(ref.current?.tagName).toBe('BUTTON')
+  })
+
+  it('IconButton: the ref is the button element', () => {
+    const ref = createRef<HTMLButtonElement>()
+    render(
+      <IconButton ref={ref} aria-label="Item">
+        <IconSquareRounded size={16} stroke={1.5} />
+      </IconButton>,
+    )
+    expect(ref.current).toBe(screen.getByRole('button', { name: 'Item' }))
+  })
+})
+
+describe('a Base UI part can be one of our buttons', () => {
+  it('Dialog.Close renders as an IconButton and closes the dialog', async () => {
+    // This is the loose end stage 3 left: `DialogShell`'s ✕ called `onClose`
+    // by hand because `Close` as a render target needs exactly this.
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+    render(
+      <Dialog.Root open onOpenChange={onOpenChange}>
+        <Dialog.Portal>
+          <Dialog.Popup aria-label="A dialog">
+            <Dialog.Close
+              render={
+                <IconButton aria-label="Close">
+                  <IconSquareRounded size={16} stroke={1.5} />
+                </IconButton>
+              }
+            />
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>,
+    )
+    const close = screen.getByRole('button', { name: 'Close' })
+    // Still our button: the class list survives composition.
+    expect(close.className).toContain('rounded-lg')
+    await user.click(close)
+    expect(onOpenChange).toHaveBeenCalledTimes(1)
+    expect(onOpenChange.mock.calls[0][0]).toBe(false)
+    // Base UI says *why* it closed, which is what a hand-wired onClick cannot.
+    expect((onOpenChange.mock.calls[0][1] as { reason?: string })?.reason).toBe('close-press')
+  })
+
+  it('Dialog.Close renders as an IconButton THAT CARRIES A TOOLTIP', async () => {
+    /*
+     * The half stage 3 could not close. With the hand-written tooltip an
+     * IconButton with a `tooltip` returned `WithTooltip`'s wrapper `<div>` as
+     * its root, so `Close` composed onto the wrapper and the ✕ was never the
+     * part. On Base UI's Tooltip the trigger IS the button, so it is.
+     */
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+    render(
+      <Dialog.Root open onOpenChange={onOpenChange}>
+        <Dialog.Portal>
+          <Dialog.Popup aria-label="A dialog">
+            <Dialog.Close
+              render={
+                <IconButton aria-label="Close" tooltip="Close">
+                  <IconSquareRounded size={16} stroke={1.5} />
+                </IconButton>
+              }
+            />
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>,
+    )
+    const close = screen.getByRole('button', { name: 'Close' })
+    expect(close.tagName).toBe('BUTTON')
+    expect(close.className).toContain('rounded-lg')
+    await user.click(close)
+    expect(onOpenChange).toHaveBeenCalledTimes(1)
+    expect((onOpenChange.mock.calls[0][1] as { reason?: string })?.reason).toBe('close-press')
+  })
+  it('Dialog.Trigger renders as a Button and opens the dialog', async () => {
+    const user = userEvent.setup()
+    render(
+      <Dialog.Root>
+        <Dialog.Trigger render={<Button variant="primary">Open</Button>} />
+        <Dialog.Portal>
+          <Dialog.Popup aria-label="A dialog">Body</Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>,
+    )
+    const trigger = screen.getByRole('button', { name: 'Open' })
+    expect(trigger.className).toContain('bg-accent-primary')
+    await user.click(trigger)
+    expect(await screen.findByRole('dialog', { name: 'A dialog' })).toBeTruthy()
+  })
+})

package/src/Button.mdx

@@ -53,11 +53,13 @@ import { IconPlus } from '@tabler/icons-react'
   passes through; the visible label is the accessible name, so no
   `aria-label` is needed.
 - `disabledReason="Sign in first"` disables it, keeps it reachable by
-  Tab, and shows the reason as a tooltip on hover. Say why, every time;
-  a bare `disabled` is for the moment between a click and its answer. The
-  reason shows on hover only for now; it will also show on keyboard focus
-  when Tooltip moves onto Base UI (stage 4). With a reason the button sits
-  in the tooltip's `inline-flex` wrapper.
+  Tab, and shows the reason as a tooltip. Say why, every time; a bare
+  `disabled` is for the moment between a click and its answer. **The
+  reason shows on keyboard focus as well as on hover**, which is what
+  makes it worth writing: a reason only a mouse can read is not offered
+  to everyone. The button itself is the tooltip's trigger, so it wears no
+  wrapper — what a caller gets is the `<button>`, and a `Menu.Trigger` or
+  a `Dialog.Close` can be it.
 
 ## Keys
 

package/src/Button.test.tsx

@@ -72,7 +72,8 @@ describe('Button', () => {
     expect(button.hasAttribute('disabled')).toBe(false)
     expect(screen.queryByRole('tooltip')).toBeNull()
     await user.hover(button)
-    expect(screen.getByRole('tooltip').textContent).toBe('Sign in first')
+    // 300ms before it opens (D23) - it used to be instant.
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Sign in first')
     await user.unhover(button)
     expect(screen.queryByRole('tooltip')).toBeNull()
     await user.click(button)