@estiva-app/ui 0.9.0 → 0.10.0

package/src/Popover.stories.tsx

@@ -0,0 +1,222 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconBold, IconItalic, IconLink } from '@tabler/icons-react'
+import { useRef, useState, type KeyboardEvent } from 'react'
+import { Button } from './Button'
+import { MenuPanel } from './Menu'
+import { Popover } from './Popover'
+import { TextInput } from './TextInput'
+import { Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from './Toolbar'
+
+/**
+ * A floating panel from a trigger — the menu's surface, with none of a menu's
+ * semantics. Reach for it when the panel holds *content*: a field, a row of
+ * controls, a small form. Reach for **Menu** when it holds a list of actions.
+ *
+ * Like a menu it portals and places itself, so the canvas draws the surface
+ * with `MenuPanel` and everything below it is live (Katerina, D25).
+ */
+const meta = {
+  title: 'Overlays/Popover',
+  component: Popover,
+  decorators: [(Story) => <div className="flex min-h-[260px] w-full items-start justify-center pt-6"><Story /></div>],
+  args: { children: null },
+  argTypes: {
+    trigger: { control: false },
+    children: { control: false },
+    anchor: { control: false },
+    onOpenChange: { control: false },
+    actionsRef: { control: false },
+    finalFocus: { control: false },
+  },
+} satisfies Meta<typeof Popover>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** The surface, at rest: whatever the caller puts in it. */
+export const Default: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="w-[280px] gap-2">
+      <span className="text-body-2-strong text-text-primary">A small form</span>
+      <TextInput value="Item one" onChange={() => {}} aria-label="Name" />
+      <div className="flex justify-end gap-2">
+        <Button size="small">Cancel</Button>
+        <Button size="small" variant="primary">
+          Save
+        </Button>
+      </div>
+    </MenuPanel>
+  ),
+}
+
+/**
+ * Live. Click the button: focus lands in the field, Tab walks the contents in
+ * order because they are contents and not menu items, and Escape closes and
+ * gives focus back to the button.
+ *
+ * The Cancel and Save buttons are not menu items, so choosing one does not
+ * close the panel by itself — that is what `actionsRef` is for.
+ */
+export const FromATrigger: Story = {
+  parameters: { controls: { disable: true } },
+  render: function Live() {
+    const [name, setName] = useState('Item one')
+    const actions = useRef<{ close: () => void; unmount: () => void } | null>(null)
+    return (
+      <Popover
+        trigger={<Button variant="outlined">Rename</Button>}
+        actionsRef={actions}
+        ariaLabel="Rename this"
+        className="w-[280px] gap-2"
+      >
+        <TextInput autoFocus value={name} onChange={(e) => setName(e.target.value)} aria-label="Name" />
+        <div className="flex justify-end gap-2">
+          <Button size="small" onClick={() => actions.current?.close()}>
+            Cancel
+          </Button>
+          <Button size="small" variant="primary" onClick={() => actions.current?.close()}>
+            Save
+          </Button>
+        </div>
+      </Popover>
+    )
+  },
+}
+
+/**
+ * The shape this component was added for: a `Toolbar` with a text field in
+ * it. In a `Menu` the arrow keys and the typeahead would fight the field.
+ *
+ * It opens **above** its trigger, as a panel holding a toolbar does — the
+ * strip acts on what is under it.
+ */
+export const AToolbar: Story = {
+  parameters: { controls: { disable: true } },
+  render: function FormattingStrip() {
+    const [url, setUrl] = useState('')
+    return (
+      <Popover
+        trigger={<Button variant="outlined">Formatting</Button>}
+        ariaLabel="Formatting"
+        /* Above the trigger, like every panel that holds a toolbar: a strip of
+           controls acts on what is under it, so it stands over that rather
+           than on top of it. `side` is the *preference* — Base UI flips it
+           when there is no room, which is the reason the placement is its job
+           and not ours. */
+        side="top"
+        className="w-auto min-w-0 p-1"
+      >
+        {/* The strip is a `Toolbar`, so the whole row is ONE Tab stop and the
+            arrow keys walk it — four stops before, one after. */}
+        <Toolbar aria-label="Formatting" surface={false}>
+          <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="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>
+      </Popover>
+    )
+  },
+}
+
+/**
+ * The other mode: **no trigger element at all.** A panel hung from a rect the
+ * caller measured — a text selection, which is not a control and cannot be
+ * one. It is controlled, because there is nothing for Base UI to watch, and it
+ * takes `finalFocus` to say where focus goes when it closes.
+ *
+ * Select some of the text below.
+ */
+export const FromASelection: Story = {
+  parameters: { controls: { disable: true } },
+  render: function Selection() {
+    const [rect, setRect] = useState<DOMRect | null>(null)
+    const body = useRef<HTMLParagraphElement>(null)
+    const read = () => {
+      const selection = window.getSelection()
+      if (!selection || selection.isCollapsed || !body.current?.contains(selection.anchorNode)) return setRect(null)
+      setRect(selection.getRangeAt(0).getBoundingClientRect())
+    }
+    /*
+     * Escape must not reopen what it just closed, and it did — measured
+     * 2026-09-08: the keydown closes the panel, `finalFocus` puts focus back
+     * on this paragraph, and the same key's KEYUP then lands here and re-reads
+     * a selection that is still perfectly alive. The panel reopened in the
+     * same gesture, so Escape looked as if it did nothing at all.
+     *
+     * A real editor's selection toolbar has exactly this shape, so the guard
+     * belongs in the example rather than in a footnote.
+     */
+    const readOnKey = (event: KeyboardEvent<HTMLParagraphElement>) => {
+      if (event.key === 'Escape') return
+      read()
+    }
+    return (
+      <div className="w-[420px]">
+        {/* `tabIndex={-1}`: `finalFocus` needs something that can take focus,
+            and a paragraph cannot until it is told it may. An editor already
+            can, which is the real case; `-1` gives this one the same property
+            without adding a Tab stop. Without it focus is left on the document
+            body when the panel closes — measured. */}
+        <p ref={body} tabIndex={-1} onMouseUp={read} onKeyUp={readOnKey} className="text-[14px] leading-[1.6] text-text-primary outline-none">
+          Select any part of this sentence with the pointer, and a panel appears
+          above the selection rather than beside a button — because a selection
+          is not a control and there is no trigger to hang from.
+        </p>
+        {/* Always rendered, `open` toggled — never `{rect && <Popover…>}`.
+            Mounting the panel only while it is open takes Base UI's own state
+            machine away with it, and the exits go with it: measured, Escape
+            closed the panel and a fresh selection sometimes failed to reopen
+            it, both intermittently. Rendered once and told when to open, both
+            are exact every time. */}
+        <Popover
+          anchor={rect}
+          open={rect !== null}
+          onOpenChange={(next) => !next && setRect(null)}
+          finalFocus={body}
+          /* Above the selection, not below it (Katerina, 2026-09-08): below,
+             the panel covers the line after the selection — and that is the
+             line that tells you what you have just selected. Base UI flips it
+             when the top has no room. */
+          side="top"
+          ariaLabel="Formatting"
+          className="w-auto min-w-0 p-1"
+        >
+          <Toolbar aria-label="Formatting" surface={false}>
+            <ToolbarButton aria-label="Bold" tooltip="Bold">
+              <IconBold size={16} stroke={1.5} />
+            </ToolbarButton>
+            <ToolbarButton aria-label="Italic" tooltip="Italic">
+              <IconItalic size={16} stroke={1.5} />
+            </ToolbarButton>
+          </Toolbar>
+        </Popover>
+      </div>
+    )
+  },
+}
+
+/**
+ * **The side is a preference, not a promise.** This one asks for the top in a
+ * row pinned to the top of the screen, so there is no room above it and Base
+ * UI puts it below. Deciding that is the whole reason the placement is not
+ * ours to compute.
+ */
+export const FlippedForRoom: Story = {
+  parameters: { controls: { disable: true }, layout: 'fullscreen' },
+  render: () => (
+    <div className="flex h-[260px] w-full items-start justify-center pt-2">
+      <Popover trigger={<Button variant="outlined">Asks for the top</Button>} side="top" ariaLabel="A panel" className="w-[240px]">
+        <span className="text-body-2 text-text-primary">No room above, so it is below.</span>
+      </Popover>
+    </div>
+  ),
+}

package/src/Popover.test.tsx

@@ -0,0 +1,188 @@
+// @vitest-environment jsdom
+/**
+ * What the Popover page claims, pinned — including the two things that
+ * distinguish it from a `Menu`, which is the whole reason it exists: its
+ * contents are not menu items, and a field inside it keeps its focus.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useRef, useState } from 'react'
+import { Button } from './Button'
+import { Popover } from './Popover'
+import { TextInput } from './TextInput'
+
+afterEach(cleanup)
+
+function Basic({ children, onOpenChange }: { children?: React.ReactNode; onOpenChange?: (open: boolean) => void }) {
+  return (
+    <Popover trigger={<Button variant="outlined">Trigger</Button>} ariaLabel="A panel" onOpenChange={onOpenChange}>
+      {children ?? <button type="button">Inside</button>}
+    </Popover>
+  )
+}
+
+describe('Popover', () => {
+  it('is a named panel, portalled out of what rendered it', async () => {
+    const user = userEvent.setup()
+    const { container } = render(<Basic />)
+    await user.click(screen.getByRole('button', { name: 'Trigger' }))
+    const panel = await screen.findByRole('dialog', { name: 'A panel' })
+    expect(container.contains(panel)).toBe(false)
+  })
+
+  /** The distinction from Menu, in one assertion: nothing in here is a
+   *  menuitem, so nothing takes the arrow keys or the typeahead. */
+  it('its contents are contents, not menu items', async () => {
+    const user = userEvent.setup()
+    render(<Basic />)
+    await user.click(screen.getByRole('button', { name: 'Trigger' }))
+    await screen.findByRole('dialog')
+    expect(screen.queryByRole('menu')).toBeNull()
+    expect(screen.queryAllByRole('menuitem')).toHaveLength(0)
+    expect(screen.getByRole('button', { name: 'Inside' })).toBeTruthy()
+  })
+
+  /** The link editor is why this component exists: a panel that steals focus
+   *  from its own field would be useless. */
+  it('a field inside keeps the focus its autoFocus asked for', async () => {
+    const user = userEvent.setup()
+    function Field() {
+      const [value, setValue] = useState('')
+      return <TextInput autoFocus value={value} onChange={(e) => setValue(e.target.value)} aria-label="Link address" />
+    }
+    render(
+      <Basic>
+        <Field />
+      </Basic>,
+    )
+    await user.click(screen.getByRole('button', { name: 'Trigger' }))
+    const field = await screen.findByRole('textbox', { name: 'Link address' })
+    expect(document.activeElement).toBe(field)
+    await user.keyboard('abc')
+    expect((field as HTMLInputElement).value).toBe('abc')
+  })
+
+  it('closes on Escape and gives focus back to the trigger', async () => {
+    const user = userEvent.setup()
+    render(<Basic />)
+    const trigger = screen.getByRole('button', { name: 'Trigger' })
+    await user.click(trigger)
+    await screen.findByRole('dialog')
+    await user.keyboard('{Escape}')
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
+    expect(document.activeElement).toBe(trigger)
+  })
+
+  it('closes on a press outside', async () => {
+    const user = userEvent.setup()
+    render(
+      <>
+        <Basic />
+        <button type="button">Elsewhere</button>
+      </>,
+    )
+    await user.click(screen.getByRole('button', { name: 'Trigger' }))
+    await screen.findByRole('dialog')
+    await user.click(screen.getByRole('button', { name: 'Elsewhere' }))
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
+  })
+
+  it('a second press of the trigger closes it', async () => {
+    const user = userEvent.setup()
+    render(<Basic />)
+    const trigger = screen.getByRole('button', { name: 'Trigger' })
+    await user.click(trigger)
+    await screen.findByRole('dialog')
+    await user.click(trigger)
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
+  })
+
+  /** A control inside a panel is content, not a menu row: pressing it does not
+   *  close the panel, which is what `actionsRef` is for. */
+  it('a button inside does not close it; actionsRef does', async () => {
+    const user = userEvent.setup()
+    function WithActions() {
+      const actions = useRef<{ close: () => void; unmount: () => void } | null>(null)
+      return (
+        <Popover trigger={<Button variant="outlined">Trigger</Button>} actionsRef={actions} ariaLabel="A panel">
+          <Button size="small">Does nothing</Button>
+          <Button size="small" onClick={() => actions.current?.close()}>
+            Close
+          </Button>
+        </Popover>
+      )
+    }
+    render(<WithActions />)
+    await user.click(screen.getByRole('button', { name: 'Trigger' }))
+    await screen.findByRole('dialog')
+    await user.click(screen.getByRole('button', { name: 'Does nothing' }))
+    expect(screen.queryByRole('dialog')).toBeTruthy()
+    await user.click(screen.getByRole('button', { name: 'Close' }))
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
+  })
+
+  it('reports opening and closing to a caller that asks', async () => {
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+    render(<Basic onOpenChange={onOpenChange} />)
+    await user.click(screen.getByRole('button', { name: 'Trigger' }))
+    await screen.findByRole('dialog')
+    expect(onOpenChange).toHaveBeenCalledWith(true)
+    await user.keyboard('{Escape}')
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+  })
+
+  /** The other mode: no trigger element, hung from a rect the caller measured. */
+  it('opens from an anchored rect with no trigger at all', async () => {
+    render(
+      <Popover anchor={new DOMRect(10, 10, 40, 20)} open ariaLabel="Formatting">
+        <button type="button">Bold</button>
+      </Popover>,
+    )
+    expect(await screen.findByRole('dialog', { name: 'Formatting' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: 'Trigger' })).toBeNull()
+    expect(screen.getByRole('button', { name: 'Bold' })).toBeTruthy()
+  })
+
+  /**
+   * An anchored panel leaves focus where it was. The person is still in
+   * whatever produced it — a text selection means a caret in the text — and a
+   * panel that took the caret would end the edit it exists to serve.
+   */
+  it('an anchored panel does not take focus', async () => {
+    render(
+      <>
+        <input aria-label="Where the person is" />
+        <Popover anchor={new DOMRect(10, 10, 40, 20)} open ariaLabel="Formatting">
+          <button type="button">Bold</button>
+        </Popover>
+      </>,
+    )
+    const field = screen.getByRole('textbox', { name: 'Where the person is' })
+    field.focus()
+    await screen.findByRole('dialog')
+    expect(document.activeElement).toBe(field)
+  })
+
+  /** An anchored panel has the same two exits as any other. It is the mode
+   *  with no trigger, so this is the only place they can be asserted. */
+  it('an anchored panel still closes on Escape and on a press outside', async () => {
+    const user = userEvent.setup()
+    const onOpenChange = vi.fn()
+    render(
+      <>
+        <Popover anchor={new DOMRect(10, 10, 40, 20)} open onOpenChange={onOpenChange} ariaLabel="Formatting">
+          <button type="button">Bold</button>
+        </Popover>
+        <button type="button">Elsewhere</button>
+      </>,
+    )
+    await screen.findByRole('dialog')
+    await user.keyboard('{Escape}')
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+    onOpenChange.mockClear()
+    await user.click(screen.getByRole('button', { name: 'Elsewhere' }))
+    expect(onOpenChange).toHaveBeenCalledWith(false)
+  })
+})

package/src/Popover.tsx

@@ -0,0 +1,153 @@
+import { useMemo, type ReactElement, type ReactNode, type RefObject } from 'react'
+import { Popover as BasePopover } from '@base-ui/react/popover'
+import { cn } from './cn'
+import { MenuPanel } from './Menu'
+
+/**
+ * A floating panel from a trigger — the same elevated surface a `Menu` uses,
+ * with none of a menu's semantics. New at stage 4 (2026-09-07).
+ *
+ * **It exists because `Menu` was being used for this.** Peek's selection
+ * toolbar puts a text field inside one, and its debug panel fills one with
+ * toggle rows; neither is a list of actions, and since the menus moved onto
+ * Base UI a `Menu` gives its contents roving focus and typeahead, which is
+ * wrong for both and fights a text field outright. Beyond those two, Peek
+ * hand-writes overlay behaviour in thirteen files — six `createPortal`, five
+ * outside-click listeners, seven position calculations against
+ * `window.innerWidth` (`COMPONENTS-PEEK.md` F5). This is what they become.
+ *
+ * **The API is `Menu`'s**: it takes the `trigger` and owns everything after —
+ * the toggle, the placement, the dismissal and the focus return. What differs
+ * is inside: a `Popover` announces itself as a dialog, its contents are
+ * ordinary content, and Tab walks them in order.
+ *
+ * The one thing a `Menu` has no use for is the second mode below: a panel with
+ * no trigger element at all, hung from a rect the caller measured — a toolbar
+ * over a text selection. That mode is controlled, because there is nothing for
+ * Base UI to watch.
+ */
+export interface PopoverProps {
+  /**
+   * The control that opens the panel. Any element that forwards its ref and
+   * spreads its props — this package's `Button`, `IconButton` and
+   * `PersonTrigger` all do.
+   *
+   * Base UI can only do the toggle, the placement, the dismissal and the focus
+   * return if it knows which element opened the panel. Give it the trigger
+   * unless there is genuinely no element to give — see `anchor`.
+   */
+  trigger?: ReactElement
+  /**
+   * For a panel with **no trigger element**: an element, or a rect the caller
+   * measured — a text selection's. Pair it with `open`, since there is nothing
+   * for Base UI to watch.
+   *
+   * An anchored panel **does not take focus**, because the person is still in
+   * whatever produced it. That also means it cannot be reached by keyboard, so
+   * everything in one must be reachable another way.
+   *
+   * Render it always and toggle `open`; do not mount it only while it is open.
+   */
+  anchor?: HTMLElement | DOMRect | null
+  /** Which of the panel's edges hangs from the trigger's. Default left. */
+  align?: 'left' | 'right'
+  /**
+   * Which side of the trigger, or of the anchor, the panel prefers. Default
+   * `bottom`.
+   *
+   * **A toolbar over a text selection wants `top`** (Katerina, 2026-09-08):
+   * below, it covers the line you are about to read next, and it is the line
+   * *after* the selection that tells you what you have selected. It is a
+   * preference, not a promise — Base UI flips it when that side has no room.
+   */
+  side?: 'top' | 'bottom'
+  /** Controlled, for a caller that must know or must force it. Required with
+   *  `anchor`; with a `trigger`, leave both off and the panel keeps its own. */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  /**
+   * Where focus goes when the panel closes. With a `trigger` it goes back to
+   * the trigger and this is not needed. An anchored panel never took focus, so
+   * this only matters when something inside it did — a field the person tabbed
+   * or clicked into: point it at what they came from, or focus is left on the
+   * document body.
+   */
+  finalFocus?: RefObject<HTMLElement | null>
+  /** Base UI's imperative handle. `actions.current?.close()` shuts the panel —
+   *  for the Cancel and Save buttons a form panel ends with. */
+  actionsRef?: RefObject<{ close: () => void; unmount: () => void } | null>
+  /** Names the panel for assistive tech. A panel with a visible heading can
+   *  point at it instead, with `aria-labelledby`. */
+  ariaLabel?: string
+  children: ReactNode
+  /** On the panel's surface — its width, its internal rhythm. */
+  className?: string
+}
+
+/** The 4px between the panel and what it hangs from, and the 8px it keeps
+ *  clear of every screen edge — `Menu`'s numbers, because it is the same box. */
+const GAP = 4
+const VIEWPORT_PAD = 8
+
+export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open, onOpenChange, finalFocus, actionsRef, ariaLabel, children, className }: PopoverProps) {
+  /* A rect is not an element, so it becomes a virtual anchor — the one shape
+     Floating UI takes besides an element. */
+  const anchorTarget = useMemo(() => {
+    if (!anchor) return undefined
+    if (anchor instanceof Element) return anchor
+    return { getBoundingClientRect: () => anchor }
+  }, [anchor])
+
+  return (
+    <BasePopover.Root
+      open={open}
+      onOpenChange={onOpenChange ? (next) => onOpenChange(next) : undefined}
+      actionsRef={actionsRef}
+      /* Non-modal: the page behind keeps its scrollbar, so opening a panel
+         never shifts the layout, and a toolbar over a text selection must not
+         take the page away from the person using it. */
+      modal={false}
+    >
+      {trigger && <BasePopover.Trigger render={trigger} />}
+      <BasePopover.Portal>
+        <BasePopover.Positioner
+          anchor={anchorTarget}
+          side={side}
+          align={align === 'right' ? 'end' : 'start'}
+          sideOffset={GAP}
+          collisionPadding={VIEWPORT_PAD}
+          className="z-50 data-[anchor-hidden]:hidden"
+        >
+          <BasePopover.Popup
+            aria-label={ariaLabel}
+            /*
+             * From a trigger, focus lands on the first thing in the panel —
+             * the field, in the panel this component exists for — and goes
+             * back to the trigger when it closes.
+             *
+             * From an anchor, it does not move at all. A panel with no trigger
+             * appeared rather than being asked for, and the person is still in
+             * the middle of what produced it: a toolbar over a text selection
+             * that took the caret out of the text would end the edit it exists
+             * to serve. Measured 2026-09-08: with focus moved into the panel,
+             * the first control's tooltip opens on `:focus-visible` and eats
+             * the Escape that should have closed the panel, and the caller's
+             * re-read of the selection fights the panel's own dismissal — both
+             * intermittently. Neither happens once focus stays put.
+             *
+             * The cost is stated on the page: an anchored panel cannot be
+             * reached by keyboard, so what is in one must also be reachable
+             * some other way.
+             */
+            initialFocus={trigger ? undefined : false}
+            finalFocus={finalFocus}
+            className={cn('min-w-[180px] max-h-[var(--available-height)] overflow-y-auto outline-none', className)}
+            render={<MenuPanel />}
+          >
+            {children}
+          </BasePopover.Popup>
+        </BasePopover.Positioner>
+      </BasePopover.Portal>
+    </BasePopover.Root>
+  )
+}

package/src/PreviewCard.mdx

@@ -0,0 +1,98 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PreviewCardStories from './PreviewCard.stories'
+
+<Meta of={PreviewCardStories} />
+
+# PreviewCard
+
+**More of a thing, on hover.**
+
+A list shows one line per thing, because a list has to. This is where the rest
+of that thing goes: rest the pointer on a row and a card opens beside it,
+holding whatever the row had no room for. It closes when the pointer leaves,
+and — unlike a tooltip — you can move into it, so what it holds can be long,
+can scroll, and can be read at your own pace.
+
+It is a **read**, not a control. Nothing in a preview card may be the only way
+to reach anything: there is no keyboard trigger, so a person who does not use a
+pointer never sees it.
+
+<Canvas of={PreviewCardStories.Default} />
+
+## When
+
+- **A row is a summary and the thing has more to it.** The row stays one line;
+  the card carries the rest. This is the case it exists for.
+- **A reference could say what it refers to** — a name, a code, a short id —
+  without a trip to another page.
+- **The reader would otherwise click, look, and come back.** If a preview
+  saves that round trip, it earns its place.
+
+## When not
+
+- **A word for a control** → **WithTooltip**. The test is not length, it is
+  whether the content is worth pointing at: a label is a tooltip, something you
+  might read, scroll or copy is this.
+- **Anything the reader must have** → put it in the page. A hover is not a
+  route; it does not exist for a keyboard.
+- **Content with controls in it** → **Popover**, opened by a click, so the
+  controls can be reached and stayed with.
+- **A list of actions** → **Menu**.
+
+## How
+
+```tsx
+import { PreviewCard } from '@estiva-app/ui'
+
+<PreviewCard content={<ItemDetail id={row.id} />} wrapperClassName="block w-full">
+  <ListRow …/>
+</PreviewCard>
+```
+
+- **`content` renders only while the card is open.** A preview that fetches
+  therefore fetches for the row being pointed at, not once per row on screen.
+- **It opens 350ms after the pointer comes to rest** and closes 200ms after it
+  leaves. The wait stops a card flashing at every row as a pointer crosses a
+  list; the 200ms is what lets you cross the gap into the card.
+- **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.
+- The trigger wrapper is `inline-flex`; a full-width row wants
+  `wrapperClassName="block w-full"`.
+
+<Canvas of={PreviewCardStories.FlippedAtAnEdge} />
+
+### It can scroll, and that is the point
+
+A card taller than its cap scrolls, and the reader can reach the scrollbar
+because the pointer can enter the card. That is the difference from a tooltip,
+stated as a behaviour rather than as a rule.
+
+<Canvas of={PreviewCardStories.Scrolling} />
+
+### While it is loading
+
+Draw a **skeleton**, not a spinner. A preview has a known shape, so the
+skeleton says "this is what is coming"; a spinner only says "wait". It also
+holds the card at the size it is about to be, so nothing jumps when the content
+lands.
+
+<Canvas of={PreviewCardStories.Loading} />
+
+## Keys
+
+There is no keyboard trigger, by design — see above.
+
+| Input | What happens |
+|---|---|
+| pointer rests on the trigger | opens after 350ms |
+| pointer moves into the card | it stays up, and can be scrolled |
+| pointer leaves both | closes after 200ms |
+| Escape | closes |
+
+## Props
+
+<Controls of={PreviewCardStories.OnARow} />