## When to use

Confirm-in-context micro-decisions: rename a row, set a status, pick a label, schedule a thing. The decision belongs here (anchored to the trigger), not over there (centered modal). Three signals it's the right pattern: the action is reversible, the user must still see the surrounding context, and the form is one to three fields. Anything bigger goes in a drawer or modal; anything smaller is a menu-ui or inline edit.

## Rename in context

Click "Rename" → popover-ui opens anchored to the trigger, carrying a card-ui with a heading, single input, and Cancel + Save actions. The rest of the page stays interactive (no backdrop, no focus trap). Click outside or press Escape to dismiss.

Q4-budget-draft.xlsx
Rename file

## Set status

Status-picker pattern: trigger shows the current state, popover carries a select + a short note field. Closes on save; the trigger updates to reflect the new state.

PR #3247 — Add cursor pagination In review
Change status
Open In review Approved Merged

## Schedule send

Two-field scheduling popover anchored to a split-button (primary action + caret for alternatives). Date + time pickers fit in the popover; the primary send button stays interactive while the user is choosing.

Schedule send Picks the next available slot in your timezone

## Composition rules

- popover-ui carries the anchor + dismiss — Popover API handles outside-click + Escape; you don't wire it. Default `placement="bottom-start"` orients the dialog LtR (popover's left edge anchored to the trigger's left edge, growing rightward); the browser's `position-try-fallbacks` auto-flips to `bottom-end` when the popover would overflow the viewport.
- card-ui inside the content slot — gives you the heading + body + footer structure for free. Keep `min-width` ≥ 280 px so the form fits without wrap; cap at ~480 px.
- Cancel button gets `data-popover-close` — the popover's built-in dismiss handler closes on click without further wiring.
- Non-modal means non-blocking — no backdrop, no focus trap, no aria-modal. Page interaction continues; the user can scroll, hover other rows, even open another popover.
- One to three fields max — if the form grows beyond three fields, the popover-as-dialog stops working (vertical overflow, ambiguous "where am I?"). Promote to `drawer-ui` or `modal-ui`.
- Primary action is the form verb — "Rename", "Save", "Schedule" — never "OK". The pattern's whole point is to make the decision tangible in context.

## Cross-references

- popover-ui · card-ui · field-ui — primitives composed here.
- modal-ui — page-blocking dialog alternative (use when the decision is irreversible or affects unrelated context).
- drawer-ui — edge-anchored multi-field form alternative (use when the form has > 3 fields).
- menu-ui — popover-ui specialization for action lists (use instead when content is a list of items, not a form).