@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/menu-button/menu-button.d.ts

@@ -38,6 +38,14 @@ export type MenuButtonOptions = {
      */
     onclose?: (event: CustomEvent<Record<string, never>>) => void;
 };
+export type MenuButtonOpenOptions = {
+    /**
+     * Where focus goes when this opening ends with a
+     * selection or Escape: `true` is the trigger, an element is that element (the trigger again if
+     * it has left the document), and `false` leaves focus alone.
+     */
+    returnFocus?: boolean | HTMLElement;
+};
 /** @typedef {import('../../internal/menu-items.js').MenuItem} MenuItem */
 /** @typedef {import('../../internal/menu-items.js').MenuEntry} MenuButtonItem */
 /**
@@ -51,8 +59,18 @@ export type MenuButtonOptions = {
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
  */
+/**
+ * @typedef {Object} MenuButtonOpenOptions
+ * @property {boolean|HTMLElement} [returnFocus=true] Where focus goes when this opening ends with a
+ *   selection or Escape: `true` is the trigger, an element is that element (the trigger again if
+ *   it has left the document), and `false` leaves focus alone.
+ */
 /**
  * APG menu-button trigger backed by an anchored Dropdown.
+ *
+ * Choosing an item closes the menu and puts focus back on the trigger before the `select` event
+ * and the item's `onselect` run, so whatever they open — a dialog, a sheet — records the trigger
+ * as the place to return to, and focus they move themselves stays where they put it.
  * @fires MenuButton#select
  * @fires MenuButton#open
  * @fires MenuButton#close
@@ -82,14 +100,22 @@ export declare class MenuButton extends Component<MenuButtonOptions> {
     setItems(items: MenuButtonItem[]): this;
     /**
      * Opens the menu.
+     * @param {MenuButtonOpenOptions} [options={}] Where focus returns when this opening ends; ignored
+     *   while the menu is already open.
      * @returns {this}
      */
-    open(): this;
+    open(options?: MenuButtonOpenOptions): this;
     /**
      * Closes the menu.
      * @returns {this}
      */
     close(): 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(): this;
     /**
      * Reports whether the menu is open.
      * @returns {boolean}
@@ -99,10 +125,18 @@ export declare class MenuButton extends Component<MenuButtonOptions> {
     getTrigger(): HTMLElement;
     /** Returns the owned menu panel. @returns {HTMLElement} */
     getPanel(): HTMLElement;
-    /** Opens the menu and focuses its first enabled item. @returns {this} */
-    focusFirst(): this;
-    /** Opens the menu and focuses its last enabled item. @returns {this} */
-    focusLast(): this;
+    /**
+     * Opens the menu and focuses its first enabled item.
+     * @param {MenuButtonOpenOptions} [options={}] Passed to `open()`.
+     * @returns {this}
+     */
+    focusFirst(options?: MenuButtonOpenOptions): this;
+    /**
+     * Opens the menu and focuses its last enabled item.
+     * @param {MenuButtonOpenOptions} [options={}] Passed to `open()`.
+     * @returns {this}
+     */
+    focusLast(options?: MenuButtonOpenOptions): this;
     /**
      * Sets the visible trigger label.
      * @param {string} label Trigger label.

package/dist/types/components/message/message.d.ts

@@ -1,18 +1,48 @@
 import { Component } from '../../core/component.js';
 export type MessageKind = 'info' | 'success' | 'warning' | 'error';
+export type MessageAction = {
+    /**
+     * Button text: a verb naming what happens ("Undo", "Approve", "Retry").
+     */
+    label: string;
+    /**
+     * Runs when the button is activated, by pointer
+     * or keyboard; the message closes right after it.
+     */
+    onclick?: (event: MouseEvent) => void;
+    /**
+     * Button kind; the default is the
+     * secondary button.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+};
 export type MessageShowOptions = {
     /**
      * Message intent (`danger` aliases `error`).
      */
     kind?: MessageKind | 'danger';
     /**
-     * Auto-dismiss delay in milliseconds; zero persists.
+     * Auto-dismiss delay in milliseconds; zero persists. A message
+     * with an `action` stays at least 8000ms.
      */
     timeout?: number;
     /**
      * Whether to render a close button.
      */
     closable?: boolean;
+    /**
+     * A command button inside the message. The message
+     * never times out while the pointer is over it or focus is inside it.
+     */
+    action?: MessageAction | 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.
+     */
+    leading?: Node | {
+        toElement: () => Node | null;
+    } | null;
     /**
      * Element whose nearest Zx theme scope owns a floating toast.
      */
@@ -37,28 +67,32 @@ export type MessageOptions = {
     maxVisible?: number;
 };
 export type MessageHandle = {
-    close: () => void;
-};
-export type ProgressHandle = {
     /**
-     * Updates progress and optional text.
-     */
-    update: (pct: number, text?: string) => void;
-    /**
-     * Completes and dismisses the progress message.
-     */
-    done: () => void;
-    /**
-     * Marks progress as failed and dismisses it later.
+     * Closes the message.
      */
-    fail: (text?: string) => void;
+    close: () => void;
 };
 /** @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.
  */
 /**
@@ -68,7 +102,28 @@ export type ProgressHandle = {
  * @property {boolean} [closable=true] Default close-button visibility.
  * @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 declare const MESSAGE_ACTION_MIN_TIMEOUT = 8000;
+export type ProgressHandle = {
+    /**
+     * Updates progress and optional text.
+     */
+    update: (pct: number, text?: string) => void;
+    /**
+     * Completes and dismisses the progress message.
+     */
+    done: () => void;
+    /**
+     * Marks progress as failed and dismisses it later.
+     */
+    fail: (text?: string) => void;
+};
 /**
  * @typedef {Object} ProgressHandle
  * @property {(pct: number, text?: string) => void} update Updates progress and optional text.
@@ -129,6 +184,14 @@ export declare class Message extends Component<MessageOptions> {
         children: Node[];
     };
     _entries: Set<any>;
+    /** @type {Element|null} The theme scope this instance is the floating region of; null when inline. */
+    _floatingHost: Element | null;
+    /** @type {Element|null} Where the floating region was last put: its scope, or the topmost modal. */
+    _placedIn: Element | null;
+    /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} The region's toast entry. */
+    _overlay: import('../../core/overlay-stack.js').OverlayHandle | null;
+    /** @type {(() => void)|null} Stops following the overlay stack. */
+    _unfollow: (() => void) | null;
     _queue: MessageQueue<any>;
     _cleaned: boolean;
     static cssName: string;
@@ -187,13 +250,24 @@ export declare class Message extends Component<MessageOptions> {
     static progress(text: string, options?: {
         scope?: Element | string | null;
     }): ProgressHandle;
+    /**
+     * 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: Element | string): boolean;
     /** @returns {void} */
     destroy(): void;
     /** @param {string} text @returns {ProgressHandle} */
     _progress(text: string): ProgressHandle;
     /**
      * @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}
      */
@@ -201,6 +275,8 @@ export declare class Message extends Component<MessageOptions> {
         kind: MessageKind;
         timeout: number;
         closable: boolean;
+        action?: MessageAction | null;
+        leading?: Node | null;
     }, progress?: {
         pct: number;
         text: string;
@@ -217,6 +293,24 @@ export declare class Message extends Component<MessageOptions> {
     _close(entry: any): void;
     /** @param {any} entry @returns {void} */
     _finish(entry: any): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * Destroys a floating region and removes its element.
+     * @returns {void}
+     */
+    _disposeFloating(): void;
     /**
      * Resolves a message through the host translator, falling back to the built-in English text.
      * @param {string} key Message key.
@@ -225,3 +319,24 @@ export declare class Message extends Component<MessageOptions> {
      */
     _message(key: string, fallback: string): string;
 }
+/**
+ * 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 declare function messageTimeout(timeout: unknown, hasAction?: boolean): number;
+/**
+ * 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 declare function normalizeMessageAction(value: unknown): {
+    label: string;
+    kind: 'default' | 'primary' | 'danger' | 'ghost';
+    onclick: ((event: MouseEvent) => void) | null;
+} | null;

package/dist/types/components/modal/modal.d.ts

@@ -23,7 +23,7 @@ export type ModalOptions = {
      */
     destroyOnClose?: boolean;
     /**
-     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+     * 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.
      */
     scope?: Element | string | null;
     /**
@@ -48,7 +48,7 @@ export type ModalOptions = {
  * @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.
@@ -110,6 +110,36 @@ export declare class Modal extends Component<ModalOptions> {
      * @returns {void}
      */
     _present(): void;
+    /**
+     * 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
+     */
+    protected _overlayEntry(): import('../../core/overlay-stack.js').OverlayEntryOptions | null;
+    /**
+     * 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
+     */
+    protected _syncOverlay(): void;
+    /**
+     * Takes the overlay off the stack. Safe to call repeatedly.
+     * @returns {void}
+     * @protected
+     */
+    protected _releaseOverlay(): void;
+    /**
+     * 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
+     */
+    protected _overlayContains(node: Node | null | undefined): boolean;
     /**
      * Hides the current presentation and records which generation its queued close event belongs to.
      * @param {string} [result=''] Native string return value.
@@ -154,6 +184,17 @@ export declare class Modal extends Component<ModalOptions> {
      * @returns {HTMLDialogElement}
      */
     render(): HTMLDialogElement;
+    /**
+     * 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: HTMLDialogElement): void;
     /**
      * Opens the modal in the browser top layer.
      * @returns {this}