@zeyos/zx 4.4.0 → 5.2.0

package/src/components/message/message.js

@@ -1,15 +1,33 @@
 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 { 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 */
 
+/**
+ * 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 +39,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,9 +161,6 @@ export class Message extends Component {
     maxVisible: 5
   };
 
-  /** @type {WeakMap<Element, Message>} */
-  static #floating = new WeakMap();
-
   /** @returns {HTMLElement} */
   render() {
     const created = !this.el;
@@ -145,6 +168,14 @@ export class Message extends Component {
     this._createdRoot = created;
     this._original = created ? null : snapshot(root);
     this._entries = new Set();
+    /** @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);
     });
@@ -161,10 +192,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 +266,37 @@ 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 region = Message.#regionFor(overlayScope(context));
+    if (!region) return false;
+    region._disposeFloating();
+    return true;
+  }
+
   /** @returns {void} */
   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();
@@ -288,13 +349,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 +376,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,6 +401,21 @@ 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',
@@ -346,8 +426,31 @@ export class Message extends Component {
       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 +464,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 +479,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 +492,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,6 +520,44 @@ 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);
+  }
+
+  /**
+   * 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}
+   */
+  _disposeFloating() {
+    const region = this.el;
+    this.destroy();
+    region.remove();
   }
 
   /**
@@ -428,23 +571,58 @@ export class Message extends Component {
     return message === key ? fallback : message;
   }
 
-  /** @param {Element|string|null|undefined} scope @returns {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);
-    const existing = this.#floating.get(host);
-    if (existing) return existing;
+    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 = 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);
-    this.#floating.set(host, floating);
-    if (typeof region.showPopover === 'function') region.showPopover();
+    floating._floatingHost = host;
+    // 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) {
+    region._disposeFloating();
+  }
 }
 
 /** @param {unknown} value @returns {MessageKind} */
@@ -460,6 +638,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

@@ -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 { 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
@@ -18,7 +19,7 @@ const FOCUSABLE_SELECTOR = [
  * @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.
@@ -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.
@@ -266,10 +326,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}
@@ -285,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
@@ -347,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();
   }
 
@@ -443,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;
-}