@estiva-app/ui 0.23.0 → 0.24.0

package/src/EmptyState.mdx

@@ -36,10 +36,12 @@ need a height from the caller (`className="h-full"`).
 
 ## When not
 
-- Data is still on its way → **Skeleton**; empty and loading are
-  different truths.
-- Something went wrong → say that, in your surface's own error treatment
-  — an empty state that hides a failure misleads.
+- Data is still on its way → **Skeleton**; empty and loading are different
+  truths. When the shape of what arrives is unknown, an EmptyState that says so
+  — "Opening…" — is fine.
+- Something went wrong → say what failed, in words. An EmptyState can carry
+  it, in its usual look — never red. An empty state that hides a failure
+  misleads.
 
 ## How
 
@@ -83,6 +85,15 @@ The message is the caller's — a shared component has no words of its own
 for what is missing. A hand-written "Nothing here" paragraph or span in a
 section is the `section` manner, and becomes it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| As a `page`, fills the room it is given and centres itself in it | centring, or padding around it |  |
+| Draws its one action, an outlined Button, under the line when you pass `action` | a button of your own under the line |  |
+
 ## Props
 
 <Controls of={EmptyStateStories.Page} />

package/src/Field.mdx

@@ -19,7 +19,7 @@ token; `required` marks it with the error-coloured asterisk.
 
 - Displaying a label–value pair → **Property**; Field is for editing.
 - The line belongs to a **group** of controls rather than to one — a value
-  with Save beside it, a row of action controls → **Field line**, the same
+  with Save beside it, a row of action controls → **FieldLine**, the same
   small line on its own.
 
 ## How
@@ -55,6 +55,15 @@ import { Field, TextInput } from '@estiva-app/ui'
   that says so already is left alone, and a `children` of several elements
   keeps the asterisk and owes its own.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Ties the label, the description and the error to the control inside it | `aria-label`, an `id` / `htmlFor` pair, or `aria-describedby` |  |
+| Marks the control invalid when it has an `error`, and announces it | `aria-invalid` |  |
+
 ## Props
 
 <Controls of={FieldStories.Default} />

package/src/FieldLine.mdx

@@ -32,7 +32,7 @@ import { FieldLine } from '@estiva-app/ui'
 
 <div className="flex flex-col gap-1.5">
   <div className="flex items-center gap-2">
-    <TextInput value={draft} onChange={…} />
+    <TextInput value={draft} onChange={(e) => setDraft(e.target.value)} />
     <Button variant="primary" size="small">Save</Button>
   </div>
   {outcome && <FieldLine tone={outcome.kind}>{outcome.message}</FieldLine>}
@@ -52,6 +52,14 @@ import { FieldLine } from '@estiva-app/ui'
 - The three tones are the same two classes Field draws, from one map in
   `Field.tsx`, so they cannot drift.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: an alert for an error, a status for the rest | `role="alert"` or `role="status"` | ✓ |
+
 ## Props
 
 <Controls of={FieldLineStories.Helper} />

package/src/FilePicker.mdx

@@ -44,6 +44,14 @@ const picker = useRef<HTMLInputElement>(null)
   nothing to reset afterwards.
 - `data-*` attributes pass on to the input, for a test to find it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Opens the system's file picker from its button, and keeps the real file input out of Tab and screen readers | a hidden `<input type="file">` |  |
+
 ## Props
 
 <Controls of={FilePickerStories.Default} />

package/src/Form.mdx

@@ -58,6 +58,16 @@ import { Button, Field, Form, TextInput } from '@estiva-app/ui'
 - `className` places the fields: the form draws no box, and neither does the
   `<fieldset>` inside it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Sends on Enter in a one-line field, and on Ctrl+Enter anywhere inside | a key handler that submits |  |
+| Leaves Enter alone where it means something else: a Textarea, a list, a people picker | exceptions of your own |  |
+| Does nothing while it is sending: no second send, and nothing inside takes focus | a busy flag on every control |  |
+
 ## Keys
 
 The same in every form (Katerina, 16 September).

package/src/Form.test.tsx

@@ -18,6 +18,7 @@ import { Checkbox } from './Checkbox'
 import { IconButton } from './IconButton'
 import { Field } from './Field'
 import { Form } from './Form'
+import { Popover } from './Popover'
 import { TextInput } from './TextInput'
 import { Textarea } from './Textarea'
 
@@ -46,6 +47,31 @@ describe('Form', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 
+  it('a Form in a Popover inside a Form sends only itself (C1)', async () => {
+    // A link field in a pop-up over a composer: Enter there adds the link, and
+    // must not also send the message around it. React carries the submit
+    // through the Popover's portal to the outer form.
+    const user = userEvent.setup()
+    const outer = vi.fn()
+    const inner = vi.fn()
+    render(
+      <Form onSubmit={outer}>
+        <TextInput aria-label="Message" />
+        <Popover trigger={<Button>Link</Button>} open ariaLabel="Link">
+          <Form onSubmit={inner}>
+            <TextInput aria-label="Address" />
+          </Form>
+        </Popover>
+      </Form>,
+    )
+    await user.type(screen.getByRole('textbox', { name: 'Address' }), 'example.com{Enter}')
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+    await user.type(screen.getByRole('textbox', { name: 'Message' }), 'hi{Enter}')
+    expect(outer).toHaveBeenCalledTimes(1)
+    expect(inner).toHaveBeenCalledTimes(1)
+  })
+
   it('sends from its submit button', async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn()

package/src/Form.tsx

@@ -160,6 +160,13 @@ export function Form({ onSubmit, busy: ownBusy = false, enterSends = true, class
       }}
       onKeyDown={onKeyDown}
       onSubmit={(event) => {
+        /*
+          A form's own send only. React carries a submit up the component tree,
+          through a portal too, so a Form in a Popover inside this Form sent both:
+          Enter in a link field sent the whole message around it (UIG-14, C1,
+          Katerina 19 September). The inner Form has already handled its own.
+        */
+        if (event.target !== event.currentTarget) return
         event.preventDefault()
         if (busyNow.current) return
         void onSubmit()

package/src/IconButton.mdx

@@ -22,8 +22,8 @@ variants. For the actions a surface repeats too often to label every time.
 - The action deserves a visible label → **Button** (words are cheaper than
   a guessed icon).
 - Inside a menu → **MenuItem** with `leading`.
-- A strip of these is a toolbar — right; but the moment rows toggle and
-  persist state, see **Checkbox**.
+- A strip of these acting on one thing → **Toolbar**. The moment rows toggle
+  and persist state, see **Checkbox**.
 
 ## How
 
@@ -54,11 +54,25 @@ import { IconPencil } from '@tabler/icons-react'
 - `disabledReason="Read only"` disables it, keeps it reachable by Tab,
   and shows the reason in place of the tooltip — **on keyboard focus as
   well as on hover**.
+- **`href`** makes it a link that looks like the button: an anchor, so the
+  address stays real for a modified click or a new tab. A router app passes
+  `onClick`, prevents the default and navigates. While it cannot be used it
+  is the button — a link cannot be disabled.
 - `tooltip` costs no wrapper: the button is the tooltip's trigger, so
   this component's root is the `<button>` whether it carries one or not,
   and both sit at the same height. A `Dialog.Close` or a `Menu.Trigger`
   can be an IconButton that has a tooltip.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a button | `role="button"` | ✓ |
+| Is reachable with Tab, also when it is disabled with a reason | a `tabIndex` | ✓ |
+| Presses on Enter and Space, and does nothing while disabled | a key handler |  |
+
 ## Keys
 
 | Key | Does |

package/src/IconButton.stories.tsx

@@ -26,6 +26,9 @@ export const WithTooltip: Story = { args: { tooltip: 'Settings', tooltipPlacemen
 /** Disabled with its reason in place of the tooltip; Tab still reaches it. */
 export const WithAReason: Story = { args: { tooltip: 'Settings', disabledReason: 'Sign in to change settings' } }
 
+/** `href`: a link that looks like the button — the same box, an anchor underneath. */
+export const AsALink: Story = { args: { href: '#settings', tooltip: 'Settings' } }
+
 /** Every variant × enabled/disabled. */
 export const AllVariants: Story = {
   // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:

package/src/IconButton.test.tsx

@@ -28,6 +28,31 @@ describe('IconButton', () => {
     expect(onClick).toHaveBeenCalledTimes(1)
   })
 
+  it('href: a link that looks like the button, with its tooltip', async () => {
+    const user = userEvent.setup()
+    render(
+      <IconButton href="/documents/12" aria-label="Open" tooltip="Open">
+        {icon}
+      </IconButton>,
+    )
+    expect(screen.queryByRole('button')).toBeNull()
+    const link = screen.getByRole('link', { name: 'Open' })
+    expect(link.getAttribute('href')).toBe('/documents/12')
+    expect(link.className).toContain('rounded-lg')
+    await user.hover(link)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Open')
+  })
+
+  it('href while it cannot be used: the button, since a link cannot be disabled', () => {
+    render(
+      <IconButton href="/documents/12" aria-label="Open" disabledReason="Read only">
+        {icon}
+      </IconButton>,
+    )
+    expect(screen.queryByRole('link')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Open' }).getAttribute('aria-disabled')).toBe('true')
+  })
+
   it('shows the tooltip on hover, with its shortcut', async () => {
     const user = userEvent.setup()
     render(

package/src/IconButton.tsx

@@ -37,6 +37,14 @@ export interface IconButtonProps extends ComponentPropsWithRef<'button'> {
   /** Why the action cannot succeed right now. Disables the button, keeps it
    *  reachable by keyboard, and shows the reason as the tooltip. */
   disabledReason?: string
+  /**
+   * A link that looks like an icon button: an anchor, so the address stays
+   * real for a modified click or a new tab, as `Link` keeps it. A router app
+   * passes `onClick`, prevents the default and navigates. A link cannot be
+   * disabled, so while it would be — `disabled`, `disabledReason`, a busy
+   * Form — it is the button (UIG-14, Katerina, 18 September).
+   */
+  href?: string
   /** The icon: 16px, stroke 1.5. */
   children: ReactNode
 }
@@ -53,56 +61,63 @@ export function IconButton({
   tooltipShortcut,
   tooltipPlacement,
   type = 'button',
+  href,
   ...props
 }: IconButtonProps) {
   // Inside a busy Form: switched off, and looking it (formBusy.ts).
   const formBusy = useFormBusy()
-  const button = (
-    <BaseButton
-      type={type}
-      disabled={disabled || !!disabledReason || formBusy}
-      focusableWhenDisabled={!!disabledReason}
-      className={(state) =>
-        cn(
-          // `shrink-0` stops a flex parent squashing the button; `self-center`
-          // stops one stretching it. Two different failures, and both have
-          // happened here: a row with no `items-*` drew this 24 wide and 228
-          // tall in Peek's TopicMoreMenu story (Katerina, 2026-09-11). A button
-          // is the size of its icon and its padding, whatever box it lands in.
-          //
-          // This is the one of the two that needs it: an IconButton states no
-          // height, so its cross size is `auto` and a stretching parent takes
-          // it. Measured in the same 260px row on 2026-09-12: 24px with this
-          // class, 226px without. `Button` states `h-8`/`h-6`, so it cannot be
-          // stretched and carries no `self-center` — see the note there.
-          'flex items-center justify-center p-1 rounded-lg transition-colors shrink-0 self-center cursor-pointer',
-          !state.disabled && variant === 'primary' && 'bg-accent-primary hover:bg-accent-hover text-text-inverse',
-          !state.disabled && (variant === 'muted' || variant === 'resolve') && 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
-          !state.disabled && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-secondary',
-          !state.disabled && variant === 'current' && 'hover:bg-bg-hover',
-          state.disabled && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
-          state.disabled && (variant === 'muted' || variant === 'resolve') && 'text-text-disabled',
-          state.disabled && variant === 'outlined' && 'border border-border-default text-text-disabled',
-          // Always, disabled too: the colour of where it sits, and Resolve's green.
-          variant === 'current' && 'text-current',
-          variant === 'resolve' && 'signal:hover:bg-success-muted signal:hover:text-success-default',
-          pressed && 'bg-bg-active text-text-primary',
-          glow && 'signal:shadow-glow-accent',
-          // `pointer-events-none` only where the button is truly out of reach:
-          // with a `disabledReason` the button IS the tooltip's trigger, and a
-          // trigger the pointer cannot land on never opens one. Base UI already
-          // swallows the click.
-          state.disabled && !disabledReason && 'pointer-events-none',
-          state.disabled && 'cursor-not-allowed',
-          className,
-        )
-      }
-      aria-pressed={pressed}
-      {...props}
-    >
-      {children}
-    </BaseButton>
-  )
+  const unusable = disabled || !!disabledReason || formBusy
+  const look = (off: boolean) =>
+    cn(
+      // `shrink-0` stops a flex parent squashing the button; `self-center`
+      // stops one stretching it. Two different failures, and both have
+      // happened here: a row with no `items-*` drew this 24 wide and 228
+      // tall in Peek's TopicMoreMenu story (Katerina, 2026-09-11). A button
+      // is the size of its icon and its padding, whatever box it lands in.
+      //
+      // This is the one of the two that needs it: an IconButton states no
+      // height, so its cross size is `auto` and a stretching parent takes
+      // it. Measured in the same 260px row on 2026-09-12: 24px with this
+      // class, 226px without. `Button` states `h-8`/`h-6`, so it cannot be
+      // stretched and carries no `self-center` — see the note there.
+      'flex items-center justify-center p-1 rounded-lg transition-colors shrink-0 self-center cursor-pointer',
+      !off && variant === 'primary' && 'bg-accent-primary hover:bg-accent-hover text-text-inverse',
+      !off && (variant === 'muted' || variant === 'resolve') && 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
+      !off && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-secondary',
+      !off && variant === 'current' && 'hover:bg-bg-hover',
+      off && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
+      off && (variant === 'muted' || variant === 'resolve') && 'text-text-disabled',
+      off && variant === 'outlined' && 'border border-border-default text-text-disabled',
+      // Always, disabled too: the colour of where it sits, and Resolve's green.
+      variant === 'current' && 'text-current',
+      variant === 'resolve' && 'signal:hover:bg-success-muted signal:hover:text-success-default',
+      pressed && 'bg-bg-active text-text-primary',
+      glow && 'signal:shadow-glow-accent',
+      // `pointer-events-none` only where the button is truly out of reach:
+      // with a `disabledReason` the button IS the tooltip's trigger, and a
+      // trigger the pointer cannot land on never opens one. Base UI already
+      // swallows the click.
+      off && !disabledReason && 'pointer-events-none',
+      off && 'cursor-not-allowed',
+      className,
+    )
+  const button =
+    href && !unusable ? (
+      <a href={href} className={look(false)} {...(props as unknown as ComponentPropsWithRef<'a'>)}>
+        {children}
+      </a>
+    ) : (
+      <BaseButton
+        type={type}
+        disabled={unusable}
+        focusableWhenDisabled={!!disabledReason}
+        className={(state) => look(state.disabled)}
+        aria-pressed={pressed}
+        {...props}
+      >
+        {children}
+      </BaseButton>
+    )
 
   const label = disabledReason ?? tooltip
   if (label) {

package/src/IdentityMenu.mdx

@@ -62,6 +62,15 @@ import { IdentityMenu } from '@estiva-app/ui'
   row's full height, and the panel hung from the bottom of *that* — measured
   360px below the face, with a scrollbar it should not have had.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Everything a Menu owns: it floats, stays attached, closes on a press outside or on Escape, and walks its rows with the arrow keys | a menu of your own around the face |  |
+| Gives focus back to the face when it closes | focus code |  |
+
 ## Keys
 
 Since stage 4 the panel is a Base UI `Menu`, and **the arrow keys walk the

package/src/InlineChip.mdx

@@ -51,6 +51,14 @@ import { InlineChip } from '@estiva-app/ui'
 - A rich-text editor that renders chips from strings cannot use a component.
   `inlineChipClassName(tone)` gives it the same classes.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| With `href`, keeps a real address, so a modified click or a new tab still works | a `<span>` with a click handler |  |
+
 ## Props
 
 <Controls of={InlineChipStories.Neutral} />

package/src/Kbd.mdx

@@ -72,6 +72,10 @@ It renders what it is given and formats nothing. A modifier is called Cmd on
 Apple platforms and Ctrl elsewhere, and only the caller knows which it is
 looking at — so decide there and pass the finished label.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={KbdStories.Default} />

package/src/Link.mdx

@@ -28,6 +28,7 @@ the app decides how it navigates.
 - An action — something happens, nothing is navigated to → **Button**.
 - A row of a sidebar → **NavItem**. A tile of a rail → **RailItem**.
 - The trail back up → **Breadcrumb**.
+- A link that looks like an icon button → **IconButton** with `href`.
 - A word standing for a person or a thing, drawn in a small box → **InlineChip**
   with `href`.
 
@@ -60,6 +61,15 @@ import { Link } from '@estiva-app/ui'
   sit, so put those on your own element around the link, not on the link —
   the lint refuses a look passed in `className` (UIG-9).
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a link | `role="link"` | ✓ |
+| Is reachable with Tab | a `tabIndex` | ✓ |
+
 ## Props
 
 <Controls of={LinkStories.Text} />

package/src/Menu.mdx

@@ -41,7 +41,7 @@ definition either way.
 - Picking one value for a form field → **Select**.
 - Rows that toggle and stay open → that is a listbox, not a menu; a Checkbox
   inside a `menuitem` is invalid. Build it as a list in a **DialogShell**.
-- A strip of icon actions → a toolbar of **IconButton**s.
+- A strip of icon actions → **Toolbar**.
 - Who-you-are and where-you-are → **IdentityMenu**, already built on this.
 
 ## How
@@ -76,6 +76,21 @@ the trigger as "close" rather than as a press outside.
 
 <Canvas of={MenuStories.OnACard} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Enter and Space choose a row, Escape closes it | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys, and jumps to a row by its first letters | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a menu, and each row a menu item | `role="menu"` or `role="menuitem"` | ✓ |
+| Keeps its own open state, and closes when a row is chosen | `useState` for open |  |
+| Gives focus back to the trigger when it closes | focus code |  |
+
 ## Keys
 
 | Input | What happens |

package/src/MenuItem.mdx

@@ -25,8 +25,9 @@ other two), `destructive` in the error colour, `selected` as the fill.
 
 ## When not
 
-- Outside a menu — it renders `role="menuitem"` and belongs inside a
-  `role="menu"` container.
+- A single action that is not a row in a list → **Button**. Outside a
+  **Menu**, MenuItem is a plain button with a row's look, so a row-shaped
+  action at the top of a list — "Add members" — is fine.
 - Picking a form value → **Select**'s own options.
 - A row that toggles a checkbox → not a menu at all; see the Menu page.
 
@@ -50,6 +51,15 @@ import { IconPencil } from '@tabler/icons-react'
 - A destructive row's `leading` icon takes the error colour itself
   (`text-error-default`) — the row colours only its label.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Is a row of its Menu: the Menu highlights it, walks to it with the arrow keys, and closes when it is chosen | a highlight or a key handler on the row |  |
+| Opens its `submenu` with → and closes it with ← | a submenu of your own |  |
+
 ## Props
 
 <Controls of={MenuItemStories.Default} />

package/src/NavItem.mdx

@@ -48,6 +48,14 @@ import { NavItem } from '@estiva-app/ui'
   anchor prop passes through.
 - The label truncates; the count never gives up its width.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Marks the current place for assistive technology when `active` | `aria-current` |  |
+
 ## Props
 
 <Controls of={NavItemStories.Default} />

package/src/Person.mdx

@@ -39,6 +39,10 @@ import { Person } from '@estiva-app/ui'
   and words are always set together (the Sizes story shows the pairings).
 - The name truncates; give the container `min-w-0` room to let it.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={PersonStories.Named} />

package/src/PersonTrigger.mdx

@@ -53,6 +53,15 @@ import { Menu, PersonTrigger } from '@estiva-app/ui'
 - It is a native `<button>` on Base UI's Button: it takes a `ref` and every
   native button prop.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Is a button: Tab reaches it, Enter and Space call your `onClick` | a clickable `<div>` |  |
+| Names itself from the person's name, and says whether what it opens is open (`open`) | `aria-label` or `aria-expanded` |  |
+
 ## Keys
 
 | Key | Does |

package/src/Popover.mdx

@@ -83,7 +83,15 @@ so it is the one case the caller drives:
   open={selectionRect !== null}
   onOpenChange={(open) => !open && setSelectionRect(null)}
   ariaLabel="Formatting"
+  side="top"
+  contentClassName="p-1"
 >
+  <Toolbar aria-label="Formatting">
+    <ToolbarButton aria-label="Bold" tooltip="Bold" onClick={bold}>
+      <IconBold size={16} stroke={1.5} />
+    </ToolbarButton>
+  </Toolbar>
+</Popover>
 ```
 
 - **`anchor`** takes an element or a rect. A new rect moves the panel, so
@@ -116,6 +124,19 @@ something belongs on a `trigger`.
 
 <Canvas of={PopoverStories.FlippedForRoom} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Stays attached to its anchor on scroll and resize, and flips side when there is no room | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Escape closes it | a key listener on the page | ✓ |
+| Moves focus in when it opens, and back to the trigger when it closes | focus code |  |
+| Keeps its own open state | `useState` for open — unless you must know it (`open` / `onOpenChange`) |  |
+
 ## Keys
 
 | Input | What happens |

package/src/PreviewCard.mdx

@@ -45,7 +45,7 @@ pointer never sees it.
 import { PreviewCard } from '@estiva-app/ui'
 
 <PreviewCard content={<ItemDetail id={row.id} />} wrapperClassName="block w-full">
-  <ListRow …/>
+  <ListRow item={row} />
 </PreviewCard>
 ```
 
@@ -57,9 +57,12 @@ import { PreviewCard } from '@estiva-app/ui'
 - **It prefers the right of the trigger and flips** when that side has no room,
   staying 12px from the trigger and 8px clear of every screen edge. `side`
   changes the preference, not the promise.
-- **Width, padding and height are yours** through `className`. The default is
-  360px wide, capped at 300px or the room available, whichever is smaller — a
-  preview of one kind of thing is not the size of a preview of another.
+- **Width is yours** through `className`; **padding and rhythm** through
+  `contentClassName`. The default is 360px wide, 12px of padding, capped at
+  300px or the room available, whichever is smaller — a preview of one kind of
+  thing is not the size of a preview of another.
+- The padding sits inside the scrolling box, as in `Popover`, so the
+  scrollbar hugs the card's edge: its thumb 3px from it, like every panel's.
 - The trigger wrapper is `inline-flex`; a full-width row wants
   `wrapperClassName="block w-full"`.
 
@@ -82,6 +85,18 @@ lands.
 
 <Canvas of={PreviewCardStories.Loading} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Opens after the pointer rests, and stays up while the pointer moves into it | a hover timer |  |
+| Closes on Escape | a key handler |  |
+
 ## Keys
 
 There is no keyboard trigger, by design — see above.