@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/workspace-switcher/workspace-switcher.d.ts

@@ -0,0 +1,327 @@
+import { Component } from '../../core/component.js';
+import { MenuButton } from '../menu-button/menu-button.js';
+export type MenuButtonItem = import('../menu-button/menu-button.js').MenuButtonItem;
+export type AppIconTone = import('../app-icon/app-icon.js').AppIconTone;
+export type WorkspaceItem = {
+    /**
+     * Stable identifier; the `active` option and `setActive()` name it.
+     */
+    id: string | number;
+    /**
+     * Workspace name.
+     */
+    label: string;
+    /**
+     * Secondary line: plan, role, domain.
+     */
+    secondary?: string;
+    /**
+     * Icon name or node drawn on the tile instead of the initial. A node
+     * is cloned for each place the tile appears.
+     */
+    icon?: string | Node;
+    /**
+     * Tile colour from the theme's categorical palette. Without `tone`
+     * or `color` the tone is derived from the label, so a workspace keeps its colour everywhere.
+     */
+    tone?: AppIconTone;
+    /**
+     * Tile colour, any CSS colour; takes precedence over `tone`.
+     */
+    color?: string;
+    /**
+     * Image drawn as the tile instead of the initial or icon.
+     */
+    src?: string | null;
+    /**
+     * Explicit tile initials; derived from the label when omitted.
+     */
+    initials?: string;
+    /**
+     * Compact trailing metadata in the menu, such as an unread count.
+     */
+    badge?: string | number;
+    /**
+     * Whether the workspace is listed but cannot be chosen.
+     */
+    disabled?: boolean;
+};
+export type WorkspaceSwitcherSelectDetail = {
+    /**
+     * The workspace being switched to.
+     */
+    workspace: WorkspaceItem;
+    /**
+     * Its id.
+     */
+    id: string | number;
+    /**
+     * The workspace active until now.
+     */
+    previous: WorkspaceItem | null;
+};
+export type WorkspaceSwitcherOptions = {
+    /**
+     * Workspaces in menu order. Entries without an id are
+     * skipped, and a repeated id keeps its first entry.
+     */
+    workspaces?: WorkspaceItem[];
+    /**
+     * Active workspace id. Defaults to the first enabled
+     * workspace, which also stands in for an id that is not listed or is disabled.
+     */
+    active?: string | number | null;
+    /**
+     * Extra actions listed after the workspaces — "Create
+     * workspace", "Workspace settings", `'-'` separators, "Sign out". A separator is inserted
+     * between the workspaces and the actions automatically.
+     */
+    items?: MenuButtonItem[];
+    /**
+     * Whether the trigger shows the tile alone.
+     */
+    compact?: boolean;
+    /**
+     * Group label above the workspaces; null resolves message
+     * `workspaceSwitcher.heading` ("Workspaces"), and an empty string leaves the label out.
+     */
+    heading?: string | null;
+    /**
+     * Trigger accessible name, in which `%1` is the active
+     * workspace's name and is filled in again after every switch. Null resolves message
+     * `workspaceSwitcher.label` ("Switch workspace: %1"), or `workspaceSwitcher.labelEmpty`
+     * ("Switch workspace") while no workspace is active.
+     */
+    label?: string | null;
+    /**
+     * Popup placement.
+     */
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top' | 'right-start' | 'right-end' | 'left-start' | 'left-end' | 'right' | 'left';
+    /**
+     * Preventable
+     * workspace switch; `preventDefault()` keeps the previous workspace active and the menu open.
+     */
+    onselect?: (event: CustomEvent<WorkspaceSwitcherSelectDetail>) => void;
+    /**
+     * Preventable
+     * extra action; `preventDefault()` skips the item's own callback and keeps the menu open.
+     */
+    onaction?: (event: CustomEvent<{
+        value: unknown;
+        item: object;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Component-local message overrides, by key:
+     * `workspaceSwitcher.heading` ("Workspaces"), `workspaceSwitcher.label` ("Switch workspace: %1",
+     * `%1` the active workspace's name), and `workspaceSwitcher.labelEmpty` ("Switch workspace",
+     * the trigger's name while no workspace is active).
+     */
+    msg?: Record<string, unknown>;
+};
+/** @typedef {import('../menu-button/menu-button.js').MenuButtonItem} MenuButtonItem */
+/** @typedef {import('../app-icon/app-icon.js').AppIconTone} AppIconTone */
+/**
+ * One workspace, account, or organisation the user can switch to.
+ * @typedef {Object} WorkspaceItem
+ * @property {string|number} id Stable identifier; the `active` option and `setActive()` name it.
+ * @property {string} label Workspace name.
+ * @property {string} [secondary] Secondary line: plan, role, domain.
+ * @property {string|Node} [icon] Icon name or node drawn on the tile instead of the initial. A node
+ *   is cloned for each place the tile appears.
+ * @property {AppIconTone} [tone] Tile colour from the theme's categorical palette. Without `tone`
+ *   or `color` the tone is derived from the label, so a workspace keeps its colour everywhere.
+ * @property {string} [color] Tile colour, any CSS colour; takes precedence over `tone`.
+ * @property {string|null} [src] Image drawn as the tile instead of the initial or icon.
+ * @property {string} [initials] Explicit tile initials; derived from the label when omitted.
+ * @property {string|number} [badge] Compact trailing metadata in the menu, such as an unread count.
+ * @property {boolean} [disabled=false] Whether the workspace is listed but cannot be chosen.
+ */
+/**
+ * @typedef {Object} WorkspaceSwitcherSelectDetail
+ * @property {WorkspaceItem} workspace The workspace being switched to.
+ * @property {string|number} id Its id.
+ * @property {WorkspaceItem|null} previous The workspace active until now.
+ */
+/**
+ * @typedef {Object} WorkspaceSwitcherOptions
+ * @property {WorkspaceItem[]} [workspaces=[]] Workspaces in menu order. Entries without an id are
+ *   skipped, and a repeated id keeps its first entry.
+ * @property {string|number|null} [active=null] Active workspace id. Defaults to the first enabled
+ *   workspace, which also stands in for an id that is not listed or is disabled.
+ * @property {MenuButtonItem[]} [items=[]] Extra actions listed after the workspaces — "Create
+ *   workspace", "Workspace settings", `'-'` separators, "Sign out". A separator is inserted
+ *   between the workspaces and the actions automatically.
+ * @property {boolean} [compact=false] Whether the trigger shows the tile alone.
+ * @property {string|null} [heading=null] Group label above the workspaces; null resolves message
+ *   `workspaceSwitcher.heading` ("Workspaces"), and an empty string leaves the label out.
+ * @property {string|null} [label=null] Trigger accessible name, in which `%1` is the active
+ *   workspace's name and is filled in again after every switch. Null resolves message
+ *   `workspaceSwitcher.label` ("Switch workspace: %1"), or `workspaceSwitcher.labelEmpty`
+ *   ("Switch workspace") while no workspace is active.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'|'right-start'|'right-end'|'left-start'|'left-end'|'right'|'left'} [placement='bottom-start'] Popup placement.
+ * @property {(event: CustomEvent<WorkspaceSwitcherSelectDetail>) => void} [onselect] Preventable
+ *   workspace switch; `preventDefault()` keeps the previous workspace active and the menu open.
+ * @property {(event: CustomEvent<{value: unknown, item: object}>) => void} [onaction] Preventable
+ *   extra action; `preventDefault()` skips the item's own callback and keeps the menu open.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ * @property {Record<string, unknown>} [msg] Component-local message overrides, by key:
+ *   `workspaceSwitcher.heading` ("Workspaces"), `workspaceSwitcher.label` ("Switch workspace: %1",
+ *   `%1` the active workspace's name), and `workspaceSwitcher.labelEmpty` ("Switch workspace",
+ *   the trigger's name while no workspace is active).
+ */
+/**
+ * Workspace switcher for the head of an application's navigation: a trigger with the current
+ * workspace's tile, name, and secondary line, opening an APG menu of the workspaces — the current
+ * one checked — followed by the application's own actions. Which workspaces a user may see, and
+ * what switching means, stay application-owned.
+ * @fires WorkspaceSwitcher#select
+ * @fires WorkspaceSwitcher#action
+ * @fires WorkspaceSwitcher#open
+ * @fires WorkspaceSwitcher#close
+ * @extends {Component<WorkspaceSwitcherOptions>}
+ */
+export declare class WorkspaceSwitcher extends Component<WorkspaceSwitcherOptions> {
+    _menu: MenuButton;
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _workspaces: WorkspaceItem[];
+    _activeId: string | number;
+    _items: import("../../internal/menu-items.js").MenuEntry[];
+    /** @type {Map<object, WorkspaceItem>} Menu entries that stand for a workspace. */
+    _entries: Map<object, WorkspaceItem>;
+    static cssName: string;
+    /** @type {Readonly<WorkspaceSwitcherOptions>} */
+    static defaults: Readonly<WorkspaceSwitcherOptions>;
+    /**
+     * Creates or enhances a workspace-switcher host.
+     * @param {Element|string|null} target Host target.
+     * @param {WorkspaceSwitcherOptions} [options={}] Workspace-switcher options.
+     */
+    constructor(target?: Element | string | null, options?: WorkspaceSwitcherOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Returns the active workspace, or null when no workspace is enabled. @returns {WorkspaceItem|null} */
+    getActive(): WorkspaceItem | null;
+    /**
+     * Makes another workspace active. An unknown or disabled id changes nothing.
+     * @param {string|number} id Workspace id.
+     * @param {{silent?: boolean}} [options={}] `silent: false` emits the preventable `select` first;
+     *   by default the change is silent, as a change the application made itself.
+     * @returns {this}
+     * @fires WorkspaceSwitcher#select
+     */
+    setActive(id: string | number, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Replaces the workspaces. The active workspace stays active while it is still listed and
+     * enabled; otherwise the first enabled workspace becomes active, silently.
+     * @param {WorkspaceItem[]} workspaces Workspaces in menu order.
+     * @returns {this}
+     */
+    setWorkspaces(workspaces: WorkspaceItem[]): this;
+    /** Replaces the extra actions after the workspaces. @param {MenuButtonItem[]} items @returns {this} */
+    setItems(items: MenuButtonItem[]): this;
+    /**
+     * Shows the tile alone, or the tile with the name, secondary line, and chevron — for a navigation
+     * column that narrows to icons and widens again. The trigger keeps its full accessible name and
+     * gains the workspace name as a tooltip while compact.
+     * @param {boolean} compact
+     * @returns {this}
+     */
+    setCompact(compact: boolean): this;
+    /** Opens the menu. @returns {this} */
+    open(): this;
+    /** Closes the menu. @returns {this} */
+    close(): this;
+    /** Toggles the menu. @returns {this} */
+    toggle(): this;
+    /** Reports whether the menu is open. @returns {boolean} */
+    isOpen(): boolean;
+    /** Focuses the trigger. @returns {this} */
+    focus(): this;
+    /** Returns the menu panel for shell hover and focus coordination. @returns {HTMLElement} */
+    getPanel(): HTMLElement;
+    /** Destroys the menu and restores or removes the host. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /** @returns {void} */
+    _renderTrigger(): void;
+    /** @returns {void} */
+    _renderMenu(): void;
+    /** @param {CustomEvent<{value: unknown, item: object}>} event @returns {void} */
+    _onMenuSelect(event: CustomEvent<{
+        value: unknown;
+        item: object;
+    }>): void;
+    /** @param {WorkspaceItem} workspace @returns {CustomEvent<WorkspaceSwitcherSelectDetail>} */
+    _emitSelect(workspace: WorkspaceItem): CustomEvent<WorkspaceSwitcherSelectDetail>;
+    /**
+     * Resolves a message, falling back to English when no translation is registered.
+     * @param {string} key Message key.
+     * @param {string} fallback English fallback with `%1` placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
+}
+/**
+ * Normalises one workspace definition: a string id or label, a tone the palette knows, a colour
+ * only when no tone was asked for, and initials derived from the label when none were given.
+ * @param {unknown} value Candidate workspace.
+ * @returns {(WorkspaceItem & {label: string, secondary: string, initials: string, disabled: boolean, tone: AppIconTone|null, color: string|null, src: string|null}) | null}
+ *   The workspace, or null when it has no usable id.
+ */
+export declare function normalizeWorkspace(value: unknown): (WorkspaceItem & {
+    label: string;
+    secondary: string;
+    initials: string;
+    disabled: boolean;
+    tone: AppIconTone | null;
+    color: string | null;
+    src: string | null;
+}) | null;
+/**
+ * Normalises a workspace list, skipping entries without an id and repeats of an id already listed.
+ * @param {unknown} list Candidate workspaces.
+ * @returns {WorkspaceItem[]}
+ */
+export declare function normalizeWorkspaces(list: unknown): WorkspaceItem[];
+/**
+ * Resolves the active workspace id: the requested one when it is listed and enabled, otherwise the
+ * first enabled workspace, otherwise null. Ids compare as strings, so `3` finds `'3'`.
+ * @param {WorkspaceItem[]} workspaces Normalised workspaces.
+ * @param {string|number|null|undefined} active Requested id.
+ * @returns {string|number|null}
+ */
+export declare function resolveActive(workspaces: WorkspaceItem[], active: string | number | null | undefined): string | number | null;
+/**
+ * The tile initials for a workspace: explicit initials trimmed to two characters, otherwise the
+ * first letter of the label, uppercased.
+ * @param {unknown} label Workspace name.
+ * @param {unknown} [initials] Explicit initials.
+ * @returns {string}
+ */
+export declare function workspaceInitials(label: unknown, initials?: unknown): string;
+/**
+ * Fills a custom trigger label: `%1` becomes the active workspace's name (empty while none is
+ * active), so the label follows every switch.
+ * @param {unknown} template Label, with an optional `%1`.
+ * @param {unknown} name Active workspace name.
+ * @returns {string}
+ */
+export declare function formatWorkspaceLabel(template: unknown, name: unknown): string;
+/** Fired before the active workspace changes; preventable. @event WorkspaceSwitcher#select @type {CustomEvent<WorkspaceSwitcherSelectDetail>} */
+/** Fired when an extra action is chosen; preventable. @event WorkspaceSwitcher#action @type {CustomEvent<{value: unknown, item: object}>} */
+/** Fired after the menu opens. @event WorkspaceSwitcher#open @type {CustomEvent<Record<string, never>>} */
+/** Fired after the menu closes. @event WorkspaceSwitcher#close @type {CustomEvent<Record<string, never>>} */

package/dist/types/core/breakpoint.d.ts

@@ -5,7 +5,7 @@
  * used inside a media query, so a `--zx-bp-*` token would be a value no stylesheet could read.
  * Zx's own layout utilities avoid the problem entirely — `.zx-grid` reflows on intrinsic track
  * widths, not on breakpoints — which leaves this module for the cases only script can decide:
- * rendering a Table as cards below a width, collapsing a MasterPanel, choosing a chart density.
+ * rendering a Table as cards below a width, collapsing a MasterPanel, choosing how many labels a chart shows.
  * @module zx/core/breakpoint
  */
 export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/dist/types/core/component.d.ts

@@ -99,9 +99,19 @@ export declare class Component<TOptions extends ComponentOptions = ComponentOpti
      */
     toElement(): Element;
     /**
-     * Resolves and interpolates a component-local or global translation.
+     * Resolves and interpolates one of the component's messages. The first answer wins:
+     *
+     * 1. the `msg` option this instance was given — a `{[lang]: {key: text}}` table for the active
+     *    language (the `lang` option, else `getLanguage()`), then a flat `{key: text}` entry;
+     * 2. the host translator installed with `setTranslator()`;
+     * 3. the `msg` defaults the component class declares;
+     * 4. the default English catalogue (`defaultMessages`);
+     * 5. the key itself.
+     *
+     * A renamed key (`calendar.today`, formerly `today`) is also looked up under its former name,
+     * right after the new one, in steps 1 and 2.
      * @param {string} key Message key.
-     * @param {...unknown} args Positional interpolation values.
+     * @param {...unknown} args Positional interpolation values (`%1`, `%2`, …).
      * @returns {string}
      */
     msg(key: string, ...args: unknown[]): string;

package/dist/types/core/i18n.d.ts

@@ -1,7 +1,10 @@
-/** @typedef {(key: string) => string|null|undefined} Translator */
+import { defaultMessages } from './messages.js';
+export { defaultMessages };
 export type Translator = (key: string) => string | null | undefined;
 /**
- * Installs the host application's translation function, or clears it with null.
+ * Installs the host application's translation function, or clears it with null. The function
+ * answers one key at a time; returning null, undefined, or the key itself means "no translation",
+ * and resolution moves on to the default English catalogue (`defaultMessages`).
  * @param {Translator|null} fn Translator function.
  * @returns {void}
  */
@@ -18,7 +21,28 @@ export declare function setLanguage(lang: string): void;
  */
 export declare function getLanguage(): string;
 /**
- * Translates a key through the injected host translator and interpolates arguments.
+ * Asks the host translator for one key, without interpolating. A translator that returns null,
+ * undefined, or the key itself has no answer.
+ * @param {string} key Message key.
+ * @returns {string|null} The translation, or null when there is none.
+ */
+export declare function hostMessage(key: string): string | null;
+/**
+ * Looks one key up in the default English catalogue.
+ * @param {string} key Message key.
+ * @returns {string|null} The English text, or null when the catalogue has no entry.
+ */
+export declare function defaultMessage(key: string): string | null;
+/**
+ * The key a renamed message key replaced, which is still honoured for one major version.
+ * @param {string} key Current message key.
+ * @returns {string|null} The former key, or null when the key was never renamed.
+ */
+export declare function legacyMessageKey(key: string): string | null;
+/**
+ * Translates a key and interpolates arguments. The host translator answers first (then, for a
+ * renamed key, the translator again under its former name), then the default English catalogue;
+ * a key neither knows comes back unchanged.
  * @param {string} key Translation key.
  * @param {unknown[]|Record<string, unknown>|string|number} [args] Interpolation arguments.
  * @returns {string}

package/dist/types/core/icons.d.ts

@@ -1,7 +1,8 @@
 /**
  * The icon layer. Two renderers sit behind one `icon()` call:
  *
- * - **built-in** (default) — the inline SVG glyphs below, no network, no stylesheet, no font.
+ * - **built-in** (default) — the inline SVG outline glyphs below (Lucide), no network, no
+ *   stylesheet, no font. Applications can add their own, filled or outlined, with `registerIcons()`.
  * - **Font Awesome** — `<i>` elements carrying Font Awesome classes, after an application opts in
  *   with `useFontAwesome()` or `loadFontAwesome(kit)`. Zx never loads a kit by itself.
  *
@@ -40,28 +41,16 @@ export type IconOptions = {
      */
     strict?: boolean;
 };
+export type IconPaint = 'fill' | 'stroke';
+export type IconGlyph = [string, string] | [string, string, IconPaint];
 /**
- * @typedef {Object} IconOptions
- * @property {number|string} [size=16] Rendered width and height.
- * @property {string|null} [label=null] Accessible label; null marks the icon decorative.
- * @property {string|string[]} [class] Extra class names added to the element.
- * @property {string} [style] Font Awesome style for this icon only (`'solid'`, `'duotone'`, …).
- * @property {string} [family] Font Awesome family for this icon only (`'classic'`, `'sharp'`, …).
- * @property {boolean} [fixedWidth] Adds Font Awesome's `fa-fw` for column-aligned glyphs.
- * @property {boolean} [strict=false] Throws `RangeError` on a name the bundled glyph set does not
- *   carry, instead of returning the placeholder. For call sites that can afford to fail — a test,
- *   a build-time check — rather than a screen rendering server data.
+ * The bundled glyph set: outline icons from Lucide (ISC; see the notice above), embedded as path
+ * data so the library carries no webfont, stylesheet, or package dependency. Every entry is
+ * `[viewBox, path, 'stroke']` in a 24-unit view box. Extend the set with `registerIcons()`; read
+ * every available name with `iconNames()`.
+ * @type {Readonly<Record<string, IconGlyph>>}
  */
-/**
- * Icon glyphs from Font Awesome Free 6 (solid, plus `square` from regular), fontawesome.com,
- * licensed CC BY 4.0 (https://fontawesome.com/license/free). Path data is embedded unmodified so
- * the library carries no webfont, stylesheet, or package dependency. Each entry is
- * `[viewBox, path]`; Font Awesome glyphs are filled (not stroked) and use per-glyph 512-unit view
- * boxes — outlines such as `square` are a filled path with a counter-wound hole.
- * Extend the set with `registerIcons()`; read every available name with `iconNames()`.
- * @type {Readonly<Record<string, [string, string]>>}
- */
-export declare const icons: Readonly<Record<string, [string, string]>>;
+export declare const icons: Readonly<Record<string, IconGlyph>>;
 export type IconConfig = {
     /**
      * Renderer used for bare icon names.
@@ -120,12 +109,21 @@ export declare function loadFontAwesome(options: string | (Partial<Omit<IconConf
     activate?: boolean;
 })): Promise<IconConfig>;
 /**
- * Adds inline SVG glyphs to the built-in set, or replaces existing ones. Entries use the same
- * `[viewBox, path]` shape as `icons`.
- * @param {Record<string, [string, string]>} glyphs Glyphs keyed by icon name.
+ * Adds inline SVG glyphs to the built-in set, or replaces existing ones.
+ *
+ * An entry is `[viewBox, path]` — a filled shape, the format Font Awesome path data comes in, and
+ * how it always rendered — or `[viewBox, path, 'stroke']` — an outline drawn with the same pen as
+ * the bundled set: `currentColor`, round caps and joins, and a stroke scaled to the view box, so a
+ * glyph from a 24-unit outline set such as Lucide renders exactly like a bundled one.
+ *
+ *     registerIcons({ rocket: ['0 0 512 512', 'M…'] });           // filled
+ *     registerIcons({ anchor: ['0 0 24 24', 'M12 6v16…', 'stroke'] });  // outline
+ * @param {Record<string, IconGlyph>} glyphs Glyphs keyed by icon name.
  * @returns {void}
+ * @throws {TypeError} When an entry is neither a `[viewBox, path]` pair nor a
+ *   `[viewBox, path, 'fill'|'stroke']` triple.
  */
-export declare function registerIcons(glyphs: Record<string, [string, string]>): void;
+export declare function registerIcons(glyphs: Record<string, IconGlyph>): void;
 /**
  * Lists every inline SVG glyph name available, built-in and registered.
  * @returns {string[]} Sorted icon names.

package/dist/types/core/keyboard.d.ts

@@ -7,6 +7,12 @@ export type RovingOptions = {
      * Whether navigation wraps at either end.
      */
     wrap?: boolean;
+    /**
+     * Whether ArrowLeft and ArrowRight swap meaning in a
+     * horizontal group. `'auto'` reads the container's computed `direction` on every key press, so
+     * a group inside `dir="rtl"` moves to the visually next item; `true`/`false` force it.
+     */
+    rtl?: 'auto' | boolean;
 };
 export type FocusTrapController = {
     /**
@@ -36,6 +42,9 @@ export type RovingController = {
  * @typedef {Object} RovingOptions
  * @property {'vertical'|'horizontal'} [orientation='vertical'] Arrow-key axis.
  * @property {boolean} [wrap=true] Whether navigation wraps at either end.
+ * @property {'auto'|boolean} [rtl='auto'] Whether ArrowLeft and ArrowRight swap meaning in a
+ *   horizontal group. `'auto'` reads the container's computed `direction` on every key press, so
+ *   a group inside `dir="rtl"` moves to the visually next item; `true`/`false` force it.
  */
 /**
  * @typedef {Object} FocusTrapController
@@ -56,12 +65,74 @@ export type RovingController = {
 export declare function focusTrap(container: Element): FocusTrapController;
 /**
  * Applies the ARIA roving-tabindex keyboard pattern to matching descendants.
+ *
+ * Editable items keep the keys they need, as the APG toolbar pattern asks: Home and End always
+ * stay with a text field, select, or contenteditable region, and so do the arrow keys — except
+ * that a text field whose caret already sits at the edge the arrow points past hands focus on to
+ * the neighbouring item, so a reader is never trapped in it. Under `dir="rtl"` the horizontal
+ * arrows follow the visual order.
+ *
+ * The group re-reads its items when children are added or removed and when an availability
+ * attribute (`hidden`, `disabled`, `aria-disabled`, `aria-hidden`) changes on an item or on an
+ * element inside the container that holds items — a `<fieldset disabled>` toggled around them; its
+ * own `tabindex` writes and unrelated attribute churn are not observed.
  * @param {Element} container Event and query container.
  * @param {string} itemSelector Selector for roving items.
  * @param {RovingOptions} [options={}] Behavior options.
  * @returns {RovingController}
  */
-export declare function rovingTabindex(container: Element, itemSelector: string, { orientation, wrap }?: RovingOptions): RovingController;
+export declare function rovingTabindex(container: Element, itemSelector: string, { orientation, wrap, rtl }?: RovingOptions): RovingController;
+export type ItemFocusMemo = {
+    /**
+     * The item's key.
+     */
+    key: unknown;
+    /**
+     * Whether the item element itself held focus.
+     */
+    self: boolean;
+    /**
+     * Position of the focused control among the item's focusable controls.
+     */
+    index: number;
+    /**
+     * Tag, data attributes, and name of the focused control, which
+     * identify its replacement after a rebuild.
+     */
+    signature: string;
+};
+/**
+ * Where focus sat inside one keyed item of a collection, recorded before the collection re-renders.
+ * @typedef {Object} ItemFocusMemo
+ * @property {unknown} key The item's key.
+ * @property {boolean} self Whether the item element itself held focus.
+ * @property {number} index Position of the focused control among the item's focusable controls.
+ * @property {string} signature Tag, data attributes, and name of the focused control, which
+ *   identify its replacement after a rebuild.
+ */
+/**
+ * Records which control of which keyed item holds focus, so a collection that rebuilds an item
+ * can put focus back on the equivalent control afterwards. Returns null when focus is elsewhere.
+ * @param {Element} root Collection root.
+ * @param {(element: Element) => ({key: unknown, element: Element}|null)} locate Finds the keyed
+ *   item an element belongs to.
+ * @returns {ItemFocusMemo|null}
+ */
+export declare function captureItemFocus(root: Element, locate: (element: Element) => ({
+    key: unknown;
+    element: Element;
+} | null)): ItemFocusMemo | null;
+/**
+ * Puts focus back on the control a {@link captureItemFocus} memo describes, unless focus is still
+ * on a live element inside the collection (nothing was lost). The replacement is the control with
+ * the same signature, else the one at the same position, else the item's last control, else the
+ * item itself when it is focusable. Scrolling is suppressed: the reader did not move.
+ * @param {Element} root Collection root.
+ * @param {ItemFocusMemo|null} memo Recorded focus.
+ * @param {(key: unknown) => Element|null} resolve Finds the item element for a key after the update.
+ * @returns {boolean} Whether focus was moved.
+ */
+export declare function restoreItemFocus(root: Element, memo: ItemFocusMemo | null, resolve: (key: unknown) => Element | null): boolean;
 /**
  * Creates a 500 ms buffered, case-insensitive first-letter typeahead handler.
  * @template T
@@ -70,3 +141,29 @@ export declare function rovingTabindex(container: Element, itemSelector: string,
  * @returns {(event: KeyboardEvent|string) => void}
  */
 export declare function typeahead<T>(getItems: () => T[], onMatch: (item: T, index: number) => void): (event: KeyboardEvent | string) => void;
+/**
+ * Maps a key to a roving step, or null for a key the group does not handle.
+ * @param {string} key `KeyboardEvent.key`.
+ * @param {'vertical'|'horizontal'} orientation Arrow-key axis.
+ * @param {boolean} reversed Whether the horizontal arrows are swapped (right-to-left).
+ * @returns {'first'|'last'|'previous'|'next'|null}
+ */
+export declare function rovingStep(key: string, orientation: 'vertical' | 'horizontal', reversed?: boolean): 'first' | 'last' | 'previous' | 'next' | null;
+/**
+ * Whether an element takes keyboard text input, so that arrow keys and Home/End move its caret
+ * or its value: a text-like `<input>`, `<textarea>`, `<select>`, or a contenteditable region.
+ * @param {Element|null} element Candidate, normally a key event's target.
+ * @returns {boolean}
+ */
+export declare function isEditableTarget(element: Element | null): boolean;
+/**
+ * Whether a roving step may leave the event target. Non-editable targets always may. An editable
+ * one keeps Home/End, and keeps the arrows unless it is a single-line text field whose collapsed
+ * caret already sits at the edge the step points past: position 0 for `previous`, the end of the
+ * value for `next`. The steps are logical, so under right-to-left the caret check still matches
+ * the direction the caret would have moved.
+ * @param {Element|null} target Key event target.
+ * @param {'first'|'last'|'previous'|'next'} step Roving step.
+ * @returns {boolean}
+ */
+export declare function editableAllowsRoving(target: Element | null, step: 'first' | 'last' | 'previous' | 'next'): boolean;