@zeyos/zx 5.0.0 → 5.2.0

package/src/components/menu-button/menu-button.js

@@ -101,6 +101,9 @@ export class MenuButton extends Component {
       content: null
     });
     this.#panel = this.#dropdown.getPanel();
+    // Escape reaches the menu through the overlay stack, which offers it only to the topmost layer;
+    // the menu decides where focus goes. Items are reached with the arrow keys, not Tab.
+    this.#dropdown._configure({ onEscape: () => this.#dismiss(), tabReach: false });
     this.#panel.classList.add('zx-menu-button__menu');
     this.#panel.setAttribute('role', 'menu');
     // The menu is named by its trigger, as the APG menu-button pattern has it. An id given here to
@@ -126,7 +129,7 @@ export class MenuButton extends Component {
       if (this.isOpen()) this.close();
       else {
         this.open();
-        this.#roving.focusFirst();
+        this.#focusFirstItem();
       }
     });
     this.listen(this.el, 'keydown', (event) => this.#onTriggerKeydown(event));
@@ -135,6 +138,9 @@ export class MenuButton extends Component {
       if (item && this.#panel.contains(item)) this.#selectElement(item, event);
     });
     this.listen(this.#panel, 'keydown', (event) => this.#onMenuKeydown(event));
+    // A choice row runs across, not down: Left and Right move within it, Up and Down leave it.
+    // Capture, so the menu's own roving focus never sees the keys this takes.
+    this.listen(this.#panel, 'keydown', (event) => this.#onChoiceKeydown(event), { capture: true });
   }
 
   /**
@@ -158,7 +164,7 @@ export class MenuButton extends Component {
    */
   setItems(items) {
     this.#items = Array.isArray(items) ? items.slice() : [];
-    this.#panel.replaceChildren(...renderMenuEntries(this.#items, 'menu-button'));
+    this.#panel.replaceChildren(...renderMenuEntries(this.#items, 'menu-button', { choices: true }));
     return this;
   }
 
@@ -183,6 +189,15 @@ export class MenuButton extends Component {
     return this;
   }
 
+  /**
+   * Opens the menu when it is closed, and closes it when it is open. Opening this way moves no
+   * focus; `focusFirst()` opens with focus on the first item.
+   * @returns {this}
+   */
+  toggle() {
+    return this.isOpen() ? this.close() : this.open();
+  }
+
   /**
    * Reports whether the menu is open.
    * @returns {boolean}
@@ -208,7 +223,7 @@ export class MenuButton extends Component {
    */
   focusFirst(options = {}) {
     this.open(options);
-    this.#roving.focusFirst();
+    this.#focusFirstItem();
     return this;
   }
 
@@ -256,18 +271,11 @@ export class MenuButton extends Component {
     event.preventDefault();
     this.open();
     if (event.key === 'ArrowUp') this.#roving.focusLast();
-    else this.#roving.focusFirst();
+    else this.#focusFirstItem();
   }
 
   /** @param {KeyboardEvent} event @returns {void} */
   #onMenuKeydown(event) {
-    if (event.key === 'Escape') {
-      event.preventDefault();
-      const target = this.#returnTarget();
-      this.close();
-      target?.focus();
-      return;
-    }
     if (event.key === 'Tab') {
       this.close();
       return;
@@ -283,10 +291,88 @@ export class MenuButton extends Component {
     this.#typeahead(event);
   }
 
+  /**
+   * Escape, as the overlay stack routes it here: closes the menu, and returns focus when the menu
+   * held it (or it had already fallen to the body).
+   * @returns {void}
+   */
+  #dismiss() {
+    const active = document.activeElement;
+    const reclaim = !active || active === document.body || this.#panel.contains(active);
+    const target = this.#returnTarget();
+    this.close();
+    if (reclaim) target?.focus();
+  }
+
+  /** Focuses the first item, or, when that is a choice row, its checked option. @returns {void} */
+  #focusFirstItem() {
+    this.#roving.focusFirst();
+    const first = this.#menuItems()[0];
+    const checked = first?.hasAttribute('data-menu-option')
+      ? first.parentElement?.querySelector('[aria-checked="true"]') : null;
+    if (checked instanceof HTMLElement) checked.focus();
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  #onChoiceKeydown(event) {
+    const option = /** @type {Element|null} */ (event.target)?.closest?.('[data-menu-option]');
+    if (!(option instanceof HTMLElement) || !this.#panel.contains(option)) {
+      // Arriving at a choice row from another item lands on its checked option, not its nearest.
+      if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+      const items = this.#menuItems();
+      const index = items.indexOf(/** @type {HTMLElement} */ (event.target));
+      if (index < 0) return;
+      const next = items[(index + (event.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length];
+      const row = next?.hasAttribute('data-menu-option') ? next.parentElement : null;
+      if (!row) return;
+      event.preventDefault();
+      event.stopPropagation();
+      /** @type {HTMLElement} */ (row.querySelector('[aria-checked="true"]') ?? next).focus();
+      return;
+    }
+    const row = /** @type {HTMLElement[]} */ ([...(option.parentElement?.children ?? [])]);
+    const items = this.#menuItems();
+    let target = null;
+    if (event.key === 'ArrowLeft') target = row[(row.indexOf(option) - 1 + row.length) % row.length];
+    else if (event.key === 'ArrowRight') target = row[(row.indexOf(option) + 1) % row.length];
+    else if (event.key === 'ArrowDown') target = items[(items.indexOf(row.at(-1)) + 1) % items.length];
+    else if (event.key === 'ArrowUp') target = items[(items.indexOf(row[0]) - 1 + items.length) % items.length];
+    else return;
+    event.preventDefault();
+    event.stopPropagation();
+    // Into another choice row, focus lands on its checked option.
+    const checked = target?.closest('[role="group"]')?.querySelector('[data-menu-option][aria-checked="true"]');
+    const next = event.key === 'ArrowDown' || event.key === 'ArrowUp' ? /** @type {HTMLElement} */ (checked ?? target) : target;
+    next?.focus();
+  }
+
+  /** @param {HTMLElement} element @param {Record<string, any>} entry @param {Event|null} event @returns {void} */
+  #selectChoice(element, entry, event) {
+    const option = entry.options?.[Number(element.getAttribute('data-menu-option'))];
+    if (!option || option.disabled) {
+      event?.preventDefault();
+      return;
+    }
+    // A setting changes in place and the menu stays open, so its effect shows.
+    for (const sibling of element.parentElement?.children ?? []) {
+      sibling.setAttribute('aria-checked', String(sibling === element));
+    }
+    element.focus();
+    entry.onselect?.(option.value, entry, this);
+    // A handler that closed the menu leaves focus on a hidden option: it goes where a close sends it.
+    if (!this.isOpen() && (element.contains(document.activeElement) || document.activeElement === document.body)) {
+      this.#returnTarget()?.focus();
+    }
+  }
+
   /** @param {Element} element @param {Event|null} [event=null] @returns {void} */
   #selectElement(element, event = null) {
     const index = Number(element.getAttribute('data-menu-item'));
     const item = this.#items[index];
+    if (item && typeof item === 'object' && item.type === 'choice') {
+      this.#selectChoice(/** @type {HTMLElement} */ (element), item, event);
+      return;
+    }
     if (!isMenuItem(item) || item.disabled) {
       event?.preventDefault();
       return;

package/src/components/message/message.js

@@ -1,7 +1,8 @@
 import { Component } from '../../core/component.js';
 import { h, resolveElement } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
-import { overlayHost } from '../../core/overlay-host.js';
+import { overlayScope } from '../../core/overlay-host.js';
+import { overlayStack } from '../../core/overlay-stack.js';
 import { button } from '../button/button.js';
 
 /** @typedef {'info'|'success'|'warning'|'error'} MessageKind */
@@ -160,9 +161,6 @@ export class Message extends Component {
     maxVisible: 5
   };
 
-  /** @type {WeakMap<Element, Message>} Floating region per overlay host. */
-  static #floating = new WeakMap();
-
   /** @returns {HTMLElement} */
   render() {
     const created = !this.el;
@@ -170,8 +168,14 @@ 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. */
+    /** @type {Element|null} The theme scope this instance is the floating region of; null when inline. */
     this._floatingHost = null;
+    /** @type {Element|null} Where the floating region was last put: its scope, or the topmost modal. */
+    this._placedIn = null;
+    /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} The region's toast entry. */
+    this._overlay = null;
+    /** @type {(() => void)|null} Stops following the overlay stack. */
+    this._unfollow = null;
     this._queue = new MessageQueue(normalizeLimit(this.options.maxVisible), (entry) => {
       this._activate(entry);
     });
@@ -276,10 +280,8 @@ export class Message extends Component {
     if (scope == null) return false;
     const context = resolveElement(scope);
     if (!context) return false;
-    const host = overlayHost(context);
-    const region = Message.#floating.get(host);
+    const region = Message.#regionFor(overlayScope(context));
     if (!region) return false;
-    Message.#floating.delete(host);
     region._disposeFloating();
     return true;
   }
@@ -288,7 +290,13 @@ export class Message extends Component {
   destroy() {
     if (this._cleaned) return;
     this._cleaned = true;
+    this._unfollow?.();
+    this._unfollow = null;
+    const overlay = this._overlay;
+    this._overlay = null;
+    overlay?.release();
     this._floatingHost = null;
+    this._placedIn = null;
     for (const entry of this._entries) {
       clearEntryTimers(entry);
       entry.node.remove();
@@ -525,6 +533,23 @@ export class Message extends Component {
     Message.#release(this);
   }
 
+  /**
+   * Puts a floating region where it can be seen and used: inside the topmost open modal dialog
+   * while one is open — outside it, `showModal()` would leave every toast unclickable — and in its
+   * own theme scope otherwise. Re-showing it after a move puts it back on top of the top layer.
+   * @returns {void}
+   */
+  _rehome() {
+    const host = this._floatingHost;
+    if (!host) return;
+    const target = overlayStack.topmostModal() ?? host;
+    if (this.el.parentElement === target && this._placedIn === target) return;
+    target.append(this.el);
+    this._placedIn = target;
+    const region = /** @type {HTMLElement} */ (this.el);
+    if (typeof region.showPopover === 'function' && !region.matches(':popover-open')) region.showPopover();
+  }
+
   /**
    * Destroys a floating region and removes its element.
    * @returns {void}
@@ -554,33 +579,48 @@ export class Message extends Component {
    * @returns {Message}
    */
   static #floatingRegion(scope) {
-    let host = overlayHost(scope ?? null);
+    let host = overlayScope(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 && existing.el.isConnected && existing.el.parentElement === host) return existing;
-    if (existing) {
-      this.#floating.delete(host);
-      existing._disposeFloating();
+    if (!host.isConnected) host = overlayScope(null);
+    const existing = this.#regionFor(host);
+    if (existing && existing.el.isConnected && existing.el.parentElement === existing._placedIn) {
+      existing._rehome();
+      return existing;
     }
+    existing?._disposeFloating();
     const region = h('div', {
       class: 'zx-message-region',
       popover: 'manual',
       role: 'status',
       ariaLive: 'polite'
     });
-    host.append(region);
     const floating = new Message(region);
     floating._floatingHost = host;
-    this.#floating.set(host, floating);
-    if (typeof region.showPopover === 'function') region.showPopover();
+    // A toast entry on the overlay stack: the registry of regions, and the reason a press on a
+    // toast dismisses no drawer or menu. Following the stack moves the region into a modal dialog
+    // when one opens and back out when it closes.
+    floating._overlay = overlayStack.push({ kind: 'toast', root: region, owner: floating });
+    floating._unfollow = overlayStack.subscribe(() => floating._rehome());
+    floating._rehome();
     return floating;
   }
 
+  /**
+   * The live floating region of a theme scope, from the overlay stack's toast entries.
+   * @param {Element} host Theme scope.
+   * @returns {Message|null}
+   */
+  static #regionFor(host) {
+    for (const entry of overlayStack.entries()) {
+      if (entry.kind === 'toast' && entry.owner instanceof Message && entry.owner._floatingHost === host) {
+        return entry.owner;
+      }
+    }
+    return null;
+  }
+
   /** @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();
   }
 }

package/src/components/modal/modal.css

@@ -39,7 +39,7 @@
  * overlay with nothing on screen saying so.
  */
 .zx-modal:focus {
-  outline: none;
+  outline-color: transparent;
 }
 
 .zx-modal:focus-visible {

package/src/components/modal/modal.js

@@ -1,6 +1,7 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
-import { connectedOverlayHost, overlayHost } from '../../core/overlay-host.js';
+import { connectedOverlayHost, overlayScope } from '../../core/overlay-host.js';
+import { pushOverlay } from '../../core/overlay-stack.js';
 
 /**
  * Controls initial focus may be placed on: what a reader reaches with Tab, rather than everything
@@ -62,6 +63,8 @@ export class Modal extends Component {
   #nativeClosingPresentations = [];
   /** @type {Element|null} Element that had focus when the overlay was opened. */
   #opener = null;
+  /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} Entry on the overlay stack while shown. */
+  #overlay = null;
 
   /**
    * Creates a modal in the configured theme scope, or at document level when none is present.
@@ -103,7 +106,9 @@ export class Modal extends Component {
    * @returns {Element}
    */
   mountTarget() {
-    return overlayHost(this.options.scope);
+    // The theme scope, never an open dialog: a dialog opened from inside another stacks above it in
+    // the top layer wherever it lives, and nesting it would tie its rendering to the outer one.
+    return overlayScope(this.options.scope);
   }
 
   /**
@@ -159,6 +164,61 @@ export class Modal extends Component {
     else if (this.el.getAttribute('aria-modal') === 'true') this.el.removeAttribute('aria-modal');
   }
 
+  /**
+   * Describes the current presentation for the overlay stack, or returns null to stay off it.
+   *
+   * The kind is read from the platform like `aria-modal` is: a `showModal()` dialog is `modal`,
+   * and its Escape and backdrop stay the browser's; anything else is `non-modal`, and a subclass
+   * presenting that way adds the Escape and outside-press handling it wants.
+   * @returns {import('../../core/overlay-stack.js').OverlayEntryOptions|null}
+   * @protected
+   */
+  _overlayEntry() {
+    return {
+      kind: this.el.matches(':modal') ? 'modal' : 'non-modal',
+      root: this.el,
+      owner: this,
+      anchor: this.#opener
+    };
+  }
+
+  /**
+   * Re-registers the current presentation on the overlay stack: called after every presentation,
+   * including a subclass's change of address that bypasses `open()`.
+   * @returns {void}
+   * @protected
+   */
+  _syncOverlay() {
+    this._releaseOverlay();
+    if (!this._isShown()) return;
+    const entry = this._overlayEntry();
+    if (!entry) return;
+    this.#overlay = pushOverlay(entry);
+    this.el.dataset.zxOverlayOrder = String(this.#overlay.order);
+  }
+
+  /**
+   * Takes the overlay off the stack. Safe to call repeatedly.
+   * @returns {void}
+   * @protected
+   */
+  _releaseOverlay() {
+    const overlay = this.#overlay;
+    this.#overlay = null;
+    delete (/** @type {HTMLElement} */ (this.el)).dataset.zxOverlayOrder;
+    overlay?.release();
+  }
+
+  /**
+   * Whether a node is inside this overlay or anything opened from it, as the overlay stack sees it.
+   * @param {Node|null|undefined} node Candidate.
+   * @returns {boolean}
+   * @protected
+   */
+  _overlayContains(node) {
+    return this.#overlay ? this.#overlay.contains(node) : this.el.contains(node ?? null);
+  }
+
   /**
    * Hides the current presentation and records which generation its queued close event belongs to.
    * @param {string} [result=''] Native string return value.
@@ -202,7 +262,7 @@ export class Modal extends Component {
       return false;
     }
     this.el.dataset.state = 'closed';
-    delete this.el.dataset.zxOverlayOrder;
+    this._releaseOverlay();
     /*
      * Only the flag this class raised. A subclass presenting non-modally writes
      * `aria-modal="false"` and owns that value across its own presentations.
@@ -300,16 +360,15 @@ export class Modal extends Component {
     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());
     this.el.returnValue = '';
     try {
       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._syncOverlay();
     this.el.dataset.state = 'open';
     this.emit('open');
     // Deferred by one microtask: the platform's own focusing step runs as part of presenting, and
@@ -362,6 +421,8 @@ export class Modal extends Component {
     if (this.#destroying) return;
     this.#destroying = true;
     if (this.isOpen()) this._dismiss();
+    // The queued close that would settle it never arrives once listeners are aborted.
+    this._releaseOverlay();
     super.destroy();
   }
 
@@ -458,11 +519,3 @@ function isBackdropClick(dialog, event) {
   return event.clientX < rect.left || event.clientX > rect.right ||
     event.clientY < rect.top || event.clientY > rect.bottom;
 }
-
-/** @returns {number} */
-function nextOverlayOrder() {
-  const orders = Array.from(document.querySelectorAll('[data-zx-overlay-order]'), (element) =>
-    Number(element.getAttribute('data-zx-overlay-order')) || 0
-  );
-  return Math.max(0, ...orders) + 1;
-}