@zeyos/zx 4.3.4 → 5.0.0

package/src/components/message/message.js

@@ -1,15 +1,32 @@
 import { Component } from '../../core/component.js';
-import { h } from '../../core/dom.js';
+import { h, resolveElement } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
 import { overlayHost } from '../../core/overlay-host.js';
+import { button } from '../button/button.js';
 
 /** @typedef {'info'|'success'|'warning'|'error'} MessageKind */
 
+/**
+ * The one command a message may carry, drawn as a small button beside its text.
+ * @typedef {Object} MessageAction
+ * @property {string} label Button text: a verb naming what happens ("Undo", "Approve", "Retry").
+ * @property {(event: MouseEvent) => void} [onclick] Runs when the button is activated, by pointer
+ *   or keyboard; the message closes right after it.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Button kind; the default is the
+ *   secondary button.
+ */
+
 /**
  * @typedef {Object} MessageShowOptions
  * @property {MessageKind|'danger'} [kind='info'] Message intent (`danger` aliases `error`).
- * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists.
+ * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists. A message
+ *   with an `action` stays at least 8000ms.
  * @property {boolean} [closable=true] Whether to render a close button.
+ * @property {MessageAction|null} [action=null] A command button inside the message. The message
+ *   never times out while the pointer is over it or focus is inside it.
+ * @property {Node|{toElement: () => Node|null}|null} [leading=null] Visual shown in place of the
+ *   kind icon, such as an Avatar's element. It is decorative — the message text must say what it
+ *   shows.
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating toast.
  */
 
@@ -21,7 +38,15 @@ import { overlayHost } from '../../core/overlay-host.js';
  * @property {number} [maxVisible=5] Maximum number of visible messages.
  */
 
-/** @typedef {{close: () => void}} MessageHandle */
+/**
+ * Returned by every `show()`: closes that message early. Closing one that already closed, or one
+ * still waiting in the queue, is safe.
+ * @typedef {Object} MessageHandle
+ * @property {() => void} close Closes the message.
+ */
+
+/** The shortest time a message that carries an action stays, in milliseconds. */
+export const MESSAGE_ACTION_MIN_TIMEOUT = 8000;
 
 /**
  * @typedef {Object} ProgressHandle
@@ -135,7 +160,7 @@ export class Message extends Component {
     maxVisible: 5
   };
 
-  /** @type {WeakMap<Element, Message>} */
+  /** @type {WeakMap<Element, Message>} Floating region per overlay host. */
   static #floating = new WeakMap();
 
   /** @returns {HTMLElement} */
@@ -145,6 +170,8 @@ export class Message extends Component {
     this._createdRoot = created;
     this._original = created ? null : snapshot(root);
     this._entries = new Set();
+    /** @type {Element|null} The overlay host this instance is the floating region of; null when inline. */
+    this._floatingHost = null;
     this._queue = new MessageQueue(normalizeLimit(this.options.maxVisible), (entry) => {
       this._activate(entry);
     });
@@ -161,10 +188,13 @@ export class Message extends Component {
    * @returns {MessageHandle}
    */
   show(msg, options = {}) {
+    const action = normalizeMessageAction(options.action);
     const settings = {
       kind: normalizeKind(options.kind ?? this.options.kind),
-      timeout: normalizeTimeout(options.timeout ?? this.options.timeout),
-      closable: options.closable ?? Boolean(this.options.closable)
+      timeout: messageTimeout(options.timeout ?? this.options.timeout, action !== null),
+      closable: options.closable ?? Boolean(this.options.closable),
+      action,
+      leading: resolveLeading(options.leading)
     };
     const entry = this._createEntry(msg, settings);
     this._entries.add(entry);
@@ -232,10 +262,33 @@ export class Message extends Component {
     return this.#floatingRegion(options.scope)._progress(text);
   }
 
+  /**
+   * Removes a floating region at once, toasts and all, without waiting for them to time out.
+   *
+   * A region already removes itself when its last toast closes, and one whose host has left the
+   * document is replaced on the next toast, so this is only for a host being torn down while
+   * toasts are still showing — an application view unmounting its themed shell, say.
+   * @param {Element|string} scope Element or selector whose nearest Zx theme scope owns the region,
+   *   as passed to `show()`.
+   * @returns {boolean} Whether there was a region to remove.
+   */
+  static disposeRegion(scope) {
+    if (scope == null) return false;
+    const context = resolveElement(scope);
+    if (!context) return false;
+    const host = overlayHost(context);
+    const region = Message.#floating.get(host);
+    if (!region) return false;
+    Message.#floating.delete(host);
+    region._disposeFloating();
+    return true;
+  }
+
   /** @returns {void} */
   destroy() {
     if (this._cleaned) return;
     this._cleaned = true;
+    this._floatingHost = null;
     for (const entry of this._entries) {
       clearEntryTimers(entry);
       entry.node.remove();
@@ -288,13 +341,13 @@ export class Message extends Component {
 
   /**
    * @param {string|Node} msg
-   * @param {{kind: MessageKind, timeout: number, closable: boolean}} settings
+   * @param {{kind: MessageKind, timeout: number, closable: boolean, action?: MessageAction|null, leading?: Node|null}} settings
    * @param {{pct: number, text: string}|null} [progress=null]
    * @returns {any}
    */
   _createEntry(msg, settings, progress = null) {
     const iconHost = h('span', { class: 'zx-message__icon', ariaHidden: 'true' },
-      icon(settings.kind, { size: 18 })
+      settings.leading ?? icon(settings.kind, { size: 18 })
     );
     const content = h('div', { class: 'zx-message__content' });
     if (isNode(msg)) content.append(msg);
@@ -315,9 +368,13 @@ export class Message extends Component {
       timer: null,
       exitTimer: null,
       closed: false,
+      hovered: false,
+      focused: false,
+      returnFocus: null,
       progressBar: null,
       progressFill: null
     };
+    if (settings.leading) node.dataset.leading = '';
 
     if (progress) {
       node.dataset.progress = '';
@@ -336,18 +393,56 @@ export class Message extends Component {
       syncProgress(entry, progress);
     }
 
+    if (settings.action) {
+      const { label, kind, onclick } = settings.action;
+      const control = button({ label, kind, size: 'sm' });
+      control.classList.add('zx-message__action');
+      node.append(control);
+      this.listen(control, 'click', (event) => {
+        if (entry.closed) return;
+        try {
+          onclick?.(/** @type {MouseEvent} */ (event));
+        } finally {
+          this._close(entry);
+        }
+      });
+    }
+
     if (settings.closable) {
       const close = h('button', {
         class: 'zx-icon-btn zx-message__close',
         type: 'button',
-        ariaLabel: 'Close message',
-        title: 'Close'
+        ariaLabel: this._message('message.close', 'Close message'),
+        title: this._message('message.closeTitle', 'Close')
       }, icon('x', { size: 14 }));
       node.append(close);
       this.listen(close, 'click', () => this._close(entry));
     }
-    this.listen(node, 'mouseenter', () => this._pause(entry));
-    this.listen(node, 'mouseleave', () => this._resume(entry));
+    // Hover and focus each hold the timer (WCAG 2.2.1): a reader moving to the action or the close
+    // button must not have the message vanish under them, and it counts down again only once
+    // neither holds it.
+    this.listen(node, 'mouseenter', () => {
+      entry.hovered = true;
+      this._pause(entry);
+    });
+    this.listen(node, 'mouseleave', () => {
+      entry.hovered = false;
+      this._resume(entry);
+    });
+    this.listen(node, 'focusin', (event) => {
+      if (!entry.focused) {
+        const from = /** @type {FocusEvent} */ (event).relatedTarget;
+        entry.returnFocus = isNode(from) && !node.contains(/** @type {Node} */ (from)) ? from : null;
+      }
+      entry.focused = true;
+      this._pause(entry);
+    });
+    this.listen(node, 'focusout', (event) => {
+      const to = /** @type {FocusEvent} */ (event).relatedTarget;
+      if (isNode(to) && node.contains(/** @type {Node} */ (to))) return;
+      entry.focused = false;
+      this._resume(entry);
+    });
     return entry;
   }
 
@@ -361,7 +456,7 @@ export class Message extends Component {
 
   /** @param {any} entry @returns {void} */
   _schedule(entry) {
-    if (entry.closed || entry.remaining <= 0) return;
+    if (entry.closed || entry.remaining <= 0 || entry.hovered || entry.focused) return;
     entry.startedAt = Date.now();
     entry.timer = setTimeout(() => this._close(entry), entry.remaining);
   }
@@ -376,7 +471,7 @@ export class Message extends Component {
 
   /** @param {any} entry @returns {void} */
   _resume(entry) {
-    if (entry.closed || entry.timer !== null) return;
+    if (entry.closed || entry.timer !== null || entry.hovered || entry.focused) return;
     if (entry.remaining <= 0) {
       this._close(entry);
       return;
@@ -389,10 +484,12 @@ export class Message extends Component {
     if (entry.closed) return;
     entry.closed = true;
     clearEntryTimers(entry);
+    returnFocus(entry);
     if (!this._queue.isActive(entry)) {
       this._queue.remove(entry);
       entry.node.remove();
       this._entries.delete(entry);
+      this._releaseIfEmpty();
       return;
     }
 
@@ -415,13 +512,57 @@ export class Message extends Component {
     entry.node.remove();
     this._entries.delete(entry);
     this._queue.remove(entry);
+    this._releaseIfEmpty();
+  }
+
+  /**
+   * Takes a floating region out of the document once its last toast has gone, so an emptied host
+   * is not left holding a region nobody uses. Inline areas stay: their element is the caller's.
+   * @returns {void}
+   */
+  _releaseIfEmpty() {
+    if (!this._floatingHost || this._entries.size > 0) return;
+    Message.#release(this);
   }
 
-  /** @param {Element|string|null|undefined} scope @returns {Message} */
+  /**
+   * Destroys a floating region and removes its element.
+   * @returns {void}
+   */
+  _disposeFloating() {
+    const region = this.el;
+    this.destroy();
+    region.remove();
+  }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @returns {string}
+   */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
+
+  /**
+   * Finds or creates the floating region for a scope. A cached region is reused only while it is
+   * still where it was put: a host emptied by `replaceChildren()` would otherwise keep receiving
+   * toasts in a node nobody can see.
+   * @param {Element|string|null|undefined} scope
+   * @returns {Message}
+   */
   static #floatingRegion(scope) {
-    const host = overlayHost(scope ?? null);
+    let host = overlayHost(scope ?? null);
+    // A scope that has itself left the document cannot show anything; the toast still must be seen.
+    if (!host.isConnected) host = overlayHost(null);
     const existing = this.#floating.get(host);
-    if (existing) return existing;
+    if (existing && existing.el.isConnected && existing.el.parentElement === host) return existing;
+    if (existing) {
+      this.#floating.delete(host);
+      existing._disposeFloating();
+    }
     const region = h('div', {
       class: 'zx-message-region',
       popover: 'manual',
@@ -430,10 +571,18 @@ export class Message extends Component {
     });
     host.append(region);
     const floating = new Message(region);
+    floating._floatingHost = host;
     this.#floating.set(host, floating);
     if (typeof region.showPopover === 'function') region.showPopover();
     return floating;
   }
+
+  /** @param {Message} region Floating region whose last toast closed. @returns {void} */
+  static #release(region) {
+    const host = region._floatingHost;
+    if (host && Message.#floating.get(host) === region) Message.#floating.delete(host);
+    region._disposeFloating();
+  }
 }
 
 /** @param {unknown} value @returns {MessageKind} */
@@ -449,6 +598,70 @@ function normalizeTimeout(value) {
   return Number.isFinite(timeout) ? Math.max(0, timeout) : 4000;
 }
 
+/**
+ * Settles how long a message stays. A message that carries an action stays at least
+ * `MESSAGE_ACTION_MIN_TIMEOUT`, so there is time to reach it; zero still means it stays until
+ * closed, and anything that is not a finite number falls back to the 4000ms default.
+ * @param {unknown} timeout Requested auto-dismiss delay in milliseconds.
+ * @param {boolean} [hasAction=false] Whether the message carries an action.
+ * @returns {number}
+ */
+export function messageTimeout(timeout, hasAction = false) {
+  const settled = normalizeTimeout(timeout);
+  return hasAction && settled > 0 ? Math.max(settled, MESSAGE_ACTION_MIN_TIMEOUT) : settled;
+}
+
+/**
+ * Copies a message action into the shape the message renders, or returns null when there is
+ * nothing to render: no object, or no label. An unknown `kind` reads as the default, secondary
+ * button, and a missing `onclick` leaves a button that only closes the message.
+ * @param {unknown} value Action descriptor.
+ * @returns {{label: string, kind: 'default'|'primary'|'danger'|'ghost', onclick: ((event: MouseEvent) => void)|null}|null}
+ */
+export function normalizeMessageAction(value) {
+  if (!value || typeof value !== 'object') return null;
+  const action = /** @type {Record<string, unknown>} */ (value);
+  const label = action.label == null ? '' : String(action.label).trim();
+  if (!label) return null;
+  const kind = ['primary', 'danger', 'ghost'].includes(String(action.kind))
+    ? /** @type {'primary'|'danger'|'ghost'} */ (action.kind) : 'default';
+  return {
+    label,
+    kind,
+    onclick: typeof action.onclick === 'function'
+      ? /** @type {(event: MouseEvent) => void} */ (action.onclick) : null
+  };
+}
+
+/**
+ * Accepts a node, or a component such as an Avatar, for the leading slot.
+ * @param {any} value Leading content.
+ * @returns {Node|null}
+ */
+function resolveLeading(value) {
+  if (isNode(value)) return /** @type {Node} */ (value);
+  if (value && typeof value === 'object' && typeof value.toElement === 'function') {
+    const element = value.toElement();
+    return isNode(element) ? element : null;
+  }
+  return null;
+}
+
+/**
+ * Hands focus back to where it came from when a message closes with focus inside it, so a keyboard
+ * reader is not dropped on the page body with the element they were on gone.
+ * @param {any} entry Message entry.
+ * @returns {void}
+ */
+function returnFocus(entry) {
+  const root = entry.node.getRootNode?.();
+  const active = root?.activeElement ?? globalThis.document?.activeElement;
+  if (!active || !entry.node.contains(active)) return;
+  const target = entry.returnFocus;
+  entry.returnFocus = null;
+  if (target?.isConnected && typeof target.focus === 'function') target.focus({ preventScroll: true });
+}
+
 /** @param {unknown} value @returns {number} */
 function normalizeLimit(value) {
   const limit = Number(value);

package/src/components/modal/modal.css

@@ -32,6 +32,21 @@
   padding: var(--zx-space-5);
 }
 
+/*
+ * The panel takes focus itself only as a fallback, when it holds nothing focusable at all. It is a
+ * surface rather than a control, so that programmatic focus paints no ring; a reader the browser
+ * reports as navigating by keyboard still gets one, because otherwise focus would be inside the
+ * overlay with nothing on screen saying so.
+ */
+.zx-modal:focus {
+  outline: none;
+}
+
+.zx-modal:focus-visible {
+  outline: 2px solid var(--zx-color-ring);
+  outline-offset: calc(-1 * var(--zx-space-1));
+}
+
 /*
  * `:modal` rather than `[open]`: only a dialog opened with `showModal()` blocks the page, and a
  * non-modal one (Sheet's `modal: false`) must leave the page scrollable behind it.

package/src/components/modal/modal.js

@@ -1,6 +1,15 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
-import { overlayHost } from '../../core/overlay-host.js';
+import { connectedOverlayHost, overlayHost } from '../../core/overlay-host.js';
+
+/**
+ * Controls initial focus may be placed on: what a reader reaches with Tab, rather than everything
+ * the platform will focus programmatically.
+ */
+const FOCUSABLE_SELECTOR = [
+  'a[href]', 'button:not([disabled])', 'input:not([disabled])', 'select:not([disabled])',
+  'textarea:not([disabled])', '[contenteditable="true"]', '[tabindex]:not([tabindex="-1"])'
+].join(',');
 
 /**
  * @typedef {Object} ModalOptions
@@ -9,7 +18,7 @@ import { overlayHost } from '../../core/overlay-host.js';
  * @property {boolean} [closable=true] Whether Escape may close the modal.
  * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal.
  * @property {boolean} [destroyOnClose=false] Whether to destroy the modal after it closes.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -18,6 +27,15 @@ import { overlayHost } from '../../core/overlay-host.js';
 /**
  * Thin native-dialog overlay with lifecycle-safe content and dismissal behavior.
  * The constructor always creates and appends a new dialog; its target argument is ignored.
+ *
+ * Accessibility is the platform's wherever the platform has an answer. The root is a real
+ * `<dialog>` and `_show()` presents it with `showModal()`, so focus containment, the inertness of
+ * everything behind it, Escape, the top layer and the implicit `dialog` role all come from the
+ * browser — there is no hand-written focus trap here, and adding one on top of `:modal` would be
+ * two traps fighting over the same Tab key. What the platform leaves undone is the rest of this
+ * class's accessibility work: it stops initial focus at the panel instead of the first control,
+ * and it restores focus to the opener only for its own native presentation, not for the popover
+ * one a non-modal subclass uses.
  * @fires Modal#open
  * @fires Modal#close
  * @fires Modal#cancel
@@ -42,6 +60,8 @@ export class Modal extends Component {
   #presentation = 0;
   /** @type {number[]} */
   #nativeClosingPresentations = [];
+  /** @type {Element|null} Element that had focus when the overlay was opened. */
+  #opener = null;
 
   /**
    * Creates a modal in the configured theme scope, or at document level when none is present.
@@ -64,6 +84,14 @@ export class Modal extends Component {
       if (!this.options.lightDismiss || event.target !== this.el || !isBackdropClick(this.el, event)) return;
       this.close();
     });
+    /*
+     * One listener for every close path, because `close` is the one event all four converge on:
+     * a footer button and a programmatic `close()` go through `_dismiss()`, Escape and a native
+     * dismissal arrive as the platform's own `close`, and light dismiss calls `close()` itself.
+     * A subclass that traps focus registers its own restore after this one and so wins, which is
+     * what keeps `Sheet`'s trap authoritative over its own capture.
+     */
+    this.on('close', () => this.#restoreFocus());
   }
 
   /**
@@ -112,6 +140,23 @@ export class Modal extends Component {
   _present() {
     this._show();
     this.#presentation += 1;
+    this.#syncModality();
+  }
+
+  /**
+   * Mirrors the presentation's real modality onto the panel as `aria-modal`.
+   *
+   * Asked of the platform (`:modal`) rather than of an option, so it stays true through every
+   * presentation a subclass chooses: `showModal()` is modal, a popover or an in-flow `show()` is
+   * not, and a sheet that moves between them is re-answered when it is presented again. The
+   * `<dialog>` element already carries the implicit `dialog` role and, while `:modal`, the
+   * implicit modal semantics — the attribute states them for assistive technology that reads the
+   * markup rather than the top-layer state.
+   * @returns {void}
+   */
+  #syncModality() {
+    if (this.el.matches(':modal')) this.el.setAttribute('aria-modal', 'true');
+    else if (this.el.getAttribute('aria-modal') === 'true') this.el.removeAttribute('aria-modal');
   }
 
   /**
@@ -158,6 +203,11 @@ export class Modal extends Component {
     }
     this.el.dataset.state = 'closed';
     delete this.el.dataset.zxOverlayOrder;
+    /*
+     * Only the flag this class raised. A subclass presenting non-modally writes
+     * `aria-modal="false"` and owns that value across its own presentations.
+     */
+    if (this.el.getAttribute('aria-modal') === 'true') this.el.removeAttribute('aria-modal');
     const pending = closingPresentation === undefined
       ? undefined
       : this.#pendingResults.get(closingPresentation);
@@ -168,6 +218,45 @@ export class Modal extends Component {
     return true;
   }
 
+  /**
+   * Returns focus to whatever held it when the overlay opened.
+   *
+   * A closing `<dialog>` restores focus itself, but only for its own native presentation and only
+   * while the opener is still where it was; doing it here covers the popover presentation a
+   * non-modal subclass uses, and covers `destroyOnClose`, which takes the opener's document
+   * position out from under the platform's own restore.
+   * @returns {void}
+   */
+  #restoreFocus() {
+    const opener = /** @type {HTMLElement|null} */ (this.#opener);
+    this.#opener = null;
+    if (opener?.isConnected && typeof opener.focus === 'function') opener.focus();
+  }
+
+  /**
+   * Places initial focus inside the panel.
+   *
+   * `showModal()` focuses an `autofocus` control when the content declares one and otherwise stops
+   * at the dialog element, which leaves a reader one Tab short of the first control. This keeps
+   * that preference — so a `Dialog` footer button marked `autofocus` still wins — and then falls
+   * through to the first focusable descendant, with the panel itself as the last resort so focus
+   * is never left outside the overlay.
+   * @returns {void}
+   */
+  _focusInitial() {
+    if (!this.isOpen()) return;
+    const target = initialFocusTarget(this.el);
+    if (target) {
+      target.focus();
+      return;
+    }
+    // A panel holding nothing focusable has to take focus itself, and is made focusable only for
+    // that: `tabindex="-1"` is programmatic focus, so it adds nothing to the Tab order.
+    const panel = /** @type {HTMLElement} */ (this.el);
+    if (!panel.hasAttribute('tabindex')) panel.setAttribute('tabindex', '-1');
+    panel.focus();
+  }
+
   /**
    * Creates the owned native dialog.
    * @returns {HTMLDialogElement}
@@ -177,10 +266,25 @@ export class Modal extends Component {
       class: 'zx-modal'
     }, h('div', { class: 'zx-modal__content', ref: 'content' })));
     dialog.dataset.state = 'closed';
-    this.mountTarget().append(dialog);
+    this._mountInitial(dialog);
     return dialog;
   }
 
+  /**
+   * Gives a freshly rendered dialog its first home.
+   *
+   * A `scope` that is not in the document yet cannot say which theme it belongs to, and the
+   * `<body>` that `mountTarget()` would answer is outside it. The dialog then stays detached and
+   * `open()` places it, by which time the scope is in place. Called from `render()`, so it may
+   * read `this.options` but no instance state.
+   * @param {HTMLDialogElement} dialog The rendered dialog.
+   * @returns {void}
+   */
+  _mountInitial(dialog) {
+    if (this.options.scope != null && !connectedOverlayHost(this.options.scope)) return;
+    this.mountTarget().append(dialog);
+  }
+
   /**
    * Opens the modal in the browser top layer.
    * @returns {this}
@@ -188,6 +292,12 @@ export class Modal extends Component {
    */
   open() {
     if (this.isOpen()) return this;
+    /*
+     * Captured before anything is presented, so it is the element the reader was actually on
+     * rather than whatever the overlay is about to focus. A subclass that traps focus before
+     * delegating here has already moved it and restores its own capture afterwards.
+     */
+    this.#opener = document.activeElement instanceof Element ? document.activeElement : null;
     const host = this.mountTarget();
     if (this.el.parentElement !== host) host.append(this.el);
     this.el.dataset.zxOverlayOrder = String(nextOverlayOrder());
@@ -196,10 +306,15 @@ export class Modal extends Component {
       this._present();
     } catch (error) {
       delete this.el.dataset.zxOverlayOrder;
+      // Nothing was presented, so nothing will close; a capture left behind would outlive its open.
+      this.#opener = null;
       throw error;
     }
     this.el.dataset.state = 'open';
     this.emit('open');
+    // Deferred by one microtask: the platform's own focusing step runs as part of presenting, and
+    // this has to be the one that settles, not the one it overwrites.
+    queueMicrotask(() => this._focusInitial());
     return this;
   }
 
@@ -278,6 +393,47 @@ export class Modal extends Component {
  * @type {CustomEvent<Record<string, never>>}
  */
 
+/**
+ * Picks the control initial focus belongs on inside an overlay panel: an `autofocus` control when
+ * the content named one, the first focusable descendant otherwise, and null when the panel holds
+ * neither and must take focus itself.
+ *
+ * Candidates in a hidden, `aria-hidden` or `inert` subtree are skipped, because `focus()` on one
+ * is a silent no-op: a `Dialog` whose header close button is hidden by `closable: false`, or whose
+ * other registered views sit hidden in the same body, would otherwise "focus" nothing at all and
+ * leave the reader with no way into the overlay.
+ * @param {Element} root Overlay panel.
+ * @returns {HTMLElement|null}
+ */
+export function initialFocusTarget(root) {
+  const declared = root.querySelector('[autofocus]:not([disabled])');
+  if (declared && isFocusable(declared, root)) return /** @type {HTMLElement} */ (declared);
+  for (const candidate of root.querySelectorAll(FOCUSABLE_SELECTOR)) {
+    if (isFocusable(candidate, root)) return /** @type {HTMLElement} */ (candidate);
+  }
+  return null;
+}
+
+/**
+ * Whether a candidate can take focus from where it sits inside the panel.
+ *
+ * Duck-typed on `focus` rather than tested against `HTMLElement`, so a focusable SVG or MathML
+ * element inside the panel is a candidate rather than a silently skipped one.
+ * @param {Element} element Candidate found by the focusable selector.
+ * @param {Element} root Panel the search is bounded by.
+ * @returns {boolean}
+ */
+function isFocusable(element, root) {
+  if (typeof (/** @type {HTMLElement} */ (element).focus) !== 'function') return false;
+  for (let node = /** @type {Element|null} */ (element); node; node = node.parentElement) {
+    if (/** @type {HTMLElement} */ (node).hidden) return false;
+    if (node.getAttribute('aria-hidden') === 'true') return false;
+    if (node.hasAttribute('inert')) return false;
+    if (node === root) break;
+  }
+  return true;
+}
+
 /**
  * @param {Element} target
  * @param {Node|string|number|{toElement: () => Node|null}|null|undefined} content