@zeyos/zx 4.3.4 → 5.0.0

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

@@ -0,0 +1,599 @@
+import { Component } from '../../core/component.js';
+import { Search } from '../search/search.js';
+export type ListToolbarSearch = {
+    /**
+     * Field placeholder; also names the field. Defaults to the
+     * `listToolbar.search` message.
+     */
+    placeholder?: string;
+    /**
+     * Initial query.
+     */
+    value?: string;
+    /**
+     * Debounce before `search` is emitted, in milliseconds.
+     */
+    debounce?: number;
+    /**
+     * Whether the field shows its clear control.
+     */
+    clearable?: boolean;
+};
+export type ListToolbarTool = {
+    /**
+     * Stable identifier, reported by `action` and addressed by `setBadge()`.
+     */
+    id: string;
+    /**
+     * Visible label, and the base of the accessible name.
+     */
+    label?: string;
+    /**
+     * Icon name from `icons.js`.
+     */
+    icon?: string | null;
+    /**
+     * Badge content. `null` renders no badge; `0` is a
+     * value and renders one.
+     */
+    badge?: string | number | null;
+    /**
+     * Badge intent.
+     */
+    badgeKind?: 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+    /**
+     * Present makes the tool a toggle (`aria-pressed`), which flips on
+     * activation; absent makes it a plain button.
+     */
+    pressed?: boolean;
+    /**
+     * Whether the tool starts disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Native tooltip; defaults to the accessible name.
+     */
+    title?: string;
+    /**
+     * Callback, called after the `action` event.
+     */
+    onclick?: (event: MouseEvent) => void;
+};
+export type ListToolbarView = {
+    /**
+     * View identifier reported by `viewchange`.
+     */
+    id: string;
+    /**
+     * Visible label; omitted falls back to the built-in preset word.
+     */
+    label?: string;
+    /**
+     * Icon name from `icons.js`.
+     */
+    icon?: string | null;
+};
+export type ListToolbarOptions = {
+    /**
+     * Search field configuration; `false` omits it.
+     */
+    search?: ListToolbarSearch | boolean;
+    /**
+     * Initial result count shown in the live status line.
+     */
+    count?: number | null;
+    /**
+     * Formats the count line; omitted
+     * uses the `listToolbar.results` message (`'%1 results'`).
+     */
+    countText?: ((count: number) => string) | null;
+    /**
+     * Shape switch entries; `[]` omits the switch.
+     */
+    views?: Array<string | ListToolbarView>;
+    /**
+     * Initially selected shape; omitted selects the first entry.
+     */
+    view?: string | null;
+    /**
+     * Tool buttons, in display order.
+     */
+    tools?: ListToolbarTool[];
+    /**
+     * Accessible name of the bar; omitted uses the
+     * `listToolbar.label` message.
+     */
+    label?: string | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Search listener.
+     */
+    onsearch?: (event: CustomEvent<{
+        value: string;
+    }>) => void;
+    /**
+     * Shape listener.
+     */
+    onviewchange?: (event: CustomEvent<{
+        view: string;
+        previous: string | null;
+    }>) => void;
+    /**
+     * Tool listener.
+     */
+    onaction?: (event: CustomEvent<{
+        id: string;
+        pressed: boolean | null;
+        tool: Element;
+    }>) => void;
+};
+/**
+ * @typedef {Object} ListToolbarSearch
+ * @property {string} [placeholder] Field placeholder; also names the field. Defaults to the
+ *   `listToolbar.search` message.
+ * @property {string} [value=''] Initial query.
+ * @property {number} [debounce=250] Debounce before `search` is emitted, in milliseconds.
+ * @property {boolean} [clearable=true] Whether the field shows its clear control.
+ */
+/**
+ * @typedef {Object} ListToolbarTool
+ * @property {string} id Stable identifier, reported by `action` and addressed by `setBadge()`.
+ * @property {string} [label=''] Visible label, and the base of the accessible name.
+ * @property {string|null} [icon=null] Icon name from `icons.js`.
+ * @property {string|number|null} [badge=null] Badge content. `null` renders no badge; `0` is a
+ *   value and renders one.
+ * @property {'neutral'|'accent'|'success'|'warning'|'danger'|'info'} [badgeKind='accent'] Badge intent.
+ * @property {boolean} [pressed] Present makes the tool a toggle (`aria-pressed`), which flips on
+ *   activation; absent makes it a plain button.
+ * @property {boolean} [disabled=false] Whether the tool starts disabled.
+ * @property {string} [title] Native tooltip; defaults to the accessible name.
+ * @property {(event: MouseEvent) => void} [onclick] Callback, called after the `action` event.
+ */
+/**
+ * @typedef {Object} ListToolbarView
+ * @property {string} id View identifier reported by `viewchange`.
+ * @property {string} [label] Visible label; omitted falls back to the built-in preset word.
+ * @property {string|null} [icon] Icon name from `icons.js`.
+ */
+/**
+ * @typedef {Object} ListToolbarOptions
+ * @property {ListToolbarSearch|boolean} [search={}] Search field configuration; `false` omits it.
+ * @property {number|null} [count=null] Initial result count shown in the live status line.
+ * @property {((count: number) => string)|null} [countText=null] Formats the count line; omitted
+ *   uses the `listToolbar.results` message (`'%1 results'`).
+ * @property {Array<string|ListToolbarView>} [views=[]] Shape switch entries; `[]` omits the switch.
+ * @property {string|null} [view=null] Initially selected shape; omitted selects the first entry.
+ * @property {ListToolbarTool[]} [tools=[]] Tool buttons, in display order.
+ * @property {string|null} [label=null] Accessible name of the bar; omitted uses the
+ *   `listToolbar.label` message.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{value: string}>) => void} [onsearch] Search listener.
+ * @property {(event: CustomEvent<{view: string, previous: string|null}>) => void} [onviewchange] Shape listener.
+ * @property {(event: CustomEvent<{id: string, pressed: boolean|null, tool: Element}>) => void} [onaction] Tool listener.
+ */
+/**
+ * The bar above a record view: one search field, a live result count, the tools that change what
+ * the list shows, and the shape switch. Every application writes this row, and most of them write
+ * it slightly wrong — this is the composition, not a new primitive. It builds on `Search` and
+ * `badge()` and reimplements neither.
+ *
+ * This is not `Toolbar`, which stays the right component for a row of commands. `Toolbar` is the
+ * APG toolbar pattern — one tab stop, arrow keys between controls — and it collapses whatever no
+ * longer fits into an overflow menu. Both are wrong here: the row contains a text input, where
+ * arrow keys must move the caret, and the first thing an overflow menu would swallow is the badge
+ * saying why the list is showing four rows out of twenty.
+ *
+ * Three properties are the reason it exists:
+ *
+ * - **A tool's badge is part of its accessible name.** A tool showing `2` announces as
+ *   "Filters (2)"; the badge itself is `aria-hidden`, so the number is heard once, as part of the
+ *   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** 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.
+ * @fires ListToolbar#search
+ * @fires ListToolbar#viewchange
+ * @fires ListToolbar#action
+ * @extends {Component<ListToolbarOptions>}
+ */
+export declare class ListToolbar extends Component<ListToolbarOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    /** @type {Map<string, ToolRecord>} */
+    _tools: Map<string, ToolRecord>;
+    _views: {
+        id: string;
+        label?: string;
+        icon?: string | null;
+    }[];
+    _view: any;
+    _count: number;
+    /** @type {Search|null} */
+    _search: Search | null;
+    /** @type {{view: Record<string, any>, capabilities: RecordViewCapabilities}|null} */
+    _bound: {
+        view: Record<string, any>;
+        capabilities: RecordViewCapabilities;
+    } | null;
+    /** @type {AdoptedElement[]} */
+    _adopted: AdoptedElement[];
+    /** @type {AdoptedElement|null} */
+    _chooser: AdoptedElement | null;
+    static cssName: string;
+    /** @type {Readonly<ListToolbarOptions>} */
+    static defaults: Readonly<ListToolbarOptions>;
+    /**
+     * Creates the bar, or turns an existing element into one.
+     * @param {Element|string|null} [target=null] Existing container, selector, or null to create one.
+     * @param {ListToolbarOptions} [options={}] Toolbar options.
+     */
+    constructor(target?: Element | string | null, options?: ListToolbarOptions);
+    /**
+     * Builds the bar. Runs inside the base constructor, so every piece of instance state is
+     * initialized here rather than in a class field.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Replaces the count line. `null` clears it, which is the right answer while a request is in
+     * flight: the number on screen describes the filters the reader has just changed.
+     * @param {number|null} count Result count, or null.
+     * @returns {this}
+     */
+    setCount(count: number | null): this;
+    /**
+     * Returns the count currently shown, or null when the line is empty.
+     * @returns {number|null}
+     */
+    getCount(): number | null;
+    /**
+     * Replaces a tool's badge and its accessible name with it. `null` removes the badge.
+     * @param {string} id Tool id.
+     * @param {string|number|null} value Badge content; `0` is a value, `null` removes it.
+     * @returns {this}
+     */
+    setBadge(id: string, value: string | number | null): this;
+    /**
+     * Sets the pressed state of a toggle tool. A tool declared without `pressed` is a plain button
+     * and is left alone.
+     * @param {string} id Tool id.
+     * @param {boolean} [pressed=true] Next state.
+     * @returns {this}
+     */
+    setPressed(id: string, pressed?: boolean): this;
+    /**
+     * Enables or disables a tool, for instance while its panel is loading.
+     * @param {string} id Tool id.
+     * @param {boolean} [disabled=true] Next state.
+     * @returns {this}
+     */
+    setToolDisabled(id: string, disabled?: boolean): this;
+    /**
+     * Replaces every tool. Elements adopted with `addTool()` and a chooser mounted by `bind()` stay
+     * where they are.
+     * @param {ListToolbarTool[]} tools Tool descriptors.
+     * @returns {this}
+     */
+    setTools(tools: ListToolbarTool[]): this;
+    /**
+     * Returns a tool's button element.
+     * @param {string} id Tool id.
+     * @returns {HTMLButtonElement|null}
+     */
+    getTool(id: string): HTMLButtonElement | null;
+    /**
+     * The element tools are mounted into. Hand it to a view as `fieldControls: {target}` to place
+     * that view's field chooser in this bar without calling `bind()`.
+     *
+     * A control mounted here by somebody else stays theirs: the toolbar puts back what it adopted
+     * through `addTool()` or `bind()`, and everything else goes wherever this slot goes. Use
+     * `addTool()` instead to hand the toolbar an element it should return on `destroy()`.
+     * @returns {HTMLElement}
+     */
+    getToolsElement(): HTMLElement;
+    /**
+     * Adopts a ready-made control into the tools slot. The element's original position is recorded,
+     * and `destroy()` puts it back.
+     * @param {Element} element Control to mount.
+     * @returns {this}
+     */
+    addTool(element: Element): this;
+    /**
+     * Selects a view shape. A value outside `views` is ignored, so the switch can only ever report
+     * one of the shapes it was configured with.
+     * @param {string} view View id.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `viewchange`.
+     * @returns {this}
+     * @fires ListToolbar#viewchange
+     */
+    setView(view: string, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Returns the selected view shape, or null when no shape switch is configured.
+     * @returns {string|null}
+     */
+    getView(): string | null;
+    /**
+     * Returns the current query, or an empty string when the field is omitted.
+     * @returns {string}
+     */
+    getSearch(): string;
+    /**
+     * Sets the query.
+     * @param {string} value Next query.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `search`.
+     * @returns {this}
+     */
+    setSearch(value: string, options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Focuses the search field, for a host that binds a "/" shortcut.
+     * @returns {this}
+     */
+    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.
+     *
+     * 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
+     * itself. See `recordViewCapabilities()` for what is looked for.
+     * @param {object} view A record view, or anything that quacks like one.
+     * @returns {this}
+     */
+    bind(view: object): this;
+    /**
+     * Releases a bound view and returns its field chooser to where it was found.
+     * @returns {this}
+     */
+    unbind(): this;
+    /**
+     * Destroys the search field, returns every adopted control to where it came from, and restores
+     * an enhanced target to the markup it had before the takeover.
+     * @returns {void}
+     */
+    destroy(): void;
+    /** @returns {import('../search/search.js').SearchOptions|null} The options `Search` is built with. */
+    _searchOptions(): import('../search/search.js').SearchOptions | null;
+    /** @returns {(count: number) => string} The count formatter, host-supplied or translated. */
+    _countFormat(): (count: number) => string;
+    /**
+     * Builds one tool button.
+     * @param {Required<ListToolbarTool>} descriptor Normalized descriptor.
+     * @returns {ToolRecord}
+     */
+    _createTool(descriptor: Required<ListToolbarTool>): ToolRecord;
+    /**
+     * Rebuilds a tool's badge and the accessible name that carries it.
+     *
+     * The badge element is `aria-hidden`: the number it shows is already in the button's name, and a
+     * screen reader meeting both would announce "Filters 2 2".
+     * @param {ToolRecord} record Tool record.
+     * @returns {void}
+     */
+    _syncTool(record: ToolRecord): void;
+    /**
+     * Reports a tool activation and flips a toggle tool.
+     * @param {MouseEvent} event Click event.
+     * @returns {void}
+     * @fires ListToolbar#action
+     */
+    _toolClick(event: MouseEvent): void;
+    /**
+     * Selects the clicked shape.
+     * @param {MouseEvent} event Click event.
+     * @returns {void}
+     */
+    _viewClick(event: MouseEvent): void;
+    /** Rebuilds the shape switch, or just its pressed states. @returns {void} */
+    _syncViews(): void;
+    /**
+     * @param {string} id View id.
+     * @returns {string} The translated preset word, or the id when the shape is the host's own.
+     */
+    _viewLabel(id: string): string;
+    /**
+     * Moves a bound view's field chooser into the tools slot. A view that mounted it here itself —
+     * `fieldControls: {target: toolbar.getToolsElement()}` — is already where it belongs and is left
+     * alone, and a view with `fieldControls: false` has none to move.
+     * @param {Record<string, any>} view Bound view.
+     * @returns {void}
+     */
+    _mountFieldControls(view: Record<string, any>): void;
+    /**
+     * Finds a view's field chooser without importing the view, newest accessor first.
+     * @param {Record<string, any>} view Bound view.
+     * @returns {Element|null}
+     */
+    _findFieldControls(view: Record<string, any>): Element | null;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string, ...args: unknown[]): string;
+}
+export type ToolRecord = {
+    /**
+     * Tool id.
+     */
+    id: string;
+    /**
+     * Rendered button.
+     */
+    element: HTMLButtonElement;
+    /**
+     * Name the badge is composed onto.
+     */
+    label: string;
+    /**
+     * Host-supplied tooltip.
+     */
+    title: string | null;
+    /**
+     * Normalized badge content.
+     */
+    badge: string | null;
+    /**
+     * Badge intent.
+     */
+    badgeKind: string;
+    /**
+     * Rendered badge.
+     */
+    badgeEl: HTMLElement | null;
+    /**
+     * Whether the tool carries `aria-pressed`.
+     */
+    toggle: boolean;
+    /**
+     * Current pressed state.
+     */
+    pressed: boolean;
+    /**
+     * Descriptor callback.
+     */
+    onclick: ((event: MouseEvent) => void) | null;
+};
+export type AdoptedElement = {
+    element: Element;
+    parent: Node | null;
+    next: Node | null;
+};
+export type RecordViewCapabilities = {
+    /**
+     * Whether the object publishes the record-view state surface.
+     */
+    isRecordView: boolean;
+    /**
+     * Method that changes the view shape, if any.
+     */
+    setShape: string | null;
+    /**
+     * Method that reads the view shape, if any.
+     */
+    getShape: string | null;
+    /**
+     * Whether the object emits component events.
+     */
+    events: boolean;
+    /**
+     * Whether the object offers its field chooser through a method.
+     */
+    fieldControls: boolean;
+};
+/**
+ * Debounced query change, and the reader pressing Enter.
+ * @event ListToolbar#search
+ * @type {CustomEvent<{value: string}>}
+ */
+/**
+ * Shape switch change.
+ * @event ListToolbar#viewchange
+ * @type {CustomEvent<{view: string, previous: string|null}>}
+ */
+/**
+ * Tool activation. `pressed` is the new state of a toggle tool, and null for a plain button.
+ * @event ListToolbar#action
+ * @type {CustomEvent<{id: string, pressed: boolean|null, tool: Element}>}
+ */
+/**
+ * @typedef {Object} ToolRecord
+ * @property {string} id Tool id.
+ * @property {HTMLButtonElement} element Rendered button.
+ * @property {string} label Name the badge is composed onto.
+ * @property {string|null} title Host-supplied tooltip.
+ * @property {string|null} badge Normalized badge content.
+ * @property {string} badgeKind Badge intent.
+ * @property {HTMLElement|null} badgeEl Rendered badge.
+ * @property {boolean} toggle Whether the tool carries `aria-pressed`.
+ * @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 {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.
+ */
+/**
+ * Describes what `bind()` can wire on an object, by feature rather than by class.
+ *
+ * `ListToolbar` must not import `TableView` or `CardView`: it would hard-depend on two components
+ * a host may not use, and on their current shape. A record view is recognised instead by the state
+ * surface `RecordView` publishes — `setViewState`/`getViewState` plus the component event
+ * methods that carry `sortchange` and friends. Everything beyond that is optional and detected
+ * one method at a time, so a view that grows a shape switch later is wired the day it does.
+ *
+ * Pure: it reads types, never the DOM.
+ * @param {unknown} view Candidate view.
+ * @returns {RecordViewCapabilities}
+ */
+export declare function recordViewCapabilities(view: unknown): RecordViewCapabilities;
+/**
+ * Normalizes badge content. `null`, `undefined`, `false`, and `''` mean no badge; everything else
+ * is text. `0` is a value: a tool that counts something and counts none of it still says so.
+ * @param {unknown} value Badge content.
+ * @returns {string|null}
+ */
+export declare function normalizeToolBadge(value: unknown): string | null;
+/**
+ * Composes a tool's accessible name from its label and badge, so the badge is announced as part of
+ * the control rather than as a second thing to find beside it: "Filters (2)".
+ * @param {string} label Visible label.
+ * @param {string|null} badgeText Normalized badge content.
+ * @param {string} [template='%1 (%2)'] Composition template.
+ * @returns {string}
+ */
+export declare function toolAccessibleName(label: string, badgeText: string | null, template?: string): string;
+/**
+ * Validates and copies tool descriptors.
+ * @param {ListToolbarTool[]} tools Raw descriptors.
+ * @returns {Required<ListToolbarTool>[]} Normalized descriptors.
+ */
+export declare function normalizeTools(tools: ListToolbarTool[]): Required<ListToolbarTool>[];
+/**
+ * Normalizes the shape switch entries. Strings name a built-in preset or a shape of the host's
+ * own; descriptors carry their own label and icon. Nullish and duplicate entries are dropped.
+ * @param {Array<string|ListToolbarView>} views Raw entries.
+ * @returns {Array<{id: string, label?: string, icon?: string|null}>}
+ */
+export declare function normalizeViewList(views: Array<string | ListToolbarView>): Array<{
+    id: string;
+    label?: string;
+    icon?: string | null;
+}>;
+/**
+ * Resolves a requested shape against the configured list. A value the toolbar was not configured
+ * with is never selected — the switch can only report shapes the host said it can render.
+ * @param {Array<{id: string}>} views Normalized entries.
+ * @param {unknown} requested Requested shape.
+ * @param {string|null} current Shape to keep when the request is not on offer; `null` means the
+ *   toolbar is choosing its initial shape and takes the first entry.
+ * @returns {string|null} A configured shape id, or null when there are none.
+ */
+export declare function resolveView(views: Array<{
+    id: string;
+}>, requested: unknown, current: string | null): string | null;
+/**
+ * The text of the count line. Anything that is not a finite number — including `null` while a
+ * request is in flight — is an empty line rather than a stale one.
+ * @param {unknown} count Result count.
+ * @param {(count: number) => string} format Formatter for a real count.
+ * @returns {string}
+ */
+export declare function countLineText(count: unknown, format: (count: number) => string): string;