@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/filter-panel/filter-panel.d.ts

@@ -107,6 +107,14 @@ export type FilterPanelOptions = {
      * lower bound takes the start of its day and its upper bound the end, so a one-day range matches.
      */
     serialize?: FilterPanelSerialize;
+    /**
+     * IANA zone the calendar days are counted in, such as the
+     * ZeyOS instance's `Europe/Vienna`. A day serializes as the first (or last) instant of that day
+     * in this zone, and an incoming instant shows as the day it falls on there — the same rule
+     * `zeyosForm()` and `zeyosTable()` apply to date-only fields. Null uses the runtime's own zone.
+     * An unknown zone throws a `RangeError`.
+     */
+    timeZone?: string | null;
     /**
      * Text shown when `fields` is empty; null resolves
      * `filterPanel.empty`.
@@ -175,6 +183,11 @@ export type FilterPanelOptions = {
  *   applies every committed edit.
  * @property {FilterPanelSerialize} [serialize='seconds'] How a date leaves the component. A range's
  *   lower bound takes the start of its day and its upper bound the end, so a one-day range matches.
+ * @property {string|null} [timeZone=null] IANA zone the calendar days are counted in, such as the
+ *   ZeyOS instance's `Europe/Vienna`. A day serializes as the first (or last) instant of that day
+ *   in this zone, and an incoming instant shows as the day it falls on there — the same rule
+ *   `zeyosForm()` and `zeyosTable()` apply to date-only fields. Null uses the runtime's own zone.
+ *   An unknown zone throws a `RangeError`.
  * @property {string|null} [emptyText=null] Text shown when `fields` is empty; null resolves
  *   `filterPanel.empty`.
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
@@ -211,6 +224,7 @@ export declare class FilterPanel extends Component<FilterPanelOptions> {
     _draft: {};
     _applied: {};
     _appliedDraft: string;
+    _timeZone: string;
     _fields: {
         key: string;
         field: FilterPanelField;
@@ -402,23 +416,29 @@ export declare function isActiveValue(value: unknown): boolean;
 export declare function pruneValue(value: Record<string, unknown>): Record<string, unknown>;
 /**
  * Converts anything a calendar day can arrive as — a `YYYY-MM-DD` string, an ISO timestamp, a
- * `Date`, Unix seconds or milliseconds — into the local calendar day a native date input holds.
+ * `Date`, Unix seconds or milliseconds — into the calendar day a native date input holds.
  * Numbers below 1e11 are read as seconds, which is the boundary between the two epochs in use.
+ * An instant — Unix seconds or milliseconds, an ISO timestamp — names the day it falls on in
+ * `timeZone`. A `Date` is read as a picked day and keeps its local calendar day, matching
+ * `calendarDayToUnixSeconds()` in the ZeyOS binding.
  * @param {unknown} value Candidate day.
+ * @param {string|null} [timeZone=null] IANA zone instants are read in; null for the runtime's own.
  * @returns {string} `YYYY-MM-DD`, or an empty string when there is no day in it.
  */
-export declare function toDateInput(value: unknown): string;
+export declare function toDateInput(value: unknown, timeZone?: string | null): string;
 /**
  * Serializes one calendar day at one edge of a range. The `from` edge takes the first instant of
- * its local day and the `to` edge the last, so a range whose ends name the same day still matches
- * everything recorded on it.
+ * its day and the `to` edge the last, so a range whose ends name the same day still matches
+ * everything recorded on it. The day is counted in `timeZone`: with `Europe/Vienna`, 2026-03-10
+ * starts at 23:00 UTC on the 9th whatever zone the browser is in.
  * @param {unknown} day Calendar day in any form `toDateInput()` accepts.
  * @param {FilterPanelEdge} edge Which end of the range the day is.
  * @param {FilterPanelSerialize} [serialize='seconds'] Output format, or a function receiving the
  *   edge instant as a `Date`.
+ * @param {string|null} [timeZone=null] IANA zone the day is counted in; null for the runtime's own.
  * @returns {unknown} The serialized day, or null when there is no day.
  */
-export declare function serializeDate(day: unknown, edge: FilterPanelEdge, serialize?: FilterPanelSerialize): unknown;
+export declare function serializeDate(day: unknown, edge: FilterPanelEdge, serialize?: FilterPanelSerialize, timeZone?: string | null): unknown;
 /**
  * Normalizes declared select options. `{value, label}`, `{ID, name}`, and bare primitives all
  * arrive from one instance or another.
@@ -435,15 +455,24 @@ export declare function normalizeOptions(options: unknown): Array<{
  * Running it on a draft returns the same draft, so it is safe on either shape.
  * @param {Record<string, unknown>|null|undefined} value Incoming values keyed by field.
  * @param {Record<string, FilterPanelField>} fields Field metadata.
+ * @param {string|null} [timeZone=null] IANA zone incoming instants are read in.
  * @returns {Record<string, unknown>}
  */
-export declare function toDraft(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>): Record<string, unknown>;
+export declare function toDraft(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>, timeZone?: string | null): Record<string, unknown>;
 /**
  * Turns values into the query object a list endpoint is sent: only the constraints that are set,
  * dates serialized at the right edge, unknown field types excluded.
  * @param {Record<string, unknown>|null|undefined} value Values keyed by field, raw or drafted.
  * @param {Record<string, FilterPanelField>} fields Field metadata.
  * @param {FilterPanelSerialize} [serialize='seconds'] Date output format.
+ * @param {string|null} [timeZone=null] IANA zone calendar days are counted in.
  * @returns {Record<string, unknown>}
  */
-export declare function serializeFilterValue(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>, serialize?: FilterPanelSerialize): Record<string, unknown>;
+export declare function serializeFilterValue(value: Record<string, unknown> | null | undefined, fields: Record<string, FilterPanelField>, serialize?: FilterPanelSerialize, timeZone?: string | null): Record<string, unknown>;
+/**
+ * Validates the `timeZone` option.
+ * @param {unknown} timeZone IANA zone name; nullish or empty means the runtime's own zone.
+ * @returns {string|null} Canonical zone name, or null for the runtime's own zone.
+ * @throws {RangeError} When the runtime does not know the zone.
+ */
+export declare function normalizePanelTimeZone(timeZone: unknown): string | null;

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

@@ -51,6 +51,12 @@ export type FormOptions = {
      * Native `novalidate` state.
      */
     novalidate?: boolean;
+    /**
+     * Prefix of the DOM ids generated for the fields of the
+     * fieldsets this form builds, as `<idPrefix>-<key>`. Null generates one per form instance, so a
+     * form mounted twice never repeats an id. A fieldset's own `idPrefix` wins.
+     */
+    idPrefix?: string | null;
     /**
      * Submit listener.
      */
@@ -88,6 +94,9 @@ export type FormOptions = {
  * @property {Array<Fieldset|import('../fieldset/fieldset.js').FieldsetOptions>} [fieldsets=[]] Initial fieldsets.
  * @property {FormAction[]} [actions=[]] Form action descriptors.
  * @property {boolean} [novalidate=true] Native `novalidate` state.
+ * @property {string|null} [idPrefix=null] Prefix of the DOM ids generated for the fields of the
+ *   fieldsets this form builds, as `<idPrefix>-<key>`. Null generates one per form instance, so a
+ *   form mounted twice never repeats an id. A fieldset's own `idPrefix` wins.
  * @property {(event: CustomEvent<{values: Record<string, unknown>}>) => void} [onsubmit] Submit listener.
  * @property {(event: CustomEvent<{errors: Record<string, string>}>) => void} [oninvalid] Invalid listener.
  * @property {(event: CustomEvent<{id: string, value: unknown}>) => void} [onchange] Field change listener.
@@ -104,6 +113,7 @@ export declare class Form extends Component<FormOptions> {
     _ownedFieldsets: Set<any>;
     _origins: Map<any, any>;
     _ownedNodes: any[];
+    _idPrefix: string;
     _novalidateAttribute: string;
     _body: HTMLElement;
     _actions: HTMLElement;
@@ -126,7 +136,8 @@ export declare class Form extends Component<FormOptions> {
     /** @returns {HTMLElement} */
     render(): HTMLElement;
     /**
-     * Adds an existing fieldset or constructs one from options.
+     * Adds an existing fieldset or constructs one from options. A constructed fieldset generates its
+     * field ids from the form's `idPrefix` unless its options carry their own.
      * @param {Fieldset|import('../fieldset/fieldset.js').FieldsetOptions} fieldset Fieldset source.
      * @returns {Fieldset}
      */

package/dist/types/components/kanban-view/kanban-card.d.ts

@@ -52,6 +52,12 @@ export type KanbanAssignee = {
      * Fallback initials.
      */
     initials: string;
+    /**
+     * Fallback tint: a descriptor's own
+     * `tone` when it names one of `AVATAR_TONES`, otherwise `avatarTone(name)` — the colour the same
+     * person has in every Avatar.
+     */
+    tone: import('../avatar/avatar.js').AvatarTone;
 };
 /**
  * Normalizes one indicator value into the descriptor the badge is built from. A plain value
@@ -88,6 +94,8 @@ export declare function createKanbanProgress(progress: KanbanProgress, label: st
 /**
  * Normalizes one or more responsible people. Names, name lists, and descriptor objects all
  * resolve to the same shape, and an unsafe image URL degrades to initials rather than failing.
+ * A descriptor may name its `tone`; otherwise the tone is derived from the name exactly as Avatar
+ * derives it.
  * @param {unknown} value Raw field value.
  * @returns {KanbanAssignee[]} Normalized people, in the order supplied.
  */

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 = {
     /**
@@ -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
@@ -247,20 +356,40 @@ export type RankedLauncherItem = LauncherItem & {
  * @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
@@ -268,6 +397,8 @@ export type RankedLauncherItem = LauncherItem & {
  */
 export declare class Launcher extends Component<LauncherOptions> {
     _createdRoot: boolean;
+    /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} Entry on the overlay stack while open. */
+    _overlay: import('../../core/overlay-stack.js').OverlayHandle | null;
     _original: {
         attributes: string[][];
         children: ChildNode[];
@@ -283,7 +414,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 +434,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 +464,86 @@ 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;
+    /**
+     * Takes the launcher off the overlay stack. Safe to call repeatedly.
+     * @returns {void}
+     * @private
+     */
+    private _releaseOverlay;
     /** 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,6 +558,14 @@ 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} */
@@ -345,10 +576,31 @@ export declare class Launcher extends Component<LauncherOptions> {
      * 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): 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.
@@ -366,6 +618,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>} */

package/dist/types/components/list-toolbar/list-toolbar.d.ts

@@ -193,7 +193,7 @@ export type ListToolbarOptions = {
  *   control, rather than found separately beside it.
  * - **The count line is a live region**, and `setCount(null)` clears it. The previous number
  *   describes the previous filters, and a stale count during a load is worse than none.
- * - **Tool buttons meet the 44 px target** in both densities. An icon button sized to its glyph is
+ * - **Tool buttons meet the 44 px target** at any spacing. An icon button sized to its glyph is
  *   the control people miss twice before hitting once.
  *
  * `bind()` is optional sugar; the toolbar is fully functional without it.
@@ -341,8 +341,10 @@ export declare class ListToolbar extends Component<ListToolbarOptions> {
      */
     focusSearch(): this;
     /**
-     * Optional sugar for a `TableView` or `CardView`: it wires the shape switch to the view and
-     * mounts the view's field chooser into this bar.
+     * Optional sugar for a `TableView`, `CardView`, or `KanbanView`: it wires the shape switch to
+     * the view and mounts the view's field chooser into this bar — through the view's public
+     * `mountFieldControls()` when it has one, which every `RecordView` does. A `TableView` with the
+     * default `fieldControls: true` contributes its Table's column chooser.
      *
      * Nothing is imported and nothing is required — every capability is feature-detected, so a view
      * that offers none of them still works and still gets `viewchange`, and the host swaps the view
@@ -410,7 +412,8 @@ export declare class ListToolbar extends Component<ListToolbarOptions> {
      */
     _mountFieldControls(view: Record<string, any>): void;
     /**
-     * Finds a view's field chooser without importing the view, newest accessor first.
+     * Finds a view's field chooser without importing the view: its public `getFieldControls()`,
+     * else — for an object that only looks like a record view — the shared chooser's class.
      * @param {Record<string, any>} view Bound view.
      * @returns {Element|null}
      */
@@ -470,6 +473,7 @@ export type AdoptedElement = {
     element: Element;
     parent: Node | null;
     next: Node | null;
+    viaView?: boolean;
 };
 export type RecordViewCapabilities = {
     /**
@@ -489,7 +493,8 @@ export type RecordViewCapabilities = {
      */
     events: boolean;
     /**
-     * Whether the object offers its field chooser through a method.
+     * Whether the object offers its field chooser through a method
+     * (`getFieldControls()`, which every `RecordView` has).
      */
     fieldControls: boolean;
 };
@@ -521,14 +526,18 @@ export type RecordViewCapabilities = {
  * @property {boolean} pressed Current pressed state.
  * @property {((event: MouseEvent) => void)|null} onclick Descriptor callback.
  */
-/** @typedef {{element: Element, parent: Node|null, next: Node|null}} AdoptedElement */
+/**
+ * @typedef {{element: Element, parent: Node|null, next: Node|null, viaView?: boolean}} AdoptedElement
+ * `viaView` marks a field chooser the bound view moved here itself and takes back on `unbind()`.
+ */
 /**
  * @typedef {Object} RecordViewCapabilities
  * @property {boolean} isRecordView Whether the object publishes the record-view state surface.
  * @property {string|null} setShape Method that changes the view shape, if any.
  * @property {string|null} getShape Method that reads the view shape, if any.
  * @property {boolean} events Whether the object emits component events.
- * @property {boolean} fieldControls Whether the object offers its field chooser through a method.
+ * @property {boolean} fieldControls Whether the object offers its field chooser through a method
+ *   (`getFieldControls()`, which every `RecordView` has).
  */
 /**
  * Describes what `bind()` can wire on an object, by feature rather than by class.