Duolith docs

0035. Overlay parts open with bind:open or a trigger piece; menus take their items as data

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP7 (kit, overlays)

Context

The kit's overlay parts (Sheet, Dialog, AlertDialog, Menu, Popover, Tooltip, Toast, Select) are written on the <overlay> element (decision 0034). A page must be able to open one from anywhere (after a save, from a menu item) and also, most often, from the button next to it, without writing the same state and handler each time. The trigger must also be the control that focus returns to and that says the overlay is open.

Decision

  • **open is a bindable prop** (decision 0029) on Sheet, Dialog, AlertDialog, Menu and Popover: <Dialog bind:open={editing}> opens it from state, and the part writes false back when it is dismissed. Left unbound, the part keeps its own.
  • **A trigger piece** holds the control that opens it: <piece name="trigger"><Button label="Edit" /></piece>. The part wraps it in a view that takes no space (display: contents) and is the overlay's anchor, so pressing the control opens (or, for Menu and Popover, toggles) the overlay, the control carries aria-expanded, and focus returns to it.
  • Tooltip wraps its control as children, rather than a piece, because it has nothing else to show; Select is its own trigger, a combobox button.
  • Menu items are data: items={[{ label, icon, destructive, disabled, onSelect }, { divider: true }]}. A list of objects keeps the keyboard model in one place (the runtime's menu keys over menu-item roles) and needs no second part.
  • AlertDialog puts Cancel first, so the first focus lands on the safe action without a new attribute; Escape cancels and the backdrop does nothing.
  • Dialog has title, message, a body (children) and an actions piece; dismissible={false} leaves only the actions to close it.

Alternatives considered

OptionWhy not
Only bind:open, no trigger pieceEvery page repeats a state, a handler, and loses the trigger's aria-expanded and the focus return
A separate <MenuTrigger>/<MenuItem> family of partsMore parts to learn, and items would need context passed between components, which the language does not have
An autofocus attribute for AlertDialog's safe actionA new attribute for one part; DOM order gives the same result
Opening imperatively (dialog.open())The language has no component references; state already says what shows

Consequences

  • A trigger piece should hold exactly one control; the first one inside it is the trigger.
  • Pickers and other future parts reuse the same pattern on <overlay kind="listbox"> or kind="popover".