@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/components/view-settings/view-settings.d.ts

@@ -0,0 +1,879 @@
+import { Component } from '../../core/component.js';
+import { Search } from '../search/search.js';
+import { Select } from '../select/select.js';
+import { Toggle } from '../toggle/toggle.js';
+export type ViewSettingsField = import('../view/record-view.js').ViewField & ViewSettingsFieldExtras;
+export type ViewSettingsFieldExtras = {
+    /**
+     * Field type; decides the glyph, the type name, and whether the
+     * field is offered for grouping. See the built-in type map in the documentation.
+     */
+    type?: string;
+    /**
+     * `false` keeps the field out of the grouping and board choices;
+     * `true` offers it whatever its type. Omitted offers it when its type is discrete.
+     */
+    groupable?: boolean;
+    /**
+     * The panel offers no handle and no hide button for it, such as
+     * the record title; it keeps its place while the other fields arrange around it. This governs
+     * only what the panel offers: a bound view has no such notion, and when the view hides a locked
+     * field itself, the panel shows it under Hidden with Add like any other.
+     */
+    locked?: boolean;
+};
+export type ViewSettingsBoard = {
+    /**
+     * Field whose values are the board's columns.
+     */
+    columnBy: string | null;
+    /**
+     * Field whose values are the swim lanes, or null for none.
+     */
+    swimlaneBy: string | null;
+    /**
+     * Whether columns without cards stay visible.
+     */
+    showEmptyColumns?: boolean;
+};
+export type ViewSettingsBoardOptions = {
+    /**
+     * Initial column field.
+     */
+    columnBy?: string | null;
+    /**
+     * Initial swim-lane field, or null for none.
+     */
+    swimlaneBy?: string | null;
+    /**
+     * Whether columns without cards stay visible.
+     */
+    showEmptyColumns?: boolean;
+    /**
+     * The field ids offered for columns and swim lanes, in this order.
+     * Omitted offers the same fields as the Group section.
+     */
+    fields?: string[];
+};
+export type ViewSettingsState = {
+    /**
+     * Every field id, in order, hidden ones included.
+     */
+    fieldOrder: string[];
+    /**
+     * Hidden field ids, in field order.
+     */
+    hiddenFields: string[];
+    /**
+     * Grouping field, or null for none.
+     */
+    groupBy: string | null;
+    /**
+     * Board settings, or null when the section is omitted.
+     */
+    board: ViewSettingsBoard | null;
+};
+export type ViewSettingsGrouping = {
+    /**
+     * The field ids offered for grouping, in this order. Omitted offers
+     * every field with `groupable !== false` and a discrete type.
+     */
+    fields?: string[];
+};
+export type ViewSettingsSection = 'fields' | 'grouping' | 'board';
+export type ViewSettingsChangeReason = 'order' | 'visibility' | 'group' | 'board';
+export type ViewSettingsOptions = {
+    /**
+     * Field descriptors, in their default order. Bound to a
+     * view, a non-empty list is also the allow-list: the view's other fields are neither listed nor
+     * touched. An empty list takes every field the view has.
+     */
+    fields?: ViewSettingsField[];
+    /**
+     * Preferred field order; missing fields append.
+     */
+    fieldOrder?: string[];
+    /**
+     * Hidden field ids. A field with `visible: false` starts
+     * hidden too; a locked field never does.
+     */
+    hiddenFields?: string[];
+    /**
+     * Initial grouping field.
+     */
+    groupBy?: string | null;
+    /**
+     * The Group section. `false` omits it;
+     * an object restricts the fields it offers.
+     */
+    grouping?: boolean | ViewSettingsGrouping;
+    /**
+     * The Board section (column field,
+     * swim-lane field, show empty columns) with its initial values and, in `fields`, the fields it
+     * offers; `false` omits it.
+     */
+    board?: ViewSettingsBoardOptions | false;
+    /**
+     * Order and presence of the sections. Defaults to
+     * `['fields', 'grouping', 'board']`; a section whose option is `false` is always left out.
+     */
+    sections?: ViewSettingsSection[];
+    /**
+     * Extends or overrides the
+     * built-in type map, keyed by type name.
+     */
+    types?: Record<string, {
+        icon?: string;
+        label?: string;
+    }>;
+    /**
+     * Field count above which the field search is shown.
+     */
+    searchThreshold?: number;
+    /**
+     * Heading level of the section headings.
+     */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /**
+     * Accessible name of the region; omitted uses the
+     * `viewSettings.label` message ("View settings").
+     */
+    label?: string | null;
+    /**
+     * Localized messages.
+     */
+    msg?: Record<string, string> | Record<string, Record<string, string>>;
+    /**
+     * Any change the reader made.
+     */
+    onchange?: (event: CustomEvent<{
+        state: ViewSettingsState;
+        reason: ViewSettingsChangeReason;
+    }>) => void;
+    /**
+     * Field order changed.
+     */
+    onfieldorderchange?: (event: CustomEvent<{
+        order: string[];
+    }>) => void;
+    /**
+     * A field was added or hidden.
+     */
+    onfieldvisibilitychange?: (event: CustomEvent<{
+        visible: string[];
+        hidden: string[];
+    }>) => void;
+    /**
+     * Grouping field changed.
+     */
+    ongroupchange?: (event: CustomEvent<{
+        field: string | null;
+    }>) => void;
+    /**
+     * Board settings changed.
+     */
+    onboardchange?: (event: CustomEvent<{
+        board: ViewSettingsBoard;
+    }>) => void;
+};
+/**
+ * One field as the settings know it: a record-view field descriptor plus what only the settings
+ * need. Any other `ViewField` property (`get`, `render`, `width`, …) is carried along untouched.
+ * @typedef {import('../view/record-view.js').ViewField & ViewSettingsFieldExtras} ViewSettingsField
+ */
+/**
+ * @typedef {Object} ViewSettingsFieldExtras
+ * @property {string} [type='text'] Field type; decides the glyph, the type name, and whether the
+ *   field is offered for grouping. See the built-in type map in the documentation.
+ * @property {boolean} [groupable] `false` keeps the field out of the grouping and board choices;
+ *   `true` offers it whatever its type. Omitted offers it when its type is discrete.
+ * @property {boolean} [locked=false] The panel offers no handle and no hide button for it, such as
+ *   the record title; it keeps its place while the other fields arrange around it. This governs
+ *   only what the panel offers: a bound view has no such notion, and when the view hides a locked
+ *   field itself, the panel shows it under Hidden with Add like any other.
+ */
+/**
+ * @typedef {Object} ViewSettingsBoard
+ * @property {string|null} columnBy Field whose values are the board's columns.
+ * @property {string|null} swimlaneBy Field whose values are the swim lanes, or null for none.
+ * @property {boolean} [showEmptyColumns=true] Whether columns without cards stay visible.
+ */
+/**
+ * The `board` option: the initial board settings plus the fields the board may use.
+ * @typedef {Object} ViewSettingsBoardOptions
+ * @property {string|null} [columnBy=null] Initial column field.
+ * @property {string|null} [swimlaneBy=null] Initial swim-lane field, or null for none.
+ * @property {boolean} [showEmptyColumns=true] Whether columns without cards stay visible.
+ * @property {string[]} [fields] The field ids offered for columns and swim lanes, in this order.
+ *   Omitted offers the same fields as the Group section.
+ */
+/**
+ * @typedef {Object} ViewSettingsState
+ * @property {string[]} fieldOrder Every field id, in order, hidden ones included.
+ * @property {string[]} hiddenFields Hidden field ids, in field order.
+ * @property {string|null} groupBy Grouping field, or null for none.
+ * @property {ViewSettingsBoard|null} board Board settings, or null when the section is omitted.
+ */
+/**
+ * @typedef {Object} ViewSettingsGrouping
+ * @property {string[]} [fields] The field ids offered for grouping, in this order. Omitted offers
+ *   every field with `groupable !== false` and a discrete type.
+ */
+/** @typedef {'fields'|'grouping'|'board'} ViewSettingsSection */
+/** @typedef {'order'|'visibility'|'group'|'board'} ViewSettingsChangeReason */
+/**
+ * @typedef {Object} ViewSettingsOptions
+ * @property {ViewSettingsField[]} [fields=[]] Field descriptors, in their default order. Bound to a
+ *   view, a non-empty list is also the allow-list: the view's other fields are neither listed nor
+ *   touched. An empty list takes every field the view has.
+ * @property {string[]} [fieldOrder=[]] Preferred field order; missing fields append.
+ * @property {string[]} [hiddenFields=[]] Hidden field ids. A field with `visible: false` starts
+ *   hidden too; a locked field never does.
+ * @property {string|null} [groupBy=null] Initial grouping field.
+ * @property {boolean|ViewSettingsGrouping} [grouping=true] The Group section. `false` omits it;
+ *   an object restricts the fields it offers.
+ * @property {ViewSettingsBoardOptions|false} [board=false] The Board section (column field,
+ *   swim-lane field, show empty columns) with its initial values and, in `fields`, the fields it
+ *   offers; `false` omits it.
+ * @property {ViewSettingsSection[]} [sections] Order and presence of the sections. Defaults to
+ *   `['fields', 'grouping', 'board']`; a section whose option is `false` is always left out.
+ * @property {Record<string, {icon?: string, label?: string}>} [types={}] Extends or overrides the
+ *   built-in type map, keyed by type name.
+ * @property {number} [searchThreshold=8] Field count above which the field search is shown.
+ * @property {2|3|4|5|6} [headingLevel=3] Heading level of the section headings.
+ * @property {string|null} [label=null] Accessible name of the region; omitted uses the
+ *   `viewSettings.label` message ("View settings").
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<{state: ViewSettingsState, reason: ViewSettingsChangeReason}>) => void} [onchange]
+ *   Any change the reader made.
+ * @property {(event: CustomEvent<{order: string[]}>) => void} [onfieldorderchange] Field order changed.
+ * @property {(event: CustomEvent<{visible: string[], hidden: string[]}>) => void} [onfieldvisibilitychange]
+ *   A field was added or hidden.
+ * @property {(event: CustomEvent<{field: string|null}>) => void} [ongroupchange] Grouping field changed.
+ * @property {(event: CustomEvent<{board: ViewSettingsBoard}>) => void} [onboardchange] Board settings changed.
+ */
+/**
+ * The content of a "View settings" panel for a record collection: which fields are shown and in
+ * what order, which hidden field to bring back, what the records are grouped by, and which fields
+ * a board uses for its columns and swim lanes. It is content, not a container — the host puts it
+ * in a `Sheet`, a `Dropdown`, or a settings page.
+ *
+ * - **Fields** — the shown fields, in order, each with its type glyph. Rows are rearranged by
+ *   dragging the handle (pointer, touch, or pen) or from the keyboard, and hidden with one button.
+ *   The hidden fields are listed below with an explicit Add button; with more than
+ *   `searchThreshold` fields a search narrows them, and Enter adds the first match.
+ * - **Group by** — a `Select` of the groupable fields, with None.
+ * - **Board** — column field, swim-lane field, and whether empty columns stay.
+ *
+ * Every move is announced through a polite live region ("Owner moved to position 3 of 6").
+ *
+ * `bind(view)` connects a `TableView`, `CardView`, or `KanbanView`: order and visibility are
+ * pushed into the view and the view's own changes come back. Grouping and board settings are only
+ * reported — the host decides how its views apply them.
+ * @fires ViewSettings#change
+ * @fires ViewSettings#fieldorderchange
+ * @fires ViewSettings#fieldvisibilitychange
+ * @fires ViewSettings#groupchange
+ * @fires ViewSettings#boardchange
+ * @extends {Component<ViewSettingsOptions>}
+ */
+export declare class ViewSettings extends Component<ViewSettingsOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    /** @type {ViewSettingsField[]} */
+    _fields: ViewSettingsField[];
+    _ownIds: Set<string>;
+    _order: any;
+    _hidden: Set<string>;
+    _groupBy: any;
+    _board: ViewSettingsBoard;
+    /** @type {string[]|null} */
+    _boardFields: string[] | null;
+    _sections: ViewSettingsSection[];
+    _query: any;
+    /** @type {Search|null} */
+    _search: Search | null;
+    /** @type {Select|null} */
+    _groupSelect: Select | null;
+    /** @type {Select|null} */
+    _columnSelect: Select | null;
+    /** @type {Select|null} */
+    _laneSelect: Select | null;
+    /** @type {Toggle|null} */
+    _emptyToggle: Toggle | null;
+    /** @type {{view: Record<string, any>, controller: AbortController}|null} */
+    _bound: {
+        view: Record<string, any>;
+        controller: AbortController;
+    } | null;
+    _syncing: boolean;
+    _rendering: boolean;
+    /** @type {{id: string, original: string[]}|null} */
+    _grab: {
+        id: string;
+        original: string[];
+    } | null;
+    /** @type {DragState|null} */
+    _drag: DragState | null;
+    _announceToken: number;
+    _level: 2 | 3 | 4 | 5 | 6;
+    _instructionsId: string;
+    static cssName: string;
+    /** @type {Readonly<ViewSettingsOptions>} */
+    static defaults: Readonly<ViewSettingsOptions>;
+    /**
+     * Builds the panel. Runs inside the base constructor, so every piece of instance state is
+     * initialized here rather than in a class field.
+     * @returns {HTMLElement}
+     */
+    render(): HTMLElement;
+    /**
+     * Returns the current settings as a JSON-safe snapshot.
+     * @returns {ViewSettingsState}
+     */
+    getState(): ViewSettingsState;
+    /**
+     * Applies part of a state. Unknown field ids are ignored, missing ones append, and a locked
+     * field stays shown. Each part that actually changes emits its own event unless `silent`.
+     * A keyboard pick-up or pointer drag in progress is canceled first.
+     * @param {Partial<ViewSettingsState>} partial State to apply.
+     * @param {{silent?: boolean}} [options={}] Set `silent` to suppress events.
+     * @returns {this}
+     * @fires ViewSettings#fieldorderchange
+     * @fires ViewSettings#fieldvisibilitychange
+     * @fires ViewSettings#groupchange
+     * @fires ViewSettings#boardchange
+     */
+    setState(partial: Partial<ViewSettingsState>, { silent }?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Replaces the field descriptors, keeping order, visibility, grouping, and board settings for
+     * every id that still exists.
+     *
+     * While a view is bound, the view owns the field list: change it with the view's own
+     * `setFields()` and the panel follows through `statechange`. A `setFields()` here is not pushed
+     * to the view and lasts only until the view's next change.
+     * @param {ViewSettingsField[]} fields Next fields.
+     * @returns {this}
+     */
+    setFields(fields: ViewSettingsField[]): this;
+    /**
+     * Returns the field descriptors in their current order.
+     * @returns {ViewSettingsField[]}
+     */
+    getFields(): ViewSettingsField[];
+    /**
+     * Shows a hidden field at the end of the shown list.
+     * @param {string} id Field id.
+     * @returns {this}
+     * @fires ViewSettings#fieldvisibilitychange
+     */
+    showField(id: string): this;
+    /**
+     * Hides a shown field. A locked field and the last shown field cannot be hidden.
+     * @param {string} id Field id.
+     * @returns {this}
+     * @fires ViewSettings#fieldvisibilitychange
+     */
+    hideField(id: string): this;
+    /**
+     * Moves a shown field to a position among the movable shown fields (locked ones keep theirs).
+     * @param {string} id Field id.
+     * @param {number} index Zero-based target position among the movable shown fields.
+     * @returns {this}
+     * @fires ViewSettings#fieldorderchange
+     */
+    moveField(id: string, index: number): this;
+    /**
+     * Connects a record view (`TableView`, `CardView`, `KanbanView`, or anything exposing the
+     * `RecordView` state surface). The view's fields and state are read now; order and visibility
+     * changes made here are pushed through `setFieldOrder()` and `setFieldVisible()`; and the view's
+     * own `statechange` is followed, so a column hidden from a table header disappears here too.
+     * The view's labels and types win over the panel's own descriptors, which supply only what the
+     * view lacks (`locked`, `groupable`, a type the view leaves at its `'text'` default). While
+     * bound, the view owns the field list; see `setFields()`.
+     *
+     * Grouping and board settings are never applied to the view — they are emitted, and the host
+     * decides (a `CardView` is re-created or given a new `groupBy`, a `KanbanView` its axes). A
+     * view's own `groupBy`, `columnBy`, and `swimlaneBy` options are adopted when they name fields.
+     * @param {object} view Record view.
+     * @param {{board?: ViewSettingsBoard|false}} [options={}] `board` replaces the board settings
+     *   read from the view.
+     * @returns {this}
+     */
+    bind(view: object, options?: {
+        board?: ViewSettingsBoard | false;
+    }): this;
+    /**
+     * Releases a bound view. The settings keep their current state.
+     * @returns {this}
+     */
+    unbind(): this;
+    /**
+     * Focuses the field search, or the first control of the shown list when there is no search.
+     * @returns {this}
+     */
+    focus(): this;
+    /**
+     * Destroys the nested controls, releases a bound view, and restores an enhanced target.
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * @param {string} text Heading text.
+     * @param {number} [offset=0] Levels below the section heading.
+     * @param {string} [className='zx-view-settings__heading'] Heading class.
+     * @returns {{element: HTMLElement, id: string}}
+     */
+    _heading(text: string, offset?: number, className?: string): {
+        element: HTMLElement;
+        id: string;
+    };
+    /** @returns {HTMLElement} The Fields section. */
+    _buildFieldsSection(): HTMLElement;
+    /** @returns {HTMLElement} The Group section. */
+    _buildGroupSection(): HTMLElement;
+    /** @returns {HTMLElement} The Board section. */
+    _buildBoardSection(): HTMLElement;
+    /**
+     * Creates or removes the field search to match the field count.
+     * @returns {void}
+     */
+    _syncSearch(): void;
+    /**
+     * Rebuilds both field lists, then puts focus back: on the control asked for, or else on the same
+     * control of the same field when focus was inside the lists. A pointer drag in progress ends —
+     * the rows it measured are about to be replaced — and so does a keyboard pick-up, unless the
+     * redraw is that pick-up's own step.
+     * @param {{id: string, part: 'handle'|'hide'|'add'}|null} [focus=null] Control to focus afterwards.
+     * @param {{keepGrab?: boolean}} [options={}] `keepGrab` marks a redraw made by the pick-up itself.
+     * @returns {void}
+     */
+    _renderFields(focus?: {
+        id: string;
+        part: 'handle' | 'hide' | 'add';
+    } | null, { keepGrab }?: {
+        keepGrab?: boolean;
+    }): void;
+    /**
+     * @param {ViewSettingsField} field Field.
+     * @param {boolean} canHideAny Whether more than one field is shown.
+     * @returns {HTMLElement}
+     */
+    _shownRow(field: ViewSettingsField, canHideAny: boolean): HTMLElement;
+    /**
+     * @param {ViewSettingsField} field Field.
+     * @returns {HTMLElement}
+     */
+    _hiddenRow(field: ViewSettingsField): HTMLElement;
+    /**
+     * The type glyph a row shows before its label. The glyph is decorative; the type name is the
+     * element's `title` for the pointer and visually hidden text for everyone else. It follows the
+     * label in the source, so a row reads "Owner, Text" — the glyph is placed first by CSS.
+     * @param {string|undefined} type Field type.
+     * @returns {HTMLElement}
+     */
+    _typeBadge(type: string | undefined): HTMLElement;
+    /** @param {string|undefined} type @returns {Element} The type's decorative glyph. */
+    _typeGlyph(type: string | undefined): Element;
+    /** @param {string|undefined} type @returns {string} The translated type name. */
+    _typeLabel(type: string | undefined): string;
+    /** @param {SelectFieldItem} item @returns {HTMLElement} Option content with the type glyph. */
+    _optionContent(item: SelectFieldItem): HTMLElement;
+    /** Refreshes the grouping and board controls from state. @returns {void} */
+    _syncGroupControls(): void;
+    /** @param {string} query @returns {void} */
+    _setQuery(query: string): void;
+    /** Adds the first hidden field matching the query; Enter in the search. @returns {void} */
+    _addFirstMatch(): void;
+    /**
+     * Shows a field from the hidden list and moves focus somewhere sensible.
+     * @param {string} id Field id.
+     * @param {boolean} fromButton Whether the Add button was used (focus moves to the next one).
+     * @returns {void}
+     */
+    _addFromPanel(id: string, fromButton: boolean): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _onHiddenClick(event: MouseEvent): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _onShownClick(event: MouseEvent): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _onHandleKeydown(event: KeyboardEvent): void;
+    /** A picked-up field is dropped where it is when focus leaves it. @param {FocusEvent} event @returns {void} */
+    _onHandleFocusout(event: FocusEvent): void;
+    /**
+     * @param {string} id Field id.
+     * @param {number} target Target index among movable fields.
+     * @param {boolean} commit Whether the move is final (emitted) or part of a pick-up.
+     * @returns {void}
+     */
+    _moveFromKeyboard(id: string, target: number, commit: boolean): void;
+    /** @param {string} id @returns {void} */
+    _pickUp(id: string): void;
+    /**
+     * @param {{id: string, part: 'handle'|'hide'|'add'}|null} [focus] Control to focus afterwards;
+     *   omitted keeps focus on the dropped row's handle when it had it.
+     * @returns {void}
+     */
+    _drop(focus?: {
+        id: string;
+        part: 'handle' | 'hide' | 'add';
+    } | null): void;
+    /** @returns {void} */
+    _cancelGrab(): void;
+    /**
+     * Ends whatever reordering is in progress before state changes from outside: a keyboard
+     * pick-up returns the row to where it was, and a pointer drag is dropped nowhere.
+     * @returns {void}
+     */
+    _settle(): void;
+    /** @param {string} id Field whose move was canceled. @returns {void} */
+    _announceCanceled(id: string): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _onPointerDown(event: PointerEvent): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _onPointerMove(event: PointerEvent): void;
+    /** @param {PointerEvent} event @returns {void} */
+    _onPointerUp(event: PointerEvent): void;
+    /**
+     * Starts a pointer drag: the dragged row follows the pointer, and a frame loop scrolls the
+     * nearest scroll container while the pointer rests near its top or bottom edge.
+     * @param {DragState} drag Press being promoted.
+     * @returns {void}
+     */
+    _beginDrag(drag: DragState): void;
+    /** @param {DragState} drag Active drag. @returns {void} */
+    _scheduleAutoScroll(drag: DragState): void;
+    /**
+     * Moves the dragged row under the pointer — compensating for any scroll since the drag began —
+     * and updates the insertion line.
+     * @param {DragState} drag Active drag.
+     * @returns {void}
+     */
+    _positionDrag(drag: DragState): void;
+    /**
+     * Resolves and marks the insertion point. The other rows are measured on every call rather than
+     * once at the start, so a list scrolled mid-drag still drops where the line says.
+     * @param {DragState} drag Active drag.
+     * @param {number} y Pointer client y.
+     * @returns {void}
+     */
+    _updateDropTarget(drag: DragState, y: number): void;
+    /** @param {DragState} drag @returns {void} */
+    _endDrag(drag: DragState): void;
+    /** @param {boolean} [announce=false] Whether to say so. @returns {void} */
+    _cancelDrag(announce?: boolean): void;
+    /** @param {string|null} field @returns {void} */
+    _setGroup(field: string | null): void;
+    /** @param {Partial<ViewSettingsBoard>} patch @returns {void} */
+    _setBoard(patch: Partial<ViewSettingsBoard>): void;
+    /** @param {boolean} [withChange=true] Whether `change` follows. @returns {void} */
+    _emitOrder(withChange?: boolean): void;
+    /** @returns {void} */
+    _emitVisibility(): void;
+    /** @returns {void} */
+    _emitGroup(): void;
+    /** @returns {void} */
+    _emitBoard(): void;
+    /** @param {ViewSettingsChangeReason} reason @returns {void} */
+    _emitChange(reason: ViewSettingsChangeReason): void;
+    /** Pushes order and visibility into the bound view. @returns {void} */
+    _pushToView(): void;
+    /**
+     * Reads fields, order, and visibility from the bound view. Silent: the view reported its own
+     * change already, and echoing it from here would hand the host the same change twice.
+     * @param {boolean} withFields Whether the field descriptors are re-read too.
+     * @returns {void}
+     */
+    _pullFromView(withFields: boolean): void;
+    /** @returns {string[]} Locked field ids. */
+    _lockedIds(): string[];
+    /** @returns {string[]} Shown, movable field ids in order. */
+    _movableIds(): string[];
+    /** @param {string} id @returns {ViewSettingsField|undefined} */
+    _field(id: string): ViewSettingsField | undefined;
+    /** @param {string} id @returns {boolean} Whether the field may be hidden now. */
+    _canHide(id: string): boolean;
+    /**
+     * Whether `candidate` keeps a hide button once `removed` is hidden.
+     * @param {string} candidate Field id.
+     * @param {string} removed Field being hidden.
+     * @returns {boolean}
+     */
+    _canHideAfter(candidate: string, removed: string): boolean;
+    /** @param {string} id @returns {HTMLElement|null} The shown row for a field. */
+    _row(id: string): HTMLElement | null;
+    /** @param {string} id @returns {{position: number, total: number}} 1-based place in the shown list. */
+    _position(id: string): {
+        position: number;
+        total: number;
+    };
+    /** @param {string} id @returns {void} */
+    _announceMove(id: string): void;
+    /** @returns {{id: string, part: 'handle'|'hide'|'add'}|null} The focused row control, if any. */
+    _activePart(): {
+        id: string;
+        part: 'handle' | 'hide' | 'add';
+    } | null;
+    /**
+     * @param {Element|null} element A focus target.
+     * @returns {{id: string, part: 'handle'|'hide'|'add'}|null} The row control it is, if any.
+     */
+    _partOf(element: Element | null): {
+        id: string;
+        part: 'handle' | 'hide' | 'add';
+    } | null;
+    /** @param {{id: string, part: 'handle'|'hide'|'add'}} focus @returns {void} */
+    _focusPart(focus: {
+        id: string;
+        part: 'handle' | 'hide' | 'add';
+    }): void;
+    /** @param {string} message @returns {void} */
+    _announce(message: string): void;
+    /**
+     * 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 DragState = {
+    /**
+     * Field being dragged.
+     */
+    id: string;
+    /**
+     * Pointer that pressed the handle.
+     */
+    pointerId: number;
+    /**
+     * Pointer-down client x.
+     */
+    startX: number;
+    /**
+     * Pointer-down client y.
+     */
+    startY: number;
+    /**
+     * Whether the press has travelled far enough to be a drag.
+     */
+    active: boolean;
+    /**
+     * Whether the drag is being torn down.
+     */
+    ending: boolean;
+    /**
+     * Captured handle.
+     */
+    handle: HTMLElement;
+    /**
+     * Latest pointer client y.
+     */
+    y: number;
+    /**
+     * Dragged row.
+     */
+    row: HTMLElement;
+    /**
+     * Target index among the movable fields.
+     */
+    target: number | null;
+    /**
+     * Nearest scroll container of the list.
+     */
+    scroller: Element | null;
+    /**
+     * Its scroll position when the drag began.
+     */
+    startScroll: number;
+    /**
+     * Its scroll position when the row was last placed.
+     */
+    lastScroll: number;
+    /**
+     * Pending auto-scroll frame, or 0.
+     */
+    frame: number;
+};
+export type SelectFieldItem = {
+    ID: string;
+    name: string;
+    type: string;
+};
+/**
+ * Any change the reader made, after the specific event.
+ * @event ViewSettings#change
+ * @type {CustomEvent<{state: ViewSettingsState, reason: ViewSettingsChangeReason}>}
+ */
+/**
+ * The field order changed.
+ * @event ViewSettings#fieldorderchange
+ * @type {CustomEvent<{order: string[]}>}
+ */
+/**
+ * A field was added or hidden.
+ * @event ViewSettings#fieldvisibilitychange
+ * @type {CustomEvent<{visible: string[], hidden: string[]}>}
+ */
+/**
+ * The grouping field changed; null is no grouping.
+ * @event ViewSettings#groupchange
+ * @type {CustomEvent<{field: string|null}>}
+ */
+/**
+ * A board setting changed.
+ * @event ViewSettings#boardchange
+ * @type {CustomEvent<{board: ViewSettingsBoard}>}
+ */
+/**
+ * @typedef {Object} DragState
+ * @property {string} id Field being dragged.
+ * @property {number} pointerId Pointer that pressed the handle.
+ * @property {number} startX Pointer-down client x.
+ * @property {number} startY Pointer-down client y.
+ * @property {boolean} active Whether the press has travelled far enough to be a drag.
+ * @property {boolean} ending Whether the drag is being torn down.
+ * @property {HTMLElement} handle Captured handle.
+ * @property {number} y Latest pointer client y.
+ * @property {HTMLElement} row Dragged row.
+ * @property {number|null} target Target index among the movable fields.
+ * @property {Element|null} scroller Nearest scroll container of the list.
+ * @property {number} startScroll Its scroll position when the drag began.
+ * @property {number} lastScroll Its scroll position when the row was last placed.
+ * @property {number} frame Pending auto-scroll frame, or 0.
+ */
+/** @typedef {{ID: string, name: string, type: string}} SelectFieldItem */
+/**
+ * Validates and clones field descriptors: ids become trimmed strings, a missing label is derived
+ * from the id, `type` defaults to `'text'`, and `locked` and `groupable` are read as booleans.
+ * @param {ViewSettingsField[]} fields Raw descriptors.
+ * @returns {ViewSettingsField[]}
+ */
+export declare function normalizeViewSettingsFields(fields: ViewSettingsField[]): ViewSettingsField[];
+/**
+ * Resolves a field type to its glyph and English name, through the host's `types` overrides, the
+ * alias table (`int` → number, `enum` → select, …), and the built-in map. An unknown type keeps
+ * its own name and the text glyph, so a server's new type still shows something sensible.
+ * @param {string|null|undefined} type Field type.
+ * @param {Record<string, {icon?: string, label?: string}>|null} [overrides=null] Host overrides.
+ * @returns {{type: string, icon: string, label: string, key: string|null}} `key` is the message
+ *   key of a built-in label, null for a host-supplied or derived one.
+ */
+export declare function resolveFieldType(type: string | null | undefined, overrides?: Record<string, {
+    icon?: string;
+    label?: string;
+}> | null): {
+    type: string;
+    icon: string;
+    label: string;
+    key: string | null;
+};
+/**
+ * Whether a type sorts records into a few named buckets — what grouping, board columns, and swim
+ * lanes need: text, select (and enum), status, priority, boolean, and entity.
+ * @param {string|null|undefined} type Field type.
+ * @returns {boolean}
+ */
+export declare function isDiscreteFieldType(type: string | null | undefined): boolean;
+/**
+ * The field ids offered for grouping. `grouping.fields` restricts and orders them; otherwise every
+ * field is offered whose `groupable` is `true`, or is not `false` and whose type is discrete.
+ * @param {ViewSettingsField[]} fields Normalized fields.
+ * @param {boolean|ViewSettingsGrouping|null|undefined} grouping The `grouping` option.
+ * @returns {string[]}
+ */
+export declare function groupingFieldIds(fields: ViewSettingsField[], grouping: boolean | ViewSettingsGrouping | null | undefined): string[];
+/**
+ * Whether a field matches a search query. Case and accents are ignored, every word must appear,
+ * and the label, the id, and the type name are all searched — "date" finds every date field.
+ * @param {{id: string, label?: string}} field Field.
+ * @param {string} query Search text.
+ * @param {string} [typeLabel=''] The field's type name.
+ * @returns {boolean}
+ */
+export declare function matchesFieldQuery(field: {
+    id: string;
+    label?: string;
+}, query: string, typeLabel?: string): boolean;
+/**
+ * Moves one shown field to a position among the movable shown fields. Locked fields keep their
+ * slots and hidden fields keep their place in the full order; the result is a new full order.
+ * An unknown, hidden, or locked id returns an unchanged copy.
+ * @param {string[]} order Full field order.
+ * @param {Iterable<string>} hidden Hidden field ids.
+ * @param {Iterable<string>} locked Locked field ids.
+ * @param {string} id Field to move.
+ * @param {number} index Target position among the movable shown fields; clamped.
+ * @returns {string[]}
+ */
+export declare function moveVisibleField(order: string[], hidden: Iterable<string>, locked: Iterable<string>, id: string, index: number): string[];
+/**
+ * Shows a hidden field at the end of the shown fields: it leaves the hidden set and moves to just
+ * after the last shown field, so "Add" puts it where the reader is looking.
+ * @param {string[]} order Full field order.
+ * @param {Iterable<string>} hidden Hidden field ids.
+ * @param {string} id Field to show.
+ * @returns {{order: string[], hidden: string[]}}
+ */
+export declare function showFieldInOrder(order: string[], hidden: Iterable<string>, id: string): {
+    order: string[];
+    hidden: string[];
+};
+/**
+ * The gap a pointer is over, given the vertical midpoints of the rows: 0 is above the first row,
+ * `middles.length` below the last.
+ * @param {number[]} middles Row midpoints, top to bottom.
+ * @param {number} y Pointer position.
+ * @returns {number}
+ */
+export declare function dropGapIndex(middles: number[], y: number): number;
+/**
+ * Merges a bound view's field with the panel's own descriptor for it. The view's label and type
+ * win; the panel's descriptor supplies only what the view lacks — `locked`, `groupable`, and a
+ * type where the view reports just the `'text'` default a record view fills in for none.
+ * @param {ViewSettingsField|null} own The panel's descriptor, if it has one.
+ * @param {ViewSettingsField} field The view's descriptor.
+ * @returns {ViewSettingsField}
+ */
+export declare function mergeViewField(own: ViewSettingsField | null, field: ViewSettingsField): ViewSettingsField;
+/**
+ * How far a drag should scroll its container this frame: up when the pointer is within `edge`
+ * pixels of the top and the list continues above, down likewise at the bottom, otherwise 0.
+ * @param {number} y Pointer client y.
+ * @param {{top: number, bottom: number}} edges The container's visible top and bottom.
+ * @param {{top: number, bottom: number}} list The list's client rectangle.
+ * @param {number} [edge=32] Width of the edge band in pixels.
+ * @param {number} [step=12] Pixels per frame.
+ * @returns {number}
+ */
+export declare function autoScrollDelta(y: number, edges: {
+    top: number;
+    bottom: number;
+}, list: {
+    top: number;
+    bottom: number;
+}, edge?: number, step?: number): number;
+/**
+ * Resolves the sections to render, in order: the `sections` option (or the default order) with
+ * unknown and duplicate names dropped, and the grouping or board section removed when its option
+ * is `false`.
+ * @param {unknown} sections The `sections` option.
+ * @param {{grouping?: unknown, board?: unknown}} options The `grouping` and `board` options.
+ * @returns {ViewSettingsSection[]}
+ */
+export declare function normalizeSections(sections: unknown, options?: {
+    grouping?: unknown;
+    board?: unknown;
+}): ViewSettingsSection[];
+/**
+ * Normalizes board settings. `false` and null mean no board. With `ids`, a field that does not
+ * exist becomes null, and a swim-lane field equal to the column field is dropped.
+ * @param {unknown} board Raw board settings.
+ * @param {string[]|null} [ids=null] Known field ids, or null to skip the check.
+ * @returns {ViewSettingsBoard|null}
+ */
+export declare function normalizeBoard(board: unknown, ids?: string[] | null): ViewSettingsBoard | null;