# `lr-dialog` - **Import** `import '@aceshooting/lyra-ui/components/lr-dialog.js';` (stable tag alias; registers the tag) - **Class** `LyraDialog`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/dialog/dialog.class.js` - **Family** `components/overlays/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecations** none - **Optional peers** none - **Themeable via** 15 parts, 21 custom properties — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-dialog` / `confirm()` General-purpose modal/overlay plus a promise-based confirmation helper built on top of it. Removing `label` safely omits its fallback title. Open dialog and drawer names follow supported name and exclusion attribute changes on direct unslotted headings, while host naming retains precedence; nested and `slot=""` headings remain outside automatic discovery. ### `lr-dialog` A modal/overlay: `role="dialog"`, focus-trapped while open, dismissible via Escape or (opt-in) a backdrop click, and scroll-locks the document for as long as it's open. Mapped chrome is present by default: `label` renders as a visible title and `closable` renders a localized close button. `closable="false"` plus either header-suppression spelling support custom chrome: `no-header` is Shoelace's name and `without-header` is Web Awesome's. Both are current upstream spellings, both are read, and neither is deprecated. **Properties:** - `open: boolean = false` (reflected) — **changed in 8.0.0:** `lr-dialog` now also has a `show()`/`hide()` pair, and assigning `open` runs exactly the same lifecycle as calling them, so the property, the reflected attribute and the two methods can never disagree. `el.open = false` therefore emits the full close lifecycle and can be vetoed, where it used to be a silent state flip. Markup that renders open from the start (``) emits nothing. - `label: string = ''` — mapped visible title. The richer `label` slot wins over it. - `headingLevel: LyraHeadingLevel = '3'` (attribute `heading-level`, reflected) — `1`–`6` expose the generated visible title (string property or rich `label` slot) at that semantic level; invalid untyped values retain level 3, while `none` keeps visual title text without heading semantics. A direct light-DOM heading retains its own native/ARIA level. - `accessibleLabel: string = ''` (attribute `accessible-label`) — explicit accessible-only name; unlike `label`, it never renders visible text - `heading?: string` — legacy visible-title fallback, after the `label` slot and `label` property; it has no effect when a direct light-DOM heading already supplies custom chrome - `closable: boolean = true` (attribute `closable`, reflected) — renders the localized close (X) button. This true-default boolean parses `closable="false"`; removing the attribute also restores the default. - `noHeader: boolean = false` (attribute `no-header`, reflected) — Shoelace's spelling (`sl-dialog`'s `no-header`), which suppresses the entire header row - `withoutHeader: boolean = false` (attribute `without-header`, reflected) — **new in 8.0.0.** Web Awesome's spelling (`wa-dialog`'s `without-header`) for the same header suppression. Both names are current upstream spellings, both are read, and neither is deprecated or removable - `withFooter: boolean = false` (attribute `with-footer`, reflected) — keeps the footer wrapper rendered as an SSR/hydration presence hint even before assigned slot content is observable - `size: LyraSize = 'm'` (reflected) — `'2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large'`. Panel-width tier, on the shared six-step ladder: `20rem` (`2xs`), `24rem` (`xs`), `28rem` (`s`/`small`), `32rem` (`m`/`medium`, unchanged from before this property existed), `38rem` (`l`/`large`), `48rem` (`xl`) — each value feeds `--lr-dialog-max-width`'s private default. An explicit `--lr-dialog-width`/`--lr-dialog-max-width` still wins over every tier. - `lightDismiss: boolean = false` (attribute `light-dismiss`) — opt in to a backdrop click closing the dialog; Escape and explicit `close()`/`hide()` calls remain available. **Changed in 8.0.0:** this was previously spelled `no-light-dismiss`, an opt-_out_ whose default left backdrop dismissal on. The polarity now matches `wa-dialog` exactly, so a mechanical rename no longer flips what the markup does. - `modal: LyraDialogModalController` (writable, property only) — `activateExternal()` temporarily yields focus/Escape ownership to a third-party modal; balanced `deactivateExternal()` resumes it without changing `open` A plain host `aria-label` is the strongest naming override. It changes naming only: mapped title chrome remains visible. The fallback order appears below. **Methods:** - `show(): Promise` — opens the dialog and resolves after `lr-after-show`; no-op/veto returns an already-resolved promise - `hide(): Promise` — identical to `close('api')`, resolving after `lr-after-hide` - `close(reason: DialogCloseReason = 'api'): Promise` — closes the dialog, returns focus to whatever had it right before opening, and resolves after `lr-after-hide`. `DialogCloseReason = 'escape' | 'backdrop' | 'close-button' | 'api' | 'unmount' | string` — `'escape'`/`'backdrop'` are emitted by the dialog's own built-in dismiss triggers; `'close-button'` by the built-in header close button (rendered when `closable` is set); `'api'` covers `close()` with no argument, `hide()`, and `open = false`; `'unmount'` is emitted automatically if the dialog is removed from the DOM while still `open` by anything other than its own `close()` (a consumer's own cleanup code, a parent re-render that drops it); any other string is whatever a caller passes (e.g. a footer Cancel button calling `dlg.close('cancel')`, or `confirm()`'s own `'confirm'`/`'cancel'`). **Events:** - `lr-show` — cancelable pre-open veto - `lr-after-show` — opening animation finished - `lr-hide` — cancelable pre-close veto; detail is `{ source: Element }`, the host or built-in affordance that requested the transition - `lr-after-hide` — closing animation finished - `lr-initial-focus` — cancelable immediately before the first automatic focus movement. A CSS-hidden dialog defers it until rendered; reconnecting the same open activation does not repeat it. - `lr-request-close` — cancelable request from a built-in affordance; detail source is `'close-button' | 'keyboard' | 'overlay'`. Veto stops the close lifecycle. Direct `close()` and `hide()` calls do not emit this request event. - `lr-close` — cancelable, with `detail: DialogCloseReason`; emitted after `lr-hide`. The same name is already used by ``, ``, and ``, whose own docs describe an identical detail shape, so one listener covers all of them. A listener calling `preventDefault()` vetoes the close. Also fired (with reason `'unmount'`, non-cancelable there) when the dialog is removed from the DOM while still open. **But the name is not dialog-scoped.** Nine components in this library emit `lr-close`, several of them commonly nested *inside* a dialog: ``, ``/``, ``, ``, ``, and the three tool dialogs (``, ``, ``). Library events bubble and are composed, so a listener bound directly on `` also receives a descendant's close — a closable callout or tab inside a dialog would otherwise dismiss the whole dialog. Guard on the target, the way `` already does internally: ```js dialog.addEventListener('lr-close', (event) => { if (event.target !== event.currentTarget) return; // a descendant's close, not this dialog's // ... }); ``` The two `lr-after-*` events are never cancelable. The open sequence is `lr-show` → `lr-initial-focus` (when focus would move) → `lr-after-show`; the direct close sequence is `lr-hide` → `lr-close` → `lr-after-hide`. A built-in dismissal prepends `lr-request-close`. **Both state pre-events fire _before_ the state changes**, so reading `el.open` inside an `lr-show`/`lr-hide` handler returns the _old_ value — this is the polarity `wa-show`/`wa-hide` already had, and the opposite of what Lyra 7.x's own `lr-show`/`lr-hide` did on `lr-popover`/`lr-dropdown`. The `wa-*` → `lr-*` migration table treats the rename as mechanical, and as of 8.0.0 that is finally true for these four names: `wa-show`/`wa-after-show`/`wa-hide`/ `wa-after-hide` map to `lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide` with matching timing and matching cancelability. Code written against Lyra 7.x that read `el.open` in a handler, or assumed the events were informational rather than vetoable, has to be re-read. `lr-after-show`/`lr-after-hide` settle after the public registry animations `dialog.show` / `dialog.hide` (panel) and `dialog.overlay.show` / `dialog.overlay.hide` (backdrop). Per-element registrations win over page defaults; keyframes-only overrides retain the token-derived duration and easing. Under `prefers-reduced-motion: reduce`, registry timing flattens to zero while the end frame and lifecycle remain intact. Passing `null` skips native interpolation but still emits the matching after-event before the method promise resolves. Because dialogs now animate on close too, `lr-after-hide` is normally deferred by roughly one animation. A removal while open emits `lr-hide`, `lr-close` (reason `'unmount'`) and `lr-after-hide` in that order, none of them cancelable, since the element is already gone. **Stacking and the top layer:** an open dialog is promoted into the browser **top layer** (via `popover="manual"`), new in 8.0.0. That means it escapes every ancestor stacking context and every ancestor `overflow` clip: a `transform`ed parent, an `isolation: isolate` wrapper or a `z-index: 2147483647` sticky header can no longer render on top of it or crop it, which no `z-index` value alone can guarantee. The `z-index` in the stylesheet remains only as the fallback for a user agent without popover support, and `popover="manual"` is deliberate — light dismiss and Escape stay this component's own contract rather than the user agent's, where an `auto` popover would close on the user agent's terms instead. What a consumer sees: the host gains a `popover="manual"` attribute while open (component-owned bookkeeping — don't set or remove it), any `z-index` you were fighting with becomes irrelevant, and the panel is no longer clipped by an ancestor's `overflow: hidden`. Beyond that, the dialog participates in the shared per-document overlay stack: only the topmost overlay receives Escape, Tab trapping, or backdrop dismissal, while overlays beneath stay open until the top one closes. **Slots:** default (the dialog body), `label` (rich header content — an element, markup, anything; rendered inside `[part="heading"]` and used as the panel's accessible name, winning over the plain-string `label` and legacy `heading` properties), `header-actions` (extra header controls, rendered in the header row _before_ the built-in close button), `footer` (action buttons, rendered in a bottom row, hidden entirely when empty). The `label` and `header-actions` slots are new in 8.0.0. **CSS parts:** `base`; `backdrop overlay`; `panel dialog`; `header`; `heading title label`; `header-actions`; `close-button close-button__base`; `close-button__control`; `body`; `footer`. Names grouped together are additive aliases on the same functional node, so a mapped `::part(title)` rule styles the same visible title as Lyra's `::part(heading)`. `close-button__control` is the composed ``'s own native `

This cannot be undone.

 ``` A dialog with no chrome of Lyra's own, animating faster and blurring the page behind it: ```html Poster ``` Accessible naming and visible title are separate. Naming precedence is: (1) host `aria-label`, by attribute presence including an explicitly empty value, (2) `accessible-label`, (3) the copied text of an unslotted direct light-DOM heading, then (4) the shadow-owned visible title wrapper. Visible-title precedence is the rich `label` slot, then the mapped `label` property, then legacy `heading`. The direct-heading case copies text because an IDREF cannot cross from the panel's shadow tree to a light-DOM heading; the mapped title wrapper can use `aria-labelledby` because it lives in the same shadow root. `no-header`/`without-header` removes the mapped title, so custom-chrome dialogs should provide a direct heading, `accessible-label`, or host `aria-label`. **Known gotchas:** - `role="dialog"`/`aria-modal="true"` are only present on `[part="panel"]` while `open` is `true` — inspecting closed markup won't show them. - An `[autofocus]` element anywhere in the slotted content takes initial focus instead of the first focusable element, including one inside a slotted custom element's own open shadow root — so `` behaves like ``. With nothing marked, the first focusable element still wins, unchanged. - `lr-initial-focus` is the veto point for Lyra's automatic focus move. It fires once per logical open, only when the rendered panel is ready to receive focus; canceling it does not disable the trap or later focus return. - The host gains a `popover="manual"` attribute the first time it opens and keeps it from then on — only top-layer membership (`:popover-open`) tracks `open`, not the attribute — and carries `data-closing` for exactly as long as the exit animation runs (pointer events are dead for that window, so a dismissing dialog can't swallow a click meant for the page underneath). Both are component-owned bookkeeping — don't set or remove them. - Heading detection observes child, subtree, and character-data changes, so mutating an already-slotted direct heading's text updates the copied panel `aria-label` live. - Only _unslotted direct_ children are scanned for a heading — one nested several layers deep, inside a slotted custom element's own shadow root, or carrying a `slot` attribute, is left to the consumer to label explicitly via `label` or the `label` slot. - A reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its shared overlay registration and re-acquires the scroll lock if `open` was still `true` across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so `willUpdate()` alone wouldn't otherwise notice. - Tab-trap focus order follows the default (body) slot, then the `footer` slot — the same order the flattened tree already tabs through — and is resolved shadow-piercingly, so a slotted custom element's real focusable target inside its own shadow root is found even though the host tag itself isn't a native focusable element. ### `confirm()` A drop-in async replacement for `window.confirm()`, built on ``. ```ts import { confirm } from "@aceshooting/lyra-ui/components/overlays/dialog/confirm.js"; const ok = await confirm({ title: "Delete conversation?", description: "This cannot be undone.", confirmLabel: "Delete", variant: "danger", }); if (ok) deleteConversation(); ``` `confirm(options: ConfirmOptions): Promise` where `ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; variant?: 'neutral' | 'danger' /* = 'neutral' */ }`. Resolves `true` only when the confirm button is pressed — Escape, a backdrop click, and the cancel button all resolve `false`. It sets `lightDismiss = true` on its transient dialog explicitly, so the backdrop-click branch survives 8.0.0's flip of that property's own default to `false`. Mounts a transient `` on `document.body` for the duration of the call and removes it once settled, rather than reusing a persistent page-level region (contrast `lr-toast`'s `toaster.ts`). Concurrent calls are distinct dialogs in the shared overlay stack, each tied to its own returned promise. `title` becomes a direct light-DOM `

`, which per ``'s own heading-detection also drives the dialog's accessible name; `description`, if provided, becomes a direct light-DOM `

`. `variant: 'danger'` fills the confirm button with `--lr-color-danger` instead of `--lr-color-brand`, for destructive actions. The deprecated `tone` option that preceded `variant` was removed in 10.0.0. Confirm/cancel actions deliberately use native inline-styled `