@zeyos/zx 4.3.4 → 5.0.0

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

@@ -28,6 +28,23 @@ export type LauncherItem = {
      * Compact metadata.
      */
     badge?: string | number;
+    /**
+     * Muted text at the end of the row, such as a current value or a project.
+     */
+    hint?: string | number;
+    /**
+     * Key labels drawn as
+     * key caps (`['⌘', 'K']`), or Button's `{label, keys}` shape. Display only: the Launcher binds nothing.
+     */
+    shortcut?: string | string[] | {
+        label: string | string[];
+        keys?: string;
+    };
+    /**
+     * The same shortcut in `aria-keyshortcuts` syntax (`'Meta+K'`), exposed on
+     * the option for assistive technology.
+     */
+    keys?: string;
     /**
      * Tile or row presentation.
      */
@@ -72,6 +89,40 @@ export type LauncherItem = {
      * Whether activation is unavailable.
      */
     disabled?: boolean;
+    /**
+     * Child items. An item with `items` opens them
+     * as a page instead of being selected: an array, or a loader called with the page's query.
+     */
+    items?: LauncherItem[] | LauncherPageLoader;
+    /**
+     * Search-field placeholder while this item's page is open.
+     */
+    placeholder?: string;
+    /**
+     * For a page whose `items` is a loader: whether Zx ranks
+     * the loaded items by the query, or keeps the loader's order.
+     */
+    order?: 'rank' | 'source';
+};
+export type LauncherPageLoader = (query: string, context: {
+    signal: AbortSignal;
+}) => LauncherItem[] | Promise<LauncherItem[]>;
+export type LauncherOpenOptions = {
+    /**
+     * Opens straight into a page: the id of a local item
+     * with `items` (at any depth of array pages, whose path becomes the back stack), or a page item.
+     */
+    page?: string | number | LauncherItem;
+};
+export type LauncherPageDetail = {
+    /**
+     * The page now shown; null on the root.
+     */
+    page: LauncherItem | null;
+    /**
+     * Every open page from the root down, the shown one last.
+     */
+    path: LauncherItem[];
 };
 export type LauncherSource = {
     /**
@@ -127,27 +178,27 @@ export type LauncherOptions = {
      */
     maxResults?: number;
     /**
-     * Search-field placeholder.
+     * Search-field placeholder. Omitted resolves `launcher.placeholder`, English `Search applications and records`.
      */
     placeholder?: string;
     /**
-     * Dialog and field label.
+     * Dialog and field label. Omitted resolves `launcher.label`, English `Launcher`.
      */
     label?: string;
     /**
-     * Close-button accessible label.
+     * Close-button accessible label. Omitted resolves `launcher.close`, English `Close launcher`.
      */
     closeLabel?: string;
     /**
-     * Results-region accessible label.
+     * Results-region accessible label. Omitted resolves `launcher.results`, English `Launcher results`.
      */
     resultsLabel?: string;
     /**
-     * Empty-state text.
+     * Empty-state text. Omitted resolves `launcher.empty`, English `No results`.
      */
     emptyText?: string;
     /**
-     * Loading-state text.
+     * Loading-state text. Omitted resolves `launcher.loading`, English `Searching…`.
      */
     loadingText?: string;
     /**
@@ -160,6 +211,7 @@ export type LauncherOptions = {
     hints?: false | {
         move?: string;
         open?: string;
+        back?: string;
         close?: string;
     };
     /**
@@ -176,6 +228,10 @@ export type LauncherOptions = {
     onquery?: (event: CustomEvent<{
         query: string;
     }>) => void;
+    /**
+     * Page-navigation listener.
+     */
+    onpage?: (event: CustomEvent<LauncherPageDetail>) => void;
     /**
      * Open listener.
      */
@@ -187,21 +243,49 @@ export type LauncherOptions = {
     /**
      * Source error listener.
      */
-    onerror?: (event: CustomEvent<{
-        source: LauncherSource;
-        error: unknown;
-    }>) => void;
+    onerror?: (event: CustomEvent<LauncherErrorDetail>) => void;
 };
 export type LauncherSelectDetail = {
     item: LauncherItem;
     value: unknown;
     source: string | null;
     query: string;
+    page: LauncherItem | null;
+};
+export type LauncherErrorDetail = {
+    source: LauncherSource;
+    error: unknown;
+    page: LauncherItem | null;
 };
 export type RankedLauncherItem = LauncherItem & {
     _source?: string | null;
     _score?: number;
 };
+export type LevelSource = LauncherSource & {
+    _page?: boolean;
+};
+export type LauncherPageEntry = {
+    /**
+     * The page item.
+     */
+    page: LauncherItem;
+    /**
+     * Its normalized local items (an array page).
+     */
+    items: LauncherItem[];
+    /**
+     * Its loader as a source (a loader page).
+     */
+    sources: LevelSource[];
+    /**
+     *   The level beneath: its query, its highlighted option, and its loaded results when they were complete.
+     */
+    parent: {
+        query: string;
+        activeId: string | null;
+        sourceItems: Map<string, RankedLauncherItem[]> | null;
+    };
+};
 /**
  * @typedef {Object} LauncherItem
  * @property {string|number} id Stable item identifier.
@@ -211,6 +295,11 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {string} [group] Result group.
  * @property {string|Node|((item: LauncherItem) => Node|null)} [icon] Decorative icon name, node, or factory.
  * @property {string|number} [badge] Compact metadata.
+ * @property {string|number} [hint] Muted text at the end of the row, such as a current value or a project.
+ * @property {string|string[]|{label: string|string[], keys?: string}} [shortcut] Key labels drawn as
+ *   key caps (`['⌘', 'K']`), or Button's `{label, keys}` shape. Display only: the Launcher binds nothing.
+ * @property {string} [keys] The same shortcut in `aria-keyshortcuts` syntax (`'Meta+K'`), exposed on
+ *   the option for assistive technology.
  * @property {'application'|'record'|'action'} [kind='action'] Tile or row presentation.
  * @property {boolean} [current=false] Whether this is the current application or destination.
  * @property {'always'|'empty'|'query'} [when='always'] Query state in which the item is visible.
@@ -222,6 +311,26 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {() => void} [invoke] Application-owned callback for non-link actions.
  * @property {boolean|number} [pinned] Pinned state or explicit pinned order.
  * @property {boolean} [disabled] Whether activation is unavailable.
+ * @property {LauncherItem[]|LauncherPageLoader} [items] Child items. An item with `items` opens them
+ *   as a page instead of being selected: an array, or a loader called with the page's query.
+ * @property {string} [placeholder] Search-field placeholder while this item's page is open.
+ * @property {'rank'|'source'} [order='rank'] For a page whose `items` is a loader: whether Zx ranks
+ *   the loaded items by the query, or keeps the loader's order.
+ */
+/**
+ * Loads a page's items for its current query. It runs when the page opens and again, debounced, as
+ * the query changes; a newer query aborts `signal`.
+ * @typedef {(query: string, context: {signal: AbortSignal}) => LauncherItem[]|Promise<LauncherItem[]>} LauncherPageLoader
+ */
+/**
+ * @typedef {Object} LauncherOpenOptions
+ * @property {string|number|LauncherItem} [page] Opens straight into a page: the id of a local item
+ *   with `items` (at any depth of array pages, whose path becomes the back stack), or a page item.
+ */
+/**
+ * @typedef {Object} LauncherPageDetail
+ * @property {LauncherItem|null} page The page now shown; null on the root.
+ * @property {LauncherItem[]} path Every open page from the root down, the shown one last.
  */
 /**
  * @typedef {Object} LauncherSource
@@ -240,27 +349,47 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {number} [debounce=250] Source-query delay in milliseconds.
  * @property {number} [minQuery=0] Global source minimum query length.
  * @property {number} [maxResults=100] Maximum combined results.
- * @property {string} [placeholder='Search applications and records'] Search-field placeholder.
- * @property {string} [label='Launcher'] Dialog and field label.
- * @property {string} [closeLabel='Close launcher'] Close-button accessible label.
- * @property {string} [resultsLabel='Launcher results'] Results-region accessible label.
- * @property {string} [emptyText='No results'] Empty-state text.
- * @property {string} [loadingText='Searching…'] Loading-state text.
+ * @property {string} [placeholder] Search-field placeholder. Omitted resolves `launcher.placeholder`, English `Search applications and records`.
+ * @property {string} [label] Dialog and field label. Omitted resolves `launcher.label`, English `Launcher`.
+ * @property {string} [closeLabel] Close-button accessible label. Omitted resolves `launcher.close`, English `Close launcher`.
+ * @property {string} [resultsLabel] Results-region accessible label. Omitted resolves `launcher.results`, English `Launcher results`.
+ * @property {string} [emptyText] Empty-state text. Omitted resolves `launcher.empty`, English `No results`.
+ * @property {string} [loadingText] Loading-state text. Omitted resolves `launcher.loading`, English `Searching…`.
  * @property {'mod+k'|false} [shortcut='mod+k'] Optional global keyboard shortcut.
- * @property {false|{move?: string, open?: string, close?: string}} [hints] Visible keyboard hints, or false.
+ * @property {false|{move?: string, open?: string, back?: string, close?: string}} [hints] Visible keyboard hints, or false.
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns an internally created launcher; defaults to the opener.
  * @property {(event: CustomEvent<LauncherSelectDetail>) => void} [onselect] Preventable selection listener.
  * @property {(event: CustomEvent<{query: string}>) => void} [onquery] Query-change listener.
+ * @property {(event: CustomEvent<LauncherPageDetail>) => void} [onpage] Page-navigation listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
- * @property {(event: CustomEvent<{source: LauncherSource, error: unknown}>) => void} [onerror] Source error listener.
+ * @property {(event: CustomEvent<LauncherErrorDetail>) => void} [onerror] Source error listener.
+ */
+/**
+ * A selection. `page` is the page the item was chosen on, null on the root.
+ * @typedef {{item: LauncherItem, value: unknown, source: string|null, query: string, page: LauncherItem|null}} LauncherSelectDetail
+ */
+/**
+ * A failed load. A page loader reports as a source whose id is `page:<page id>`, with `page` set.
+ * @typedef {{source: LauncherSource, error: unknown, page: LauncherItem|null}} LauncherErrorDetail
  */
-/** @typedef {{item: LauncherItem, value: unknown, source: string|null, query: string}} LauncherSelectDetail */
 /** @typedef {LauncherItem & {_source?: string|null, _score?: number}} RankedLauncherItem */
+/** @typedef {LauncherSource & {_page?: boolean}} LevelSource */
+/**
+ * One open page and the level beneath it, kept so going back restores that level as it was.
+ * @typedef {Object} LauncherPageEntry
+ * @property {LauncherItem} page The page item.
+ * @property {LauncherItem[]} items Its normalized local items (an array page).
+ * @property {LevelSource[]} sources Its loader as a source (a loader page).
+ * @property {{query: string, activeId: string|null, sourceItems: Map<string, RankedLauncherItem[]>|null}} parent
+ *   The level beneath: its query, its highlighted option, and its loaded results when they were complete.
+ */
 /**
  * Abortable command/search dialog that emits application-owned actions without routing itself.
+ * Items with `items` open nested pages: an APG combobox whose listbox shows one page at a time.
  * @fires Launcher#select
  * @fires Launcher#query
+ * @fires Launcher#page
  * @fires Launcher#open
  * @fires Launcher#close
  * @fires Launcher#error
@@ -283,7 +412,15 @@ export declare class Launcher extends Component<LauncherOptions> {
     _requestSequence: number;
     _queryTimer: number;
     _busy: boolean;
+    _settled: boolean;
+    /** @type {LauncherPageEntry[]} */
+    _pages: LauncherPageEntry[];
+    _restoreActiveId: string;
+    _announcePending: boolean;
+    _announceToggle: boolean;
     _destroyed: boolean;
+    _label: string;
+    _placeholder: string;
     static cssName: string;
     /** @type {Readonly<LauncherOptions>} */
     static defaults: Readonly<LauncherOptions>;
@@ -295,8 +432,24 @@ export declare class Launcher extends Component<LauncherOptions> {
     constructor(target?: HTMLDialogElement | string | null, options?: LauncherOptions);
     /** @returns {HTMLDialogElement} */
     render(): HTMLDialogElement;
-    /** Opens the launcher and focuses/selects its query. @returns {this} @fires Launcher#open */
-    open(): this;
+    /**
+     * Opens the launcher and focuses/selects its query. It opens on the root unless `page` names one;
+     * already open, `page` navigates there.
+     * @param {LauncherOpenOptions} [options={}] Open options.
+     * @returns {this}
+     * @fires Launcher#open
+     * @fires Launcher#page
+     */
+    open(options?: LauncherOpenOptions): this;
+    /**
+     * Goes back one page, restoring the level beneath with its query and highlighted option. Does
+     * nothing on the root.
+     * @returns {this}
+     * @fires Launcher#page
+     */
+    back(): this;
+    /** Returns the page shown, or null on the root. @returns {LauncherItem|null} */
+    getPage(): LauncherItem | null;
     /** Closes the launcher. @returns {this} */
     close(): this;
     /** Toggles the launcher. @returns {this} */
@@ -309,18 +462,80 @@ export declare class Launcher extends Component<LauncherOptions> {
     setQuery(query: string): this;
     /** Returns the untrimmed query. @returns {string} */
     getQuery(): string;
-    /** Replaces local catalogue items. @param {LauncherItem[]} items @returns {this} */
+    /** Replaces the root's local catalogue items; an open page keeps its own. @param {LauncherItem[]} items @returns {this} */
     setItems(items: LauncherItem[]): this;
     /** Marks one local item as the current destination. @param {string|number|null} id Item id. @returns {this} */
     setCurrent(id: string | number | null): this;
-    /** Replaces asynchronous sources and aborts work from the old set. @param {LauncherSource[]} sources @returns {this} */
+    /** Replaces the root's asynchronous sources and aborts work from the old set; on a page they load once the root is back. @param {LauncherSource[]} sources @returns {this} */
     setSources(sources: LauncherSource[]): this;
     /** Aborts sources and removes the owned dialog. @returns {void} */
     destroy(): void;
-    /** @returns {void} */
-    _refresh(): void;
+    /**
+     * Re-renders the current level and reloads its sources: debounced while typing, at once when a
+     * page opens (so its loading state shows instead of a passing "No results").
+     * @param {boolean} [immediate=false] Load without the debounce.
+     * @returns {void}
+     */
+    _refresh(immediate?: boolean): void;
     /** @returns {Promise<void>} */
     _loadSources(): Promise<void>;
+    /**
+     * The level on screen: the root's items and sources, or the open page's.
+     * @returns {{items: LauncherItem[], sources: LevelSource[]}}
+     */
+    _level(): {
+        items: LauncherItem[];
+        sources: LevelSource[];
+    };
+    /**
+     * Opens a page on top of the current level: what the user activated, or ArrowRight on its row.
+     * @param {LauncherItem} item Page item.
+     * @returns {void}
+     */
+    _openPage(item: LauncherItem): void;
+    /**
+     * Replaces the whole stack with `path` (empty for the root) and refreshes what it lands on.
+     * @param {LauncherItem[]} path Pages from the root down.
+     * @param {{emit?: boolean}} [options={}] Whether to report a change through `page`.
+     * @returns {void}
+     */
+    _goTo(path: LauncherItem[], { emit }?: {
+        emit?: boolean;
+    }): void;
+    /** Pops every page, restoring the root's query, without rendering. @returns {void} */
+    _unwind(): void;
+    /**
+     * Pushes a page, remembering the level beneath, and clears the query for it.
+     * @param {LauncherItem} item Page item.
+     * @returns {void}
+     */
+    _pushPage(item: LauncherItem): void;
+    /**
+     * Pops the top page and restores the level beneath.
+     * @returns {boolean} Whether that level's results came back complete (no reload needed).
+     */
+    _popPage(): boolean;
+    /** @param {string} query @returns {void} */
+    _setInputQuery(query: string): void;
+    /**
+     * Shows the open page in the search row: the chip, the combobox name and placeholder, and the
+     * footer's Back hint.
+     * @returns {void}
+     */
+    _syncPage(): void;
+    /** @returns {void} @fires Launcher#page */
+    _emitPage(): void;
+    /**
+     * Resolves `open({ page })`: a page item as given, or the path to a local page by id.
+     * @param {string|number|LauncherItem} target Page id or item.
+     * @returns {LauncherItem[]}
+     */
+    _pagePath(target: string | number | LauncherItem): LauncherItem[];
+    /**
+     * The polite line a page change ends on: where the user is and how much is there.
+     * @returns {string}
+     */
+    _pageStatus(): string;
     /** @param {boolean} busy @returns {void} */
     _setBusy(busy: boolean): void;
     /** @returns {void} */
@@ -335,13 +550,49 @@ export declare class Launcher extends Component<LauncherOptions> {
     _syncActive(): void;
     /** @param {KeyboardEvent} event @returns {void} */
     _onKeydown(event: KeyboardEvent): void;
+    /**
+     * ArrowRight on a page row opens it once the caret is at the end of the query (before that it
+     * moves the caret); ArrowLeft on an empty query goes back. Application tiles keep both arrows
+     * for moving through their grid, which the caller tries first.
+     * @param {string} key ArrowLeft or ArrowRight.
+     * @returns {boolean} Whether the key navigated.
+     */
+    _pageKey(key: string): boolean;
     /** @param {string} direction @param {number[]} enabled @returns {number|null} */
     _spatialIndex(direction: string, enabled: number[]): number | null;
     /** @param {number} index @param {Event} event @returns {void} */
     _activate(index: number, event: Event): void;
     /** @param {KeyboardEvent} event @returns {void} */
     _onDocumentKeydown(event: KeyboardEvent): void;
+    /**
+     * 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.
+     * @param {...unknown} args Positional `%1`, `%2` values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
 }
+/**
+ * Whether an item opens a page rather than being selected.
+ * @param {unknown} item Candidate item.
+ * @returns {boolean}
+ */
+export declare function isLauncherPage(item: unknown): boolean;
+/**
+ * Finds a page among local items by id, descending through array pages (a loader's items are not
+ * known until it runs).
+ * @param {LauncherItem[]} items Root items.
+ * @param {string|number} id Page item id.
+ * @returns {LauncherItem[]} The pages from the root down to the match, or an empty array.
+ */
+export declare function findLauncherPage(items: LauncherItem[], id: string | number): LauncherItem[];
+/**
+ * Normalizes an item's `shortcut` into the key labels drawn as caps.
+ * @param {unknown} shortcut `['⌘', 'K']`, one label, or `{label, keys}`.
+ * @returns {string[]}
+ */
+export declare function launcherShortcutCaps(shortcut: unknown): string[];
 /**
  * Ranks launcher items using the current ZeyOS application tiers.
  * @param {RankedLauncherItem[]} items Items to rank.
@@ -359,6 +610,7 @@ export declare function rankLauncherItems(items: RankedLauncherItem[], query: st
 export declare function orderedLauncherSourceItems(sources: LauncherSource[], sourceItems: Map<string, RankedLauncherItem[]>): RankedLauncherItem[];
 /** Fired when a result is activated. @event Launcher#select @type {CustomEvent<LauncherSelectDetail>} */
 /** Fired when the query changes. @event Launcher#query @type {CustomEvent<{query: string}>} */
+/** Fired after a page opens or closes, or `open()` lands on a different page. @event Launcher#page @type {CustomEvent<LauncherPageDetail>} */
 /** Fired after the dialog opens. @event Launcher#open @type {CustomEvent<Record<string, never>>} */
 /** Fired after the dialog closes. @event Launcher#close @type {CustomEvent<Record<string, never>>} */
-/** Fired when one asynchronous source fails. @event Launcher#error @type {CustomEvent<{source: LauncherSource, error: unknown}>} */
+/** Fired when one asynchronous source or page loader fails. @event Launcher#error @type {CustomEvent<LauncherErrorDetail>} */