@zeyos/zx 4.3.4 → 5.0.0

package/dist/types/components/select/glyphs.d.ts

@@ -0,0 +1,124 @@
+export type StatusIndicator = 'dotted' | 'ring' | 'progress' | 'review' | 'ready' | 'waiting' | 'done' | 'canceled' | 'duplicate';
+export type StatusTone = 'muted' | 'neutral' | 'warning' | 'info' | 'accent' | 'success' | 'danger';
+export type StatusId = 'backlog' | 'todo' | 'in-progress' | 'in-review' | 'review' | 'ready' | 'waiting' | 'done' | 'canceled' | 'cancelled' | 'duplicate';
+export type StatusIconOptions = {
+    /**
+     * Shape, overriding the status's own.
+     */
+    indicator?: StatusIndicator;
+    /**
+     * Colour, overriding the status's own.
+     */
+    tone?: StatusTone;
+    /**
+     * Accessible name. Without one the glyph is decorative
+     * (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+     * status.
+     */
+    label?: string | null;
+};
+export type PriorityIconOptions = {
+    /**
+     * Accessible name. Without one the glyph is decorative
+     * (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+     * priority.
+     */
+    label?: string | null;
+};
+/**
+ * The shapes a workflow-status glyph can take. Each status reads by shape first and colour
+ * second, so the set stays legible to readers who do not see the colour.
+ * @typedef {'dotted'|'ring'|'progress'|'review'|'ready'|'waiting'|'done'|'canceled'|'duplicate'} StatusIndicator
+ */
+/** @typedef {'muted'|'neutral'|'warning'|'info'|'accent'|'success'|'danger'} StatusTone */
+/**
+ * The built-in workflow statuses. `review` and `cancelled` are accepted as spellings of
+ * `in-review` and `canceled`.
+ * @typedef {'backlog'|'todo'|'in-progress'|'in-review'|'review'|'ready'|'waiting'|'done'|'canceled'|'cancelled'|'duplicate'} StatusId
+ */
+/**
+ * @typedef {Object} StatusIconOptions
+ * @property {StatusIndicator} [indicator] Shape, overriding the status's own.
+ * @property {StatusTone} [tone] Colour, overriding the status's own.
+ * @property {string|null} [label=null] Accessible name. Without one the glyph is decorative
+ *   (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+ *   status.
+ */
+/**
+ * @typedef {Object} PriorityIconOptions
+ * @property {string|null} [label=null] Accessible name. Without one the glyph is decorative
+ *   (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+ *   priority.
+ */
+/** Every shape `statusIcon()` draws. */
+export declare const STATUS_INDICATORS: readonly string[];
+/** Every colour a status glyph takes, from the semantic set. */
+export declare const STATUS_TONES: readonly string[];
+/**
+ * The built-in statuses in workflow order, as `[id, message key, English name, indicator, tone]`.
+ * `Select.status()` lists them; `statusIcon()` draws them.
+ */
+export declare const DEFAULT_STATUSES: readonly string[][];
+/** The top priority level, the one coloured level: a danger square with an exclamation mark. */
+export declare const PRIORITY_URGENT = 4;
+/**
+ * Resolves the shape and colour of a status glyph.
+ *
+ * A status is a built-in id (or one of its other spellings), or a status item of the kind
+ * `Select.status({items})` takes, whose own `indicator` and `tone` win over the built-in status
+ * its `ID` names. Options win over both. An unknown shape falls back to the empty ring and an
+ * unknown colour to muted, as `Select.status()` does with a custom item.
+ * @param {StatusId|string|{ID?: unknown, id?: unknown, indicator?: unknown, tone?: unknown}|null|undefined} status
+ * @param {StatusIconOptions} [options={}] Overrides.
+ * @returns {{indicator: StatusIndicator, tone: StatusTone}}
+ */
+export declare function resolveStatusGlyph(status: StatusId | string | {
+    ID?: unknown;
+    id?: unknown;
+    indicator?: unknown;
+    tone?: unknown;
+} | null | undefined, options?: StatusIconOptions): {
+    indicator: StatusIndicator;
+    tone: StatusTone;
+};
+/**
+ * Maps a status id to its built-in spelling: trimmed, lower-cased, and `review` / `cancelled`
+ * read as `in-review` / `canceled`.
+ * @param {unknown} id Status id.
+ * @returns {string}
+ */
+export declare function normalizeStatusId(id: unknown): string;
+/**
+ * Settles a priority level: an integer from 0 (lowest) to 4 (highest), or `null` for no priority.
+ * Out-of-range numbers clamp; anything that is not a number reads as 0.
+ * @param {unknown} level Priority level.
+ * @returns {number|null}
+ */
+export declare function normalizePriorityLevel(level: unknown): number | null;
+/**
+ * Draws the workflow-status glyph `Select.status()` shows, for a list row, a board column, a
+ * filter chip, or a heading — so every place a status appears reads as the picker that changes it.
+ *
+ * Built-in statuses: `backlog` (dotted ring), `todo` (empty ring), `in-progress` (ring with a
+ * centre dot), `in-review` (half filled; also `review`), `ready` (a third filled), `waiting` (two
+ * thirds filled), `done` (filled, with a check), `canceled` (filled, with a cross; also
+ * `cancelled`), and `duplicate` (ring with a slash). Colour only repeats what the shape says.
+ * @param {StatusId|string|{ID?: unknown, indicator?: unknown, tone?: unknown}} status Built-in id,
+ *   or a status item with its own `indicator` and `tone`.
+ * @param {StatusIconOptions} [options={}] Shape, colour, and accessible-name overrides.
+ * @returns {HTMLSpanElement} A `.zx-status-icon` element, decorative unless `label` is given.
+ */
+export declare function statusIcon(status: StatusId | string | {
+    ID?: unknown;
+    indicator?: unknown;
+    tone?: unknown;
+}, options?: StatusIconOptions): HTMLSpanElement;
+/**
+ * Draws the priority glyph `Select.priority()` shows. Levels 0–3 are four signal bars in muted
+ * ink, filled up to the level; level 4, the highest, is a filled danger square whose "!" the
+ * stylesheet draws, so it never joins the text beside it; no priority (`null`) is a row of dashes.
+ * @param {number|null} level Priority level, 0 (lowest) to 4 (highest), or `null` for none.
+ * @param {PriorityIconOptions} [options={}] Accessible-name option.
+ * @returns {HTMLSpanElement} A `.zx-priority-icon` element, decorative unless `label` is given.
+ */
+export declare function priorityIcon(level: number | null, options?: PriorityIconOptions): HTMLSpanElement;

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

@@ -68,6 +68,10 @@ export type SelectOptions = {
      * Empty control text.
      */
     placeholder?: string;
+    /**
+     * Accessible combobox name; falls back to the placeholder.
+     */
+    label?: string;
     /**
      * Whether selection may be cleared.
      */
@@ -143,7 +147,9 @@ export type EntitySelectOptions = {
      */
     iconKey?: string | ((item: SelectItem) => unknown);
     /**
-     * Optional icon colour reader.
+     * Optional icon colour reader: a CSS
+     * colour or a token reference such as `var(--zx-color-tone-blue-fg)`. Without one the glyph is a
+     * neutral tile in muted ink.
      */
     colorKey?: string | ((item: SelectItem) => unknown);
     /**
@@ -210,6 +216,7 @@ export declare class Select extends Component<SelectOptions> {
     _createdRoot: boolean;
     _root: HTMLElement;
     _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _pointerModality: boolean;
     _handleTypeahead: (event: KeyboardEvent | string) => void;
     static cssName: string;
     /** @type {SelectOptions} */
@@ -263,9 +270,14 @@ export declare class Select extends Component<SelectOptions> {
     /** Moves focus to the combobox input. @returns {this} */
     focus(): this;
     /**
-     * Creates the five-level priority preset.
+     * Creates the five-level priority preset: values 0 (lowest) to 4 (highest), each drawn as grey
+     * signal bars filled to its level, except the highest, which is the one coloured level — a
+     * danger square with an exclamation mark. A "No priority" row (value null, a row of dashes)
+     * heads the list and labels the empty control; `clearable: false` removes it.
      * @param {Element|string|null} target Component target.
-     * @param {SelectOptions} [options={}] Select overrides other than fixed items and renderer.
+     * @param {SelectOptions} [options={}] Select overrides other than items and renderers.
+     *   `clearable` defaults to true here; `noneLabel` and `placeholder` default to the
+     *   `priority.none` message ("No priority").
      * @returns {Select}
      */
     static priority(target: Element | string | null, options?: SelectOptions): Select;

package/dist/types/components/sort-control/sort-control.d.ts

@@ -0,0 +1,105 @@
+import { Component } from '../../core/component.js';
+import { Select } from '../select/select.js';
+export type SortField = {
+    id: string;
+    label: string;
+};
+export type SortValue = {
+    id: string;
+    dir: 'asc' | 'desc';
+};
+export type SortControlOptions = {
+    /**
+     * Available sort fields, in display order.
+     */
+    fields?: SortField[];
+    /**
+     * Initial sort; null chooses the first field ascending.
+     */
+    value?: SortValue | null;
+    /**
+     * Accessible field label and direction-name prefix.
+     */
+    label?: string;
+    /**
+     * Current/next direction labels, defaulting to Ascending/Descending.
+     */
+    labels?: {
+        asc?: string;
+        desc?: string;
+    };
+    /**
+     * Whether interaction is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Atomic field/direction change.
+     */
+    onchange?: (event: CustomEvent<{
+        value: SortValue;
+    }>) => void;
+};
+/** @typedef {{id:string,label:string}} SortField */
+/** @typedef {{id:string,dir:'asc'|'desc'}} SortValue */
+/**
+ * @typedef {Object} SortControlOptions
+ * @property {SortField[]} [fields=[]] Available sort fields, in display order.
+ * @property {SortValue|null} [value=null] Initial sort; null chooses the first field ascending.
+ * @property {string} [label='Sort by'] Accessible field label and direction-name prefix.
+ * @property {{asc?:string,desc?:string}} [labels={}] Current/next direction labels, defaulting to Ascending/Descending.
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {(event:CustomEvent<{value:SortValue}>)=>void} [onchange] Atomic field/direction change.
+ */
+/**
+ * A searchable field selector with an adjacent direction toggle and one shared sort value.
+ * @fires SortControl#change
+ * @extends {Component<SortControlOptions>}
+ */
+export declare class SortControl extends Component<SortControlOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _value: SortValue;
+    _disabled: boolean;
+    _direction: HTMLButtonElement;
+    _select: Select;
+    static cssName: string;
+    /** @type {SortControlOptions} */
+    static defaults: SortControlOptions;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Returns a defensive copy of the current sort. @returns {SortValue|null} */
+    getValue(): SortValue | null;
+    /**
+     * Replaces the field and direction atomically; rejects unavailable fields and directions.
+     * @param {SortValue|null} value Sort state, or null for the first field ascending.
+     * @param {{silent?:boolean}} [options={}] Suppress change when silent.
+     * @returns {this}
+     */
+    setValue(value: SortValue | null, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /** Enables both controls when fields are available. @returns {this} */
+    enable(): this;
+    /** Disables both controls and closes the option panel. @returns {this} */
+    disable(): this;
+    /** Updates the icon and accessible current/next direction text. @private @returns {void} */
+    private _syncDirection;
+    /** Focuses the searchable control. @returns {this} */
+    focus(): this;
+    /** Releases the owned Select and restores an enhanced target. @returns {void} */
+    destroy(): void;
+}
+/**
+ * Validates a sort against available fields without retaining caller-owned state.
+ * @param {SortValue|null} value Requested sort.
+ * @param {SortField[]} fields Available fields.
+ * @returns {SortValue|null} Normalized sort, or null for an empty catalogue.
+ */
+export declare function normalizeSortValue(value: SortValue | null, fields: SortField[]): SortValue | null;
+/**
+ * Builds one searchable record per field without retaining caller-owned objects.
+ * @param {SortField[]} fields Available fields.
+ * @returns {SortField[]} Choice records.
+ */
+export declare function sortChoices(fields: SortField[]): SortField[];
+/** @event SortControl#change @type {CustomEvent<{value:SortValue}>} */

package/dist/types/components/stat-tile/stat-tile.d.ts

@@ -0,0 +1,288 @@
+import { Component } from '../../core/component.js';
+export type StatTileFormatName = 'number' | 'currency' | 'percent' | 'fileSize' | null;
+export type StatTileFormat = StatTileFormatName | ((value: number | string | null | undefined) => string);
+export type StatTileKind = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+export type StatTileDeltaKind = 'positive' | 'negative' | 'neutral';
+export type StatTileDirection = 'up' | 'down' | 'flat';
+export type StatTileDelta = {
+    /**
+     * Which way the metric moved, read from the sign alone.
+     */
+    direction: StatTileDirection;
+    /**
+     * `'+'`, `'−'` (U+2212), or `''` for an unchanged metric.
+     */
+    sign: string;
+    /**
+     * The formatted absolute change, without a sign.
+     */
+    magnitude: string;
+    /**
+     * The visible change: `sign` followed by `magnitude`.
+     */
+    text: string;
+};
+export type StatTileNameParts = {
+    /**
+     * The metric's name.
+     */
+    label?: string;
+    /**
+     * The formatted value.
+     */
+    value?: string;
+    /**
+     * The context line under the value, e.g. `'of 13,184'`.
+     */
+    caption?: string;
+    /**
+     * The change, already worded for speech (`'up 2'`, not `'+2'`).
+     */
+    delta?: string;
+    /**
+     * What the change is measured against.
+     */
+    deltaLabel?: string;
+};
+export type StatTileOptions = {
+    /**
+     * The metric's name, set small above the value.
+     */
+    label?: string;
+    /**
+     * The metric. A string is rendered as given.
+     */
+    value?: number | string | null;
+    /**
+     * How a numeric value is rendered: a named mode, a
+     * callback receiving the raw value, or null to print the value unformatted.
+     */
+    format?: StatTileFormat;
+    /**
+     * ISO 4217 code used by `format: 'currency'`.
+     */
+    currency?: string | null;
+    /**
+     * A muted context line under the value — what the number is out
+     * of or measured in, e.g. `'of 13,184'` or `'open tickets'`. Part of the accessible name.
+     */
+    caption?: string;
+    /**
+     * BCP 47 tag for every formatter; defaults to the active language.
+     */
+    locale?: string;
+    /**
+     * Change against the previous period. Rendered with
+     * its own sign and an arrow, never with colour alone.
+     */
+    delta?: number | string | null;
+    /**
+     * Whether the change is good, bad, or merely a
+     * change. This — not the sign's direction — picks the delta colour: a rising ticket count is not
+     * a success, so "up is good" is never assumed.
+     */
+    deltaKind?: StatTileDeltaKind;
+    /**
+     * How the delta is rendered; defaults to `format`.
+     */
+    deltaFormat?: StatTileFormat;
+    /**
+     * What the change is measured against, e.g. `'vs. last week'`.
+     */
+    deltaLabel?: string;
+    /**
+     * Values for a decorative sparkline. Fewer than two usable numbers
+     * render nothing.
+     */
+    trend?: number[];
+    /**
+     * Icon name from `icons.js`, shown muted beside the label —
+     * a glyph, not a coloured chip.
+     */
+    icon?: string | null;
+    /**
+     * Semantic intent. It tints the sparkline and never the
+     * value, which stays at full text contrast whatever intent a record carries.
+     */
+    kind?: StatTileKind;
+    /**
+     * Destination. A tile with an href is an `<a>`.
+     */
+    href?: string | null;
+    /**
+     * Renders a `<button>` without an href. Passing `onclick`
+     * sets this implicitly; set it directly to subscribe with `on('click', …)` instead.
+     */
+    clickable?: boolean;
+    /**
+     * Renders a skeleton shaped like the tile.
+     */
+    loading?: boolean;
+    /**
+     * Message overrides, keyed as `statTile.*`.
+     */
+    msg?: Record<string, unknown>;
+    /**
+     * Activation listener; its
+     * presence is what turns a tile with no href into a button. It is the tile's `click` event, as
+     * every Zx component's `on*` option is, so it receives the `CustomEvent` carrying the native
+     * event in `detail.event`.
+     */
+    onclick?: (event: CustomEvent<{
+        event: MouseEvent;
+    }>) => void;
+};
+/**
+ * Renders a metric: a label, the number it names, and — optionally — how that number moved.
+ *
+ * The value is the loudest thing on the tile; the label sits small above it and the delta and the
+ * sparkline are subordinate to both. Nothing here assumes a fixed set of metrics: the label, the
+ * intent colour, the icon and the formatting all arrive per instance, so a tile whose content
+ * comes from a server is the normal case rather than the exception.
+ *
+ * The element shape follows the tile's behaviour, and a tag cannot be rewritten in place, so the
+ * component normally builds its own root — pass `null` as the target, or use {@link statTile}. An
+ * existing element is adopted only when its tag already is the one the options call for; a mismatch
+ * throws rather than silently shipping a `<div>` with a click handler or a link that cannot
+ * navigate.
+ *
+ * @fires StatTile#click
+ * @extends {Component<StatTileOptions>}
+ */
+export declare class StatTile extends Component<StatTileOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _closed: boolean;
+    _state: any;
+    static cssName: string;
+    /** @type {Readonly<StatTileOptions>} */
+    static defaults: Readonly<StatTileOptions>;
+    /**
+     * Creates or adopts one metric tile.
+     * @param {Element|string|null} [target=null] Existing element of the required tag, or null.
+     * @param {StatTileOptions} [options={}] Tile options.
+     */
+    constructor(target?: Element | string | null, options?: StatTileOptions);
+    /**
+     * @returns {HTMLElement}
+     * @throws {TypeError} When an adopted target is not the tag the options require.
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces any subset of the tile's content and redraws it. This is how a tile leaves
+     * `loading: true` behind once the server answers.
+     * @param {StatTileOptions} options Options to merge over the current ones.
+     * @returns {this}
+     * @throws {TypeError} When the merged options would need a different element tag.
+     */
+    update(options?: StatTileOptions): this;
+    /**
+     * Reports the tile's own accessible name, which is what assistive technology announces.
+     * @returns {string} Label, value, and delta, in that order.
+     */
+    getAccessibleName(): string;
+    /**
+     * Aborts listeners and restores an adopted target to the state it was found in.
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, ...args: unknown[]): string;
+}
+/**
+ * Creates a tile that builds its own root: the convenience form of `new StatTile(null, options)`,
+ * the way `tooltip()` stands in for `new Tooltip(…)`.
+ *
+ * It returns the component, not an element, so there is one construction idiom and one click path.
+ * Call `.toElement()` for the node to place.
+ *
+ * @param {StatTileOptions} [opts={}] Tile options.
+ * @returns {StatTile} The component, whose root is an `<a>`, a `<button>`, or a `<div>`.
+ */
+export declare function statTile(opts?: StatTileOptions): StatTile;
+/**
+ * Formats the metric itself.
+ *
+ * A string value is the host's own final text and is passed through untouched; an explicit
+ * callback outranks that, because a host that supplies one has asked to decide every case.
+ *
+ * @param {number|string|null|undefined} value The metric.
+ * @param {{format?: StatTileFormat, locale?: string, currency?: string|null}} [options={}] Mode,
+ *   language, and currency.
+ * @returns {string} The text to display; empty for a missing value.
+ */
+export declare function formatStatValue(value: number | string | null | undefined, options?: {
+    format?: StatTileFormat;
+    locale?: string;
+    currency?: string | null;
+}): string;
+/**
+ * Describes a change without judging it.
+ *
+ * The direction is read from the sign and nothing else; whether that direction is good news is
+ * `deltaKind`'s business, not this function's. The magnitude is formatted from the absolute value
+ * and the sign is prepended, because no locale prints a leading `+` on its own.
+ *
+ * @param {number|string|null|undefined} delta The change.
+ * @param {{format?: StatTileFormat, locale?: string, currency?: string|null}} [options={}]
+ *   Formatting, defaulting to the tile's own.
+ * @returns {StatTileDelta|null} The change, or null when there is none to show.
+ */
+export declare function statDelta(delta: number | string | null | undefined, options?: {
+    format?: StatTileFormat;
+    locale?: string;
+    currency?: string | null;
+}): StatTileDelta | null;
+/**
+ * Chooses the element a tile must be, from what the tile does.
+ *
+ * A destination is a link, an action is a button, and a tile that does neither is a plain
+ * container. A `<div>` never gets a click handler, and an href that could execute script is not a
+ * destination at all — it falls through to whichever shape the remaining options justify.
+ *
+ * @param {{href?: string|null, clickable?: boolean, onclick?: unknown}} [options={}] The options
+ *   that carry behaviour.
+ * @returns {'a'|'button'|'div'} The tag to render.
+ */
+export declare function statTileTag(options?: {
+    href?: string | null;
+    clickable?: boolean;
+    onclick?: unknown;
+}): 'a' | 'button' | 'div';
+/**
+ * Composes the tile's accessible name: label, then value with its caption, then how it changed.
+ *
+ * The sparkline is decoration and contributes nothing, and the delta arrives already worded —
+ * `'up 2'` rather than `'+2'` — because a screen reader should not have to interpret a glyph. The
+ * caption is read with the value it qualifies (`'2,184 of 13,184'`), not as a separate clause.
+ *
+ * @param {StatTileNameParts} [parts={}] The pieces, already formatted and translated.
+ * @returns {string} The name, with empty pieces dropped rather than left as stray punctuation.
+ */
+export declare function statTileName(parts?: StatTileNameParts): string;
+/**
+ * Projects a series onto the sparkline's user-unit box.
+ *
+ * A series needs two usable numbers to be a line; a flat series is drawn down the middle rather
+ * than along the floor, which would read as zero.
+ *
+ * @param {unknown[]} values The series, in order. Unusable entries are dropped.
+ * @param {{width?: number, height?: number, inset?: number}} [box={}] The target box.
+ * @returns {string|null} An SVG `points` list, or null when there is no line to draw.
+ */
+export declare function statTrendPoints(values: unknown[], box?: {
+    width?: number;
+    height?: number;
+    inset?: number;
+}): string | null;
+/**
+ * Fired when a linked or clickable tile is activated. A tile with neither an href nor a click
+ * handler is a `<div>` and never emits it.
+ * @event StatTile#click
+ * @type {CustomEvent<{event: MouseEvent}>}
+ */

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

@@ -53,6 +53,12 @@ export type TabboxOptions = {
      * Keep inactive panel elements mounted.
      */
     keepAlive?: boolean;
+    /**
+     * Accessible name of the tab list — what the tabs switch between
+     * ("Record sections"). A tab list needs one whenever the page has more than one, and screen
+     * readers announce it on entry.
+     */
+    label?: string;
     /**
      * Change callback.
      */
@@ -107,6 +113,9 @@ export type TabRecord = {
  *   the active tab across a full-width rule; `segmented` renders a compact group that reads as one
  *   control, for a toolbar or card header.
  * @property {boolean} [keepAlive=true] Keep inactive panel elements mounted.
+ * @property {string} [label] Accessible name of the tab list — what the tabs switch between
+ *   ("Record sections"). A tab list needs one whenever the page has more than one, and screen
+ *   readers announce it on entry.
  * @property {(event: CustomEvent<{name: string, previous: string|null}>) => void} [onchange] Change callback.
  * @property {(event: CustomEvent<{name: string}>) => void} [onclose] Close callback, fired when the
  *   user dismisses a closable tab.
@@ -236,4 +245,11 @@ export declare class Tabbox extends Component<TabboxOptions> {
     _require(name: string): TabRecord;
     /** @param {Element} tab @returns {TabRecord|null} */
     _recordForTab(tab: Element): TabRecord | null;
+    /**
+     * 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.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }