@zeyos/zx 4.3.4 → 5.0.0

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

@@ -3,6 +3,7 @@ export type TableRow = Record<string, any>;
 export type TableSortDirection = 'asc' | 'desc';
 export type TableSelectionMode = false | 'single' | 'multi';
 export type TableEditMode = false | 'cell' | 'row';
+export type TableVariant = 'default' | 'plain';
 export type TableEditorType = 'text' | 'number' | 'select' | 'date' | 'checkbox' | 'textarea' | 'custom';
 export type TableColumnType = 'text' | 'number' | 'currency' | 'percent' | 'unit';
 export type TableEditorOption = {
@@ -25,6 +26,29 @@ export type TableHierarchyOptions = {
      */
     expanded?: boolean | unknown[];
 };
+export type TableRowKind = {
+    /**
+     * Draw the row as a single cell across every rendered column — a
+     * section heading rather than a record. The cell is a `<th scope="colgroup">`, not a `<td>`,
+     * because it labels the columns of the rows beneath it and a screen reader walking the table
+     * should meet it as a heading rather than as a value. A spanning row carries no selection
+     * checkbox, is never editable, and is skipped by `rowReorder`; it still emits `rowclick` and still
+     * participates in `getData()` and `updateRow()`.
+     */
+    span?: boolean;
+    /**
+     * Content
+     * of the spanning cell. Omitted, the cell falls back to the row's raw value for the first visible
+     * column, which is what a host otherwise writes by hand.
+     */
+    render?: (row: TableRow, index: number) => Node | string | number | null | undefined;
+    /**
+     * Space-separated classes added to the row, on top of `rowClass`. Zx
+     * ships no section look: a billing section is not a kanban swimlane, so the tint, the weight and
+     * the rule above it are the host's to decide.
+     */
+    class?: string;
+};
 export type TableEditorApi = {
     /**
      * Value the cell holds when the editor opens.
@@ -53,9 +77,16 @@ export type TableColumn = {
      */
     id: string;
     /**
-     * Visible header label.
+     * Visible header label. An empty label leaves the header blank — an
+     * icon or actions column — and the header is then named by `ariaLabel`, or by the id.
      */
     label: string;
+    /**
+     * Accessible name of the column header, and the name the column
+     * chooser and the cell editors use. Needed when `label` is empty or terse (`'#'`); include the
+     * visible label's words in it when there is one.
+     */
+    ariaLabel?: string;
     /**
      * Whether the header changes the active sort.
      */
@@ -207,10 +238,31 @@ export type TableOptions = {
      * Additional row class callback.
      */
     rowClass?: ((row: TableRow) => string) | null;
+    /**
+     * Row property or callback
+     * naming each row's kind — the `type` on a ZeyOS transaction line, where one value is a position
+     * carrying quantities and amounts and another is a section heading that groups the positions under
+     * it. `null`, the default, renders every row exactly as before.
+     */
+    rowKind?: string | ((row: TableRow) => unknown) | null;
+    /**
+     * Presentation per kind, keyed by the
+     * resolved kind coerced to a string. A kind with no entry here renders as an ordinary row. While
+     * any row in the current data resolves to a `span` kind the header sort controls are withheld and
+     * `setSort()` is inert: sorting a grouped table scatters the positions out of their sections, and
+     * doing that silently is worse than not offering it. `sortMode: 'server'` still owns its own order.
+     */
+    rowKinds?: Record<string, TableRowKind> | null;
     /**
      * Whether alternate rows use the zebra background.
      */
     zebra?: boolean;
+    /**
+     * Frame treatment. `'default'` draws the table's own
+     * bordered box; `'plain'` is for a table inside a card or panel that already draws one — no outer
+     * frame, no header band, no zebra, hairline row dividers. Reflected as `data-variant` on the root.
+     */
+    variant?: TableVariant;
     /**
      * Inline editing mode. `'cell'` edits one cell, `'row'`
      * opens every editable cell of the row together and commits them as a unit. Editing is completely
@@ -487,6 +539,10 @@ export declare class Table extends Component<TableOptions> {
     _original: import("../../core/dom.js").TargetSnapshot;
     _columns: any[] | TableColumn[];
     _data: any[] | TableRow[];
+    _rowKind: string | ((row: TableRow) => unknown);
+    _rowKinds: Record<string, TableRowKind>;
+    _spanning: boolean;
+    _sortWarned: boolean;
     _selected: Set<any>;
     _selectionAnchorId: any;
     _sort: any;
@@ -533,6 +589,7 @@ export declare class Table extends Component<TableOptions> {
     _columnList: HTMLElement;
     _selectAll: HTMLElement;
     _headers: Map<any, any>;
+    _headerSpanning: boolean;
     _hierarchyMeta: Map<unknown, TableHierarchyEntry>;
     static cssName: string;
     /** @type {TableOptions} */
@@ -678,6 +735,10 @@ export declare class Table extends Component<TableOptions> {
     /**
      * Activates a column sort. Local mode stably reorders data; server mode only updates the
      * header state and emits the request event.
+     *
+     * Inert while the data holds a spanning row: a sort would scatter the positions out of the
+     * sections that group them, in either sort mode. The header withholds its controls for the same
+     * reason, so nothing on screen invites the call.
      * @param {string} id Column id.
      * @param {TableSortDirection} [dir] Direction; omitted toggles the current column.
      * @param {{silent?: boolean}} [options={}] Event options.
@@ -896,6 +957,28 @@ export declare class Table extends Component<TableOptions> {
     destroy(): void;
     /** @returns {TableColumn[]} */
     _visibleColumns(): TableColumn[];
+    /**
+     * Whether a row draws as one cell across the table instead of as a record.
+     * @param {TableRow} row Row to classify.
+     * @returns {boolean}
+     */
+    _isSpanningRow(row: TableRow): boolean;
+    /**
+     * Whether any row in the current data — not only the rendered prefix — spans. This is what
+     * withholds the sort controls, and the reader must not be offered a control that the next
+     * `growBy()` would have to take away again.
+     * @returns {boolean}
+     */
+    _hasSpanningRow(): boolean;
+    /**
+     * How many cells one row occupies: every visible column plus the structural columns the table
+     * renders beside them. Shared by the spanning cell and the empty-state cell so the two can never
+     * disagree about the table's width.
+     * @returns {number}
+     */
+    _spanColspan(): number;
+    /** @returns {TableRow[]} Rendered rows that can carry a selection; spanning rows cannot. */
+    _selectableData(): TableRow[];
     /** @returns {HTMLElement} */
     _createColumnControls(): HTMLElement;
     /**
@@ -1091,6 +1174,8 @@ export declare class Table extends Component<TableOptions> {
     _emitRowToggle(id: unknown, expanded: boolean): void;
     /** Keeps the reader's current expansion state limited to branches still present in the data. */
     _reconcileExpanded(): void;
+    /** @returns {Set<unknown>} Ids of every row in the data that may hold a selection. */
+    _selectableIds(): Set<unknown>;
     /** @returns {boolean} Whether selection changed. */
     _pruneSelection(): boolean;
     /** @param {TableRow} row @returns {unknown} */
@@ -1141,6 +1226,79 @@ export declare class Table extends Component<TableOptions> {
  * @event Table#editinvalid
  * @type {CustomEvent<TableEditInvalidDetail>}
  */
+/**
+ * Resolves a row's kind through the `rowKind` accessor and coerces it to the string `rowKinds` is
+ * keyed by.
+ *
+ * Only `null` and `undefined` mean "no kind". `0` and `''` are kinds like any other: a ZeyOS
+ * transaction line uses `0` for a position and `1` for a section, so a falsy test here would render
+ * every position as though the table had never been told about kinds at all.
+ * @param {TableRow} row Row to classify.
+ * @param {string|((row: TableRow) => unknown)|null|undefined} rowKind Field name or accessor.
+ * @returns {string|null} The kind as a string, or null when there is none.
+ */
+export declare function resolveRowKind(row: TableRow, rowKind: string | ((row: TableRow) => unknown) | null | undefined): string | null;
+/**
+ * Looks one resolved kind up in the `rowKinds` map.
+ *
+ * Own properties only: a kind read out of server data could just as easily be `toString` or
+ * `constructor`, and inherited members of `Object.prototype` are not configuration.
+ * @param {Record<string, TableRowKind>|null|undefined} rowKinds Kind map.
+ * @param {string|null} kind Resolved kind.
+ * @returns {TableRowKind|null} Matching entry, or null.
+ */
+export declare function resolveRowKindSpec(rowKinds: Record<string, TableRowKind> | null | undefined, kind: string | null): TableRowKind | null;
+/**
+ * Whether a row draws as one spanning cell under the given configuration.
+ * @param {TableRow} row Row to classify.
+ * @param {string|((row: TableRow) => unknown)|null|undefined} rowKind Field name or accessor.
+ * @param {Record<string, TableRowKind>|null|undefined} rowKinds Kind map.
+ * @returns {boolean}
+ */
+export declare function isSpanningRow(row: TableRow, rowKind: string | ((row: TableRow) => unknown) | null | undefined, rowKinds: Record<string, TableRowKind> | null | undefined): boolean;
+/**
+ * Whether a data set holds a row that spans — the question that decides whether `Table` offers its
+ * sort controls at all.
+ *
+ * Asked of the whole data rather than of the rendered prefix: with `growing` on, a sort control
+ * that disappeared the moment the reader pressed "show 20 more" would be worse than one that was
+ * never there. Asked again on every data change, so a filter that removes the last section gives
+ * the sort back.
+ * @param {TableRow[]} rows Rows to scan.
+ * @param {string|((row: TableRow) => unknown)|null|undefined} rowKind Field name or accessor.
+ * @param {Record<string, TableRowKind>|null|undefined} rowKinds Kind map.
+ * @returns {boolean}
+ */
+export declare function hasSpanningRow(rows: TableRow[], rowKind: string | ((row: TableRow) => unknown) | null | undefined, rowKinds: Record<string, TableRowKind> | null | undefined): boolean;
+/**
+ * How many cells one table row occupies.
+ *
+ * `selectable: 'multi'` and `rowReorder` each render a `<col>` and a leading cell of their own, and
+ * a spanning cell that ignored them would leave the row one or two columns short — the table would
+ * still lay out, silently and wrongly. `selectable: 'single'` adds no column: the whole row is the
+ * control there.
+ * @param {number} columnCount Number of visible data columns.
+ * @param {{selectable?: TableSelectionMode, rowReorder?: boolean}} [structure={}] Structural columns.
+ * @returns {number} Colspan covering every rendered cell, never below 1.
+ */
+export declare function tableSpanColspan(columnCount: number, structure?: {
+    selectable?: TableSelectionMode;
+    rowReorder?: boolean;
+}): number;
+/**
+ * Content for a spanning row's single cell.
+ *
+ * Without a `render` the cell shows the row's raw value for the first visible column — the same
+ * thing a host writes by hand today. Deliberately raw rather than routed through the column's own
+ * renderer or display type: that renderer was written for a record, and running it against a
+ * heading that carries no quantities or amounts is how a section row ends up showing `0,00 €`.
+ * @param {TableRow} row Row being rendered.
+ * @param {TableRowKind|null|undefined} spec Resolved kind presentation.
+ * @param {TableColumn[]} visibleColumns Columns currently rendered, in display order.
+ * @param {number} [index=0] Flat row index.
+ * @returns {Node|string|number|null|undefined} Cell content.
+ */
+export declare function spanRowContent(row: TableRow, spec: TableRowKind | null | undefined, visibleColumns: TableColumn[], index?: number): Node | string | number | null | undefined;
 /**
  * Applies a column's built-in display type. A custom renderer always wins and may still return a
  * Node; all built-in results are strings so `_renderCellContent` can insert them as text.
@@ -1248,12 +1406,43 @@ export declare function firstValidationError(values: Record<string, unknown>, co
     columnId: string;
     message: string;
 } | null;
+/**
+ * Resolves the `variant` option to one the stylesheet knows; anything else is the default frame.
+ * @param {unknown} value Requested variant.
+ * @returns {TableVariant}
+ */
+export declare function normalizeTableVariant(value: unknown): TableVariant;
 /**
  * Validates and shallow-clones table columns so stable-id APIs never mutate caller descriptors.
  * @param {unknown} columns Column descriptors.
  * @returns {TableColumn[]} Normalized descriptors.
  */
 export declare function normalizeTableColumns(columns: unknown): TableColumn[];
+/**
+ * The name a column goes by wherever it is named rather than shown: its `ariaLabel`, else its
+ * visible label, else its id. The column chooser lists columns by it and cell editors are labelled
+ * with it, so a column with a blank header still has a name in both.
+ * @param {Partial<TableColumn>|null|undefined} column Column descriptor.
+ * @returns {string} Non-empty name, unless the column has no id either.
+ */
+export declare function tableColumnName(column: Partial<TableColumn> | null | undefined): string;
+/**
+ * The accessible name a column header needs on top of its content, or null when its visible label
+ * already names it. That is the `ariaLabel` when one is given, and the column id when the label is
+ * blank — an icon or actions column — so no header is announced as an empty column.
+ * @param {Partial<TableColumn>|null|undefined} column Column descriptor.
+ * @returns {string|null} Name to set as `aria-label`, or null.
+ */
+export declare function tableHeaderName(column: Partial<TableColumn> | null | undefined): string | null;
+/**
+ * Whether opening an editor of this type selects its content, so the first keystroke replaces the
+ * value instead of being appended to it. True for the single-line text, number, and date editors;
+ * a textarea keeps its caret, and a select, checkbox, or custom editor keeps its own focus
+ * behaviour.
+ * @param {TableEditorType|string} type Resolved editor type.
+ * @returns {boolean}
+ */
+export declare function editorSelectsOnEntry(type: TableEditorType | string): boolean;
 /**
  * Reconciles saved or partial column IDs with every current column.
  * @param {TableColumn[]} columns Current columns.

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

@@ -43,9 +43,11 @@ export type TableViewOptions = {
      */
     hiddenFields?: string[];
     /**
-     * Show the accessible visibility and reorder disclosure.
+     * Show the accessible visibility and reorder disclosure. `true` keeps the composed Table's own
+     * column chooser and `false` omits it; an object renders the shared record-view chooser instead,
+     * with a translated `label` and, with `target`, mounted into a host element.
      */
-    fieldControls?: boolean;
+    fieldControls?: boolean | import('../view/record-view.js').ViewFieldControlsConfig;
     /**
      * Empty-result content.
      */
@@ -93,7 +95,10 @@ export type TableViewOptions = {
  * @property {unknown[]} [selection=[]] Initially selected record ids.
  * @property {string[]} [fieldOrder=[]] Preferred stable field order.
  * @property {string[]} [hiddenFields=[]] Initially hidden field ids.
- * @property {boolean} [fieldControls=true] Show the accessible visibility and reorder disclosure.
+ * @property {boolean|import('../view/record-view.js').ViewFieldControlsConfig} [fieldControls=true]
+ * Show the accessible visibility and reorder disclosure. `true` keeps the composed Table's own
+ * column chooser and `false` omits it; an object renders the shared record-view chooser instead,
+ * with a translated `label` and, with `target`, mounted into a host element.
  * @property {string|Node|(()=>string|Node)|null} [emptyText=null] Empty-result content.
  * @property {TableOptions} [table={}] Advanced low-level Table options. Shared options win where
  * their contracts overlap; all other options and callbacks are forwarded unchanged.
@@ -126,6 +131,7 @@ export declare class TableView extends RecordView {
     _tableSyncDepth: number;
     _tableViewDestroyed: boolean;
     _tableHost: HTMLElement;
+    _tableViewToolbar: HTMLElement;
     table: Table;
     static cssName: string;
     /** @type {Readonly<TableViewOptions>} */
@@ -176,7 +182,7 @@ export declare function fieldsToTableColumns(fields: ViewField[]): TableColumn[]
  * Builds the composed Table configuration. Shared options deliberately overwrite overlapping
  * low-level options; every advanced option remains untouched.
  * @param {TableOptions|undefined} table Advanced Table options.
- * @param {{fields:ViewField[],data:TableViewRecord[],recordId:string|((record:TableViewRecord)=>unknown),sort:ViewSort|null,sortMode:'local'|'server',selectable:false|'single'|'multi',hiddenFields:string[],fieldControls:boolean,emptyText:string|Node|(()=>string|Node)|null}} shared Shared state.
+ * @param {{fields:ViewField[],data:TableViewRecord[],recordId:string|((record:TableViewRecord)=>unknown),sort:ViewSort|null,sortMode:'local'|'server',selectable:false|'single'|'multi',hiddenFields:string[],fieldControls:boolean|import('../view/record-view.js').ViewFieldControlsConfig,emptyText:string|Node|(()=>string|Node)|null}} shared Shared state.
  * @returns {TableOptions} Table configuration.
  */
 export declare function tableOptionsForView(table: TableOptions | undefined, shared: {
@@ -187,6 +193,6 @@ export declare function tableOptionsForView(table: TableOptions | undefined, sha
     sortMode: 'local' | 'server';
     selectable: false | 'single' | 'multi';
     hiddenFields: string[];
-    fieldControls: boolean;
+    fieldControls: boolean | import('../view/record-view.js').ViewFieldControlsConfig;
     emptyText: string | Node | (() => string | Node) | null;
 }): TableOptions;

package/dist/types/components/tag-picker/tag-picker.d.ts

@@ -24,9 +24,17 @@ export type TagPickerOptions = {
      */
     iconKey?: TagValueReader;
     /**
-     * Optional item colour property or reader.
+     * Optional item colour property or reader: a CSS colour
+     * or a token reference such as `var(--zx-color-tone-blue-fg)`.
      */
     colorKey?: TagValueReader;
+    /**
+     * Optional item tone property or reader: a categorical
+     * tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
+     * `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone`
+     * does; a tone wins over a colour, and unknown names are ignored.
+     */
+    toneKey?: TagValueReader;
     /**
      * Fields searched by local filtering.
      */
@@ -68,7 +76,8 @@ export type TagPickerOptions = {
      */
     disabled?: boolean;
     /**
-     * Whether tags may be added or removed.
+     * When true the picker shows only its tags — no input, chevron, or
+     * remove buttons.
      */
     readonly?: boolean;
     /**
@@ -142,7 +151,12 @@ export type TagPickerOptions = {
  * @property {TagValueReader} [valueKey='ID'] Item ID property or reader.
  * @property {TagLabelReader} [labelKey='name'] Item label property or reader.
  * @property {TagValueReader} [iconKey='icon'] Optional item icon property or reader.
- * @property {TagValueReader} [colorKey='color'] Optional item colour property or reader.
+ * @property {TagValueReader} [colorKey='color'] Optional item colour property or reader: a CSS colour
+ * or a token reference such as `var(--zx-color-tone-blue-fg)`.
+ * @property {TagValueReader} [toneKey='tone'] Optional item tone property or reader: a categorical
+ * tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
+ * `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone`
+ * does; a tone wins over a colour, and unknown names are ignored.
  * @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
  * @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
  * @property {number} [minQuery=0] Minimum async query length.
@@ -153,7 +167,8 @@ export type TagPickerOptions = {
  * @property {string} [placeholder=''] Empty-state input text.
  * @property {number} [listHeight=260] Maximum list height in pixels.
  * @property {boolean} [disabled=false] Whether interaction is disabled.
- * @property {boolean} [readonly=false] Whether tags may be added or removed.
+ * @property {boolean} [readonly=false] When true the picker shows only its tags — no input, chevron, or
+ * remove buttons.
  * @property {((item: TagItem) => Node|string)|null} [renderItem=null] Option renderer.
  * @property {((item: TagItem) => Node|string)|null} [renderTag=null] Tag-label renderer.
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
@@ -373,6 +388,8 @@ export declare class TagPicker extends Component<TagPickerOptions> {
     _iconOf(item: unknown): Node | null;
     /** @param {unknown} item @returns {string|null} */
     _colorOf(item: unknown): string | null;
+    /** @param {unknown} item @returns {string|null} */
+    _toneOf(item: unknown): string | null;
     /** @param {unknown} item @param {unknown} reader @returns {unknown} */
     _readItem(item: unknown, reader: unknown): unknown;
     /** @returns {void} */

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

@@ -118,4 +118,11 @@ export declare class Timebox extends Component<TimeboxOptions> {
     _syncDisabled(): void;
     /** @returns {void} */
     _emitChange(): void;
+    /**
+     * 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;
 }

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

@@ -381,3 +381,16 @@ export declare class TreeView extends Component<TreeOptions> {
     /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
     destroy(): void;
 }
+/**
+ * Whether a key press is one the type-ahead consumes: a single printable character, not a space
+ * (Space selects), with no Ctrl, Meta, or Alt (those are shortcuts). Shift is allowed, since it
+ * only changes the letter's case.
+ * @param {{key?: string, ctrlKey?: boolean, metaKey?: boolean, altKey?: boolean}} event Key event.
+ * @returns {boolean}
+ */
+export declare function isTreeTypeaheadKey(event: {
+    key?: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}): boolean;

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

@@ -144,6 +144,14 @@ export declare class ValueList extends Component<ValueListOptions> {
     _removeAt(index: number, focusIndex?: number): void;
     /** @param {string} message @returns {void} */
     _showError(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;
     /** @returns {void} */
     destroy(): void;
 }

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

@@ -62,6 +62,35 @@ export type ViewSort = {
      */
     dir: ViewSortDirection;
 };
+export type ViewFieldControlsConfig = {
+    /**
+     * Trigger label. Omitted resolves `recordView.fields`, English `Fields`.
+     */
+    label?: string;
+    /**
+     * Element or selector the disclosure is mounted into
+     * instead of the view's own toolbar. An unresolvable target falls back to the view.
+     */
+    target?: Element | string | null;
+};
+export type ViewFieldControlsSettings = {
+    /**
+     * Whether a concrete view renders the chooser at all.
+     */
+    enabled: boolean;
+    /**
+     * Whether the option was given as a `ViewFieldControlsConfig` object.
+     */
+    custom: boolean;
+    /**
+     * Configured trigger label, or null to resolve the message.
+     */
+    label: string | null;
+    /**
+     * Configured mount point, before resolution.
+     */
+    target: Element | string | null;
+};
 export type RecordViewState = {
     /**
      * State schema version.
@@ -118,9 +147,12 @@ export type RecordViewOptions = {
      */
     hiddenFields?: string[];
     /**
-     * Whether concrete views show the shared field chooser.
+     * Whether concrete views show the
+     * shared field chooser. `true` renders it in the view's own toolbar and `false` omits it; a
+     * `ViewFieldControlsConfig` object renders the same control with a translated `label` and, with
+     * `target`, mounts it into a host element such as a list toolbar.
      */
-    fieldControls?: boolean;
+    fieldControls?: boolean | ViewFieldControlsConfig;
     /**
      * Empty-result content.
      */
@@ -174,6 +206,21 @@ export type RecordViewOptions = {
  * @property {string} id Field id.
  * @property {ViewSortDirection} dir Sort direction.
  */
+/**
+ * Trigger customisation for the shared field chooser. Passing this object in place of `true` keeps
+ * the control and its state model exactly as they are; only its wording and mount point change.
+ * @typedef {Object} ViewFieldControlsConfig
+ * @property {string} [label] Trigger label. Omitted resolves `recordView.fields`, English `Fields`.
+ * @property {Element|string|null} [target=null] Element or selector the disclosure is mounted into
+ * instead of the view's own toolbar. An unresolvable target falls back to the view.
+ */
+/**
+ * @typedef {Object} ViewFieldControlsSettings
+ * @property {boolean} enabled Whether a concrete view renders the chooser at all.
+ * @property {boolean} custom Whether the option was given as a `ViewFieldControlsConfig` object.
+ * @property {string|null} label Configured trigger label, or null to resolve the message.
+ * @property {Element|string|null} target Configured mount point, before resolution.
+ */
 /**
  * @typedef {Object} RecordViewState
  * @property {1} version State schema version.
@@ -192,7 +239,10 @@ export type RecordViewOptions = {
  * @property {unknown[]} [selection=[]] Initially selected record ids.
  * @property {string[]} [fieldOrder=[]] Field ids in preferred order.
  * @property {string[]} [hiddenFields=[]] Initially hidden field ids.
- * @property {boolean} [fieldControls=true] Whether concrete views show the shared field chooser.
+ * @property {boolean|ViewFieldControlsConfig} [fieldControls=true] Whether concrete views show the
+ * shared field chooser. `true` renders it in the view's own toolbar and `false` omits it; a
+ * `ViewFieldControlsConfig` object renders the same control with a translated `label` and, with
+ * `target`, mounts it into a host element such as a list toolbar.
  * @property {string|Node|(() => string|Node)|null} [emptyText=null] Empty-result content.
  * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onrecordclick]
  * @property {(event: CustomEvent<Record<string, unknown>>) => void} [onrecorddblclick]
@@ -226,6 +276,8 @@ export declare class RecordView extends Component<RecordViewOptions> {
     _viewSelectionAnchor: unknown;
     _viewFieldControls: HTMLElement;
     _viewFieldList: HTMLElement;
+    _viewFieldSettings: ViewFieldControlsSettings;
+    _viewFieldControlsTarget: Element;
     _viewInitialized: boolean;
     static cssName: string;
     /** @type {Readonly<RecordViewOptions>} */
@@ -384,10 +436,42 @@ export declare class RecordView extends Component<RecordViewOptions> {
     /**
      * Builds the shared show/hide and ordering disclosure for a concrete view toolbar.
      * @protected
-     * @param {string} [label='Fields'] Trigger label.
+     * @param {string|null} [label=null] Explicit trigger label. Omitted resolves the configured
+     * `fieldControls.label` and then the `recordView.fields` message.
      * @returns {HTMLElement} Disclosure element.
      */
-    protected _createViewFieldControls(label?: string): HTMLElement;
+    protected _createViewFieldControls(label?: string | null): HTMLElement;
+    /**
+     * Builds the shared field disclosure and mounts it where `fieldControls` asks for it: the host
+     * element named by `target`, or the view's own toolbar when no target resolves.
+     * @protected
+     * @param {Element} toolbar The view's own toolbar.
+     * @param {string|null} [label=null] Explicit trigger label, for views that own their wording.
+     * @returns {HTMLElement} The mounted disclosure.
+     */
+    protected _mountViewFieldControls(toolbar: Element, label?: string | null): HTMLElement;
+    /**
+     * Removes the shared field disclosure from wherever it was mounted. An external `target` keeps
+     * every node it had before the view was created.
+     * @protected
+     * @returns {void}
+     */
+    protected _removeViewFieldControls(): void;
+    /**
+     * Resolves the field-chooser trigger label: the configured one, else the translated message.
+     * @protected
+     * @returns {string} Trigger label.
+     */
+    protected _viewFieldControlsLabel(): string;
+    /**
+     * Resolves a message through the host translator, falling back to the built-in English text.
+     * @protected
+     * @param {string} key Message key.
+     * @param {string} fallback Built-in text, with `%1`-style placeholders.
+     * @param {...unknown} args Interpolation values.
+     * @returns {string} Translated or built-in text.
+     */
+    protected _message(key: string, fallback: string, ...args: unknown[]): string;
     /** Concrete renderers override this hook. @protected @param {string} _reason Refresh reason. @returns {void} */
     protected _refreshView(_reason: string): void;
     /** Reads one record's stable id. @protected @param {ViewRecord} record Record. @returns {unknown} */
@@ -407,6 +491,13 @@ export declare class RecordView extends Component<RecordViewOptions> {
     /** @private @param {string|null} [focusId=null] @returns {void} */
     private _renderViewFieldControls;
 }
+/**
+ * Reads the `fieldControls` option in its three shapes. `true` and `false` keep their exact
+ * meaning; an object additionally carries the trigger label and the host element to mount into.
+ * @param {boolean|ViewFieldControlsConfig|null|undefined} value Raw option value.
+ * @returns {ViewFieldControlsSettings} Normalized settings.
+ */
+export declare function normalizeViewFieldControls(value: boolean | ViewFieldControlsConfig | null | undefined): ViewFieldControlsSettings;
 /**
  * Validates and clones field descriptors.
  * @param {ViewField[]} fields Fields.

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';