Duolith docs

0034. One <overlay> element, with a kind, shown in one overlay layer

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

Context

The second half of the kit needs content above the screen: sheets, dialogs, alert dialogs, menus, popovers, tooltips, toasts and a select's list. Each must trap or not trap focus, make the page behind it unavailable or not, close on Escape, come back to its trigger, stack with the others in the right order, and sit next to an anchor without leaving the window. Parts are .duo components built from the language's own elements (decision 0028), so the language needs a way to say "this is shown above the screen", and the runtime needs one place that does the hard parts the same way for every part. On iOS and Android each of these is a native presentation (a sheet, an alert, a menu, a popover), so the language should say which one is meant, not how the web draws it.

Decision

  1. **A new element, <overlay kind="...">**, written anywhere in a page or component. kind is one of a fixed list in spec/language/elements.yaml (overlays:), written as text: dialog and sheet (modal), popover, menu, listbox and tooltip (anchored, not modal), and toasts (the toast region). The kind decides its default role, whether it is modal, how it is placed and the keys it answers to. An unknown or empty kind, or one written as an expression, is E0150.
  2. Its attributes: open={...} shows it; anchor={id} names the element it belongs to (required for anchored kinds, and not empty, E0151); placement is top or bottom with an optional -start or -end, or left or right (E0152 otherwise); detent is a sheet's medium or large (E0153), and on:detent runs with the new one when the sheet is dragged to it. Each attribute decides one thing, so writing one twice is E0154. role, label and described-by work as on any element, so an alert dialog is <overlay kind="dialog" role="alert-dialog">.
  3. It asks, it does not close itself: Escape, a press on the backdrop (except for an alert dialog), a press outside an anchored overlay, Tab in a menu or listbox, and a sheet dragged down all fire on:dismiss. The overlay closes when the file sets its open to false, so the state that says it is open is never out of step with what shows. A tooltip is the exception: it opens and closes itself on hover and focus.
  4. Four roles join the list: alert-dialog, menu-item, option and combobox. selected on an option is aria-selected on the web.
  5. One overlay layer at run time. On the web every overlay is moved to #duolith-overlays, the last child of the body, when it is built; a comment stays where it was written. While open:
    • the newest overlay is on top (it is moved to the end of the layer on opening), and Escape goes to the top one, so a menu inside a sheet closes before the sheet;
    • a modal kind makes the rest of the page, and overlays opened before it, inert, wraps Tab and Shift+Tab inside itself and stops the page scrolling; the toast region is never inert and always above;
    • an anchored kind is position: fixed next to its anchor, on the preferred side unless only the other has room (flip), moved along to keep 8px from the window's edges (shift), its height capped at the room it has, and placed again on scroll and resize;
    • its trigger (the anchor, or the first control inside it) carries aria-haspopup, aria-expanded and aria-controls; a tooltip's trigger is described by it instead;
    • focus moves in on opening (a menu's first item, a listbox's selected option, else the first control, else the overlay) and goes back to where it was on closing; ArrowDown or ArrowUp on a closed menu or listbox trigger opens it.
  6. An overlay belongs to its screen. A comment marks where it was written. When the router moves a screen out of the front, its open overlays are hidden and stop counting for the stack, inertness and scroll lock, but stay open; when a kept screen comes back they show again. When a screen is dropped, its overlays are removed with it. An overlay written inside another overlay belongs to that one: when the outer one closes, the open ones inside it get on:dismiss and are hidden at once, so state bound to them ends up false and focus goes back to where it was before the outer one opened. One whose file ignores the dismiss stays open and shows again when the outer one reopens. When the outer one's screen leaves, the ones inside it are hidden and kept open, like the outer one. (Added with the gallery example.)
  7. Animations are the part's. The overlay carries data-state="open" once it is showing, and stays in the page 200 ms after closing so a part's styles can transition out; with prefers-reduced-motion: reduce it is hidden at once, and every kit part turns its transitions off. A sheet's runtime drag sets data-detent and raises on:detent, so a part can bind its detent. The release that ends a drag is not also a press, and a press on a modal's backdrop must start and end there to dismiss it.

Alternatives considered

OptionWhy not
The web's <dialog> and the popover attribute (the top layer)The top layer orders by opening, so the toast region could not stay above a modal opened after it; showModal makes everything outside the dialog inert, toasts included; and its rules have no native counterpart
A portal element (<portal>) plus separate focus-trap and position attributesEvery part would assemble the same five behaviours, with room to get one wrong; the kind names what native presents
One element per kind (<sheet>, <menu>, <tooltip> ...)Seven elements sharing all their attributes; the list of kinds is data, and adding one is a line in the specification
Overlays that close themselves and write open backTwo writers of one state; on:dismiss keeps the file in charge, as bind: does for fields
Positioning with a third-party libraryOne small function covers flip, shift and height for the placements the language allows; nothing to adapt for native
kind={expression}The kind decides structure and native presentation, so it must be known when the page is built

Consequences

  • kind is the word for which overlay this is; it is not a variant (the glossary's variant avoids "kind" for a part's alternative looks).
  • The web runtime gains web/overlay.ts and its helpers (overlay-keys.ts, overlay-position.ts, overlay-gestures.ts, overlay-tooltip.ts); the mount hands an overlay's attribute changes to it. The base stylesheet gains .st-overlay rules, and the theme a scrim colour for backdrops.
  • Native emitters will map each kind to the platform's presentation, and must keep the same focus, Escape (back gesture) and dismiss rules.
  • Glossary terms added: overlay, anchor, detent, toast.