@zeyos/zx 5.0.0 → 5.2.0

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

@@ -295,6 +295,24 @@ export type TableOptions = {
      * expandable treegrid. Row data and mutation APIs remain flat.
      */
     hierarchy?: false | TableHierarchyOptions;
+    /**
+     * Makes the table an APG grid — row focus, Enter firing
+     * `rowclick` — even without selection, editing, or hierarchy, which already imply it. Attaching a
+     * `rowclick` or `rowdblclick` listener through `on()` or an `on…` option sets it too; pass it when
+     * the host listens for the bubbling `zx-rowclick` DOM event instead.
+     */
+    interactive?: boolean;
+    /**
+     * Accessible name of the table. A grid must have one; null
+     * resolves the `table.label` message (English "Table") for a grid and leaves a plain table unnamed,
+     * so name it after what it lists.
+     */
+    label?: string | null;
+    /**
+     * Id of an element that names the grid — the heading
+     * above it, say. Wins over `label`.
+     */
+    labelledBy?: string | null;
     onrowclick?: (event: CustomEvent<TableRowClickDetail>) => void;
     onrowdblclick?: (event: CustomEvent<TableRowClickDetail>) => void;
     onsort?: (event: CustomEvent<TableSortDetail>) => void;
@@ -517,6 +535,20 @@ export type TableEditorEntry = {
 /**
  * Semantic, sortable data table with optional single or checkbox-based multi-selection and
  * opt-in inline cell or row editing.
+ *
+ * An interactive table — one that is `selectable`, has `editMode` or `hierarchy`, sets
+ * `interactive: true`, or has a `rowclick`/`rowdblclick` listener attached through `on()` or an
+ * `on…` option — follows the WAI-ARIA APG Grid pattern (`role="grid"`), or the Treegrid pattern
+ * (`role="treegrid"`) with `hierarchy`. Any other table keeps plain `<table>` semantics and no
+ * keyboard model of its own. In a grid the rows are one Tab stop with a roving `tabindex`. Rows
+ * take focus by default; a table with `editMode` moves focus between cells instead, which the root
+ * reflects as `data-focus="row"|"cell"`. ArrowUp/ArrowDown move between rows, ArrowLeft/ArrowRight
+ * between cells (cell focus) or expand, collapse, and walk the tree (treegrid), Home/End and
+ * Ctrl+Home/End jump to the ends, PageUp/PageDown move by a visible page (10 rows when the table
+ * does not scroll). Enter activates the row exactly as a click does (`rowclick`), Space toggles the
+ * row's selection when `selectable` (and activates otherwise), Shift+Arrow extends a `multi`
+ * selection, and Ctrl/Cmd+A selects every rendered row. The focused row survives `setData`, sorting,
+ * expansion, and `updateRow`. Column headers keep their sort buttons in the Tab order.
  * @fires Table#rowclick
  * @fires Table#rowdblclick
  * @fires Table#sort
@@ -543,10 +575,11 @@ export declare class Table extends Component<TableOptions> {
     _rowKinds: Record<string, TableRowKind>;
     _spanning: boolean;
     _sortWarned: boolean;
-    _selected: Set<any>;
-    _selectionAnchorId: any;
+    _selected: Set<any> | Set<unknown>;
+    _selectionAnchorId: unknown;
     _sort: any;
     _rowMeta: WeakMap<object, any>;
+    _rowNames: WeakMap<object, any>;
     _rowElements: Map<any, any>;
     _restored: boolean;
     _editMode: TableEditMode;
@@ -564,12 +597,11 @@ export declare class Table extends Component<TableOptions> {
     _growStep: number;
     _rendered: number;
     _more: HTMLElement;
-    _rovingKey: {
-        id: unknown;
-        columnId: string;
-    };
-    _rovingCell: any;
-    _rovingMatched: boolean;
+    _focusMode: string;
+    _interactive: boolean;
+    _current: any;
+    _rovingEl: any;
+    _extendBase: Set<any>;
     _hierarchy: TableHierarchyOptions & {
         column: string;
     };
@@ -586,6 +618,7 @@ export declare class Table extends Component<TableOptions> {
     _scroll: HTMLElement;
     _rowMoveMessage: HTMLElement;
     _columnControls: HTMLElement;
+    _clickListened: boolean;
     _columnList: HTMLElement;
     _selectAll: HTMLElement;
     _headers: Map<any, any>;
@@ -938,12 +971,26 @@ export declare class Table extends Component<TableOptions> {
      * @fires Table#stackedchange
      */
     _setStacked(stacked: boolean): void;
+    /**
+     * Registers a listener, and turns the table into a grid when the listener is for a row click:
+     * a host that reacts to the row needs the row reachable by keyboard.
+     * @param {string} type Event name.
+     * @param {EventListenerOrEventListenerObject|null} listener Listener.
+     * @param {boolean|AddEventListenerOptions} [options] Listener options.
+     * @returns {void}
+     */
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    /** @returns {'grid'|'treegrid'|null} Role of the `<table>`, or null for plain table semantics. */
+    _gridRole(): 'grid' | 'treegrid' | null;
+    /** Writes the grid role, name, and focus mode — or their absence — onto the table. @returns {void} */
+    _syncGridRole(): void;
     /**
      * States the table roles explicitly while stacked, and removes them again on the way out.
      *
      * Stacking works by changing `display` on the table elements, and a table whose display is not
      * `table` loses its implicit ARIA roles — leaving a screen reader with a pile of generic blocks
-     * where a table used to be. The roles are only asserted while the layout has taken them away.
+     * where a table used to be. The roles are only asserted while the layout has taken them away;
+     * a grid keeps its explicit grid or treegrid role in either mode.
      * @param {boolean} stacked Whether the roles should be present.
      * @returns {void}
      */
@@ -1048,6 +1095,14 @@ export declare class Table extends Component<TableOptions> {
     _createRow(row: TableRow, index: number, tree: TableHierarchyEntry & {
         visibleIndex: number;
     }): HTMLTableRowElement;
+    /**
+     * Names a row's own controls after the row's content rather than its position: "Select Acme
+     * GmbH", not "Select row 3", which tells a screen reader user nothing and changes on every sort.
+     * The position is the fallback for a row without any text.
+     * @param {HTMLTableRowElement} tr Rendered row.
+     * @returns {void}
+     */
+    _labelRowControls(tr: HTMLTableRowElement): void;
     /**
      * Fills a cell with the column's rendered value, replacing anything already in it.
      * @param {HTMLTableCellElement} cell Target cell.
@@ -1060,6 +1115,20 @@ export declare class Table extends Component<TableOptions> {
     _renderCellContent(cell: HTMLTableCellElement, column: TableColumn, row: TableRow, index: number, tree?: TableHierarchyEntry): void;
     /** @param {MouseEvent} event @returns {void} */
     _handleBodyClick(event: MouseEvent): void;
+    /**
+     * Activates a row: the click path, shared by Enter on a focused row or cell.
+     * @param {{row: TableRow, id: unknown, index: number, visibleIndex?: number}} meta Row metadata.
+     * @param {Event} event Originating click or keydown.
+     * @returns {void}
+     * @fires Table#rowclick
+     * @fires Table#selectionchange
+     */
+    _activateRow(meta: {
+        row: TableRow;
+        id: unknown;
+        index: number;
+        visibleIndex?: number;
+    }, event: Event): void;
     /** @param {MouseEvent} event @returns {void} @fires Table#editstart */
     _handleBodyDoubleClick(event: MouseEvent): void;
     /**
@@ -1130,20 +1199,127 @@ export declare class Table extends Component<TableOptions> {
         columnId: string;
         index: number;
     } | null;
-    /** @param {Event} event @returns {void} */
-    _handleEditFocusIn(event: Event): void;
     /** @param {Event} event @returns {void} @fires Table#editcommit */
     _handleDocumentPointerDown(event: Event): void;
+    /** @returns {HTMLTableRowElement[]} Rendered body rows in display order, section rows included. */
+    _navRows(): HTMLTableRowElement[];
     /**
-     * Keeps exactly one editable cell in the tab order, preferring the last focused one.
-     * @param {HTMLTableCellElement} cell Newly rendered editable cell.
+     * Cells that take focus while the table moves focus by cell: the data cells, or the single cell of
+     * a section row. The selection and reorder cells are not among them; their controls have keys of
+     * their own on the row.
+     * @param {HTMLTableRowElement} tr Body row.
+     * @returns {HTMLTableCellElement[]}
+     */
+    _navCells(tr: HTMLTableRowElement): HTMLTableCellElement[];
+    /**
+     * The cell of a row that matches the current column: by id, else by position, so a section row
+     * (one cell) or a hidden column still lands somewhere sensible.
+     * @param {HTMLTableRowElement} tr Body row.
+     * @returns {HTMLElement}
+     */
+    _cellFor(tr: HTMLTableRowElement): HTMLElement;
+    /** @param {HTMLTableRowElement} tr @returns {HTMLElement} Element of a row that holds the Tab stop. */
+    _rovingTarget(tr: HTMLTableRowElement): HTMLElement;
+    /** @param {HTMLElement} element New roving Tab stop. @returns {void} */
+    _setRoving(element: HTMLElement): void;
+    /**
+     * Records which part of a row holds focus before the body is rebuilt.
+     * @returns {{part: 'row'|'cell'|'checkbox'|'toggle'|'handle'}|null} Null when focus is elsewhere.
+     */
+    _captureFocus(): {
+        part: 'row' | 'cell' | 'checkbox' | 'toggle' | 'handle';
+    } | null;
+    /**
+     * Puts the Tab stop back on the current row after a render — the same row by id; else, when a
+     * collapsed ancestor hid it, that ancestor; else the row now at its old position — and gives it
+     * focus again only when the body had focus before. The focus is restored without scrolling: a
+     * table refreshed by polling must not pull the page back to itself.
+     * @param {{part: string}|null} focus What `_captureFocus()` found before the render.
+     * @returns {void}
+     */
+    _syncRoving(focus: {
+        part: string;
+    } | null): void;
+    /**
+     * The nearest ancestor of a row that is rendered — where focus goes when collapsing a branch
+     * hid the focused row.
      * @param {unknown} id Row id.
-     * @param {string} columnId Column id.
+     * @returns {HTMLTableRowElement|undefined}
+     */
+    _renderedAncestor(id: unknown): HTMLTableRowElement | undefined;
+    /**
+     * While the table has no rows to focus, its frame takes focus instead of letting it fall to the
+     * document — and gives the Tab order its old shape back once rows return.
+     * @param {boolean} hold Whether focus was in the body and there is now no row for it.
+     * @returns {void}
+     */
+    _syncEmptyFocus(hold: boolean): void;
+    /** @param {Event} event @returns {void} */
+    _handleFocusIn(event: Event): void;
+    /**
+     * The APG grid and treegrid keyboard model on the focused row or cell. The row's own checkbox and
+     * disclosure answer the navigation keys too, so a pointer user who clicked one can carry on by
+     * keyboard; anything else inside a cell — a link, a button, an open editor — keeps its keys.
+     * @param {KeyboardEvent} event Keydown event.
+     * @returns {void}
+     * @fires Table#rowclick
+     * @fires Table#selectionchange
+     * @fires Table#rowtoggle
+     */
+    _handleGridKeydown(event: KeyboardEvent): void;
+    /**
+     * Carries out one treegrid arrow-key action on a row.
+     * @param {{action: string, column?: number}} action What `treegridArrowAction()` decided.
+     * @param {HTMLTableRowElement} tr Focused row.
+     * @param {{id: unknown}} meta Row metadata.
+     * @param {unknown} parentId Parent row id, or null at the root.
+     * @returns {void}
+     * @fires Table#rowtoggle
+     */
+    _applyTreeAction(action: {
+        action: string;
+        column?: number;
+    }, tr: HTMLTableRowElement, meta: {
+        id: unknown;
+    }, parentId: unknown): void;
+    /**
+     * How many rows PageUp and PageDown move: what fits in the scroll region when the table scrolls
+     * on its own, else ten.
+     * @param {HTMLTableRowElement[]} rows Rendered rows.
+     * @returns {number}
+     */
+    _pageSize(rows: HTMLTableRowElement[]): number;
+    /**
+     * Space on a row: toggles it in `multi`, and in `single` selects it or clears the selection.
+     * @param {{row: TableRow, id: unknown, index: number, visibleIndex?: number}} meta Row metadata.
      * @returns {void}
+     * @fires Table#selectionchange
      */
-    _offerRovingCell(cell: HTMLTableCellElement, id: unknown, columnId: string): void;
-    /** @param {HTMLTableCellElement} cell @param {unknown} id @param {string} columnId @returns {void} */
-    _setRovingCell(cell: HTMLTableCellElement, id: unknown, columnId: string): void;
+    _toggleRowSelection(meta: {
+        row: TableRow;
+        id: unknown;
+        index: number;
+        visibleIndex?: number;
+    }): void;
+    /**
+     * Ctrl/Cmd+A: selects every rendered row that can hold a selection, as the header checkbox does.
+     * @returns {void}
+     * @fires Table#selectionchange
+     */
+    _selectAllRendered(): void;
+    /**
+     * Shift+Arrow: selects the rows between the anchor and the row focus moved to, on top of what was
+     * selected before the extension began — moving back shrinks the range again.
+     * @param {{id: unknown}} from Row focus moved from.
+     * @param {{id: unknown}|undefined} to Row focus moved to.
+     * @returns {void}
+     * @fires Table#selectionchange
+     */
+    _extendSelection(from: {
+        id: unknown;
+    }, to: {
+        id: unknown;
+    } | undefined): void;
     /**
      * Resolves a message key with an English fallback for hosts without a translator.
      * @param {string} key Message key.
@@ -1226,6 +1402,78 @@ export declare class Table extends Component<TableOptions> {
  * @event Table#editinvalid
  * @type {CustomEvent<TableEditInvalidDetail>}
  */
+/**
+ * Where a navigation key moves focus in the table body: the arithmetic of the APG grid keyboard
+ * model, kept apart from the DOM. Positions are zero-based and every move is clamped — focus never
+ * wraps, as the APG asks of a grid.
+ *
+ * With `cells` false (row focus) only the vertical keys move: ArrowUp/ArrowDown by one row,
+ * PageUp/PageDown by `page`, Home/End (with or without Ctrl) to the first or last row. With `cells`
+ * true ArrowLeft/ArrowRight move one cell, Home/End go to the first or last cell of the row, and
+ * Ctrl+Home/Ctrl+End to the first cell of the first row or the last cell of the last row.
+ * @param {{row: number, column?: number}} position Current position.
+ * @param {string} key `KeyboardEvent.key`.
+ * @param {{rows: number, columns?: number, page?: number, ctrl?: boolean, cells?: boolean}} grid
+ * Row and column counts, the page size, whether Ctrl/Cmd is held, and whether focus is on cells.
+ * @returns {{row: number, column: number}|null} New position, or null when the key is not a move.
+ */
+export declare function tableGridTarget(position: {
+    row: number;
+    column?: number;
+}, key: string, grid: {
+    rows: number;
+    columns?: number;
+    page?: number;
+    ctrl?: boolean;
+    cells?: boolean;
+}): {
+    row: number;
+    column: number;
+} | null;
+/**
+ * How many rows a PageUp or PageDown moves: the rows that fit in the visible height, less one so
+ * the row focus leaves stays in view as context. Falls back when either height is unknown.
+ * @param {number} viewport Visible height of the scroll region, below any sticky header.
+ * @param {number} rowHeight Height of one row.
+ * @param {number} [fallback=10] Rows to move when the heights are unusable.
+ * @returns {number} At least 1.
+ */
+export declare function tablePageSize(viewport: number, rowHeight: number, fallback?: number): number;
+/**
+ * ArrowLeft and ArrowRight in a treegrid, after the APG Treegrid pattern.
+ *
+ * Row focus (`focus: 'row'`): ArrowRight expands a collapsed branch; on an expanded branch it moves
+ * into the first child — or, when cells take focus too (`cells`), onto the row's first cell, which
+ * is also where it goes from a leaf. ArrowLeft collapses an expanded branch and otherwise moves to
+ * the parent row. Cell focus: ArrowRight moves one cell right; ArrowLeft one cell left, and from the
+ * first cell onto the row itself, where the branch can be expanded or collapsed.
+ * @param {'ArrowLeft'|'ArrowRight'|string} key `KeyboardEvent.key`.
+ * @param {{focus: 'row'|'cell', cells?: boolean, column?: number, columns?: number,
+ *   hasChildren?: boolean, expanded?: boolean, hasParent?: boolean}} state Focused row and cell.
+ * @returns {{action: 'expand'|'collapse'|'child'|'parent'|'row'|'cell', column?: number}|null}
+ * What to do, or null when focus stays where it is.
+ */
+export declare function treegridArrowAction(key: 'ArrowLeft' | 'ArrowRight' | string, state: {
+    focus: 'row' | 'cell';
+    cells?: boolean;
+    column?: number;
+    columns?: number;
+    hasChildren?: boolean;
+    expanded?: boolean;
+    hasParent?: boolean;
+}): {
+    action: 'expand' | 'collapse' | 'child' | 'parent' | 'row' | 'cell';
+    column?: number;
+} | null;
+/**
+ * The name a row goes by in the labels of its own controls ("Select …", "Expand …"): the text of
+ * its first cell that has any, whitespace collapsed and long text cut short. Null when no cell has
+ * text, which is when the caller falls back to the row's position.
+ * @param {Array<string|null|undefined>} texts Text of the row's cells, in display order.
+ * @param {number} [max=80] Longest name returned before it is cut with an ellipsis.
+ * @returns {string|null}
+ */
+export declare function tableRowLabel(texts: Array<string | null | undefined>, max?: number): string | null;
 /**
  * Resolves a row's kind through the `rowKind` accessor and coerces it to the string `rowKinds` is
  * keyed by.

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

@@ -274,8 +274,20 @@ export declare class RecordView extends Component<RecordViewOptions> {
     _viewSort: ViewSort;
     _viewSelected: any;
     _viewSelectionAnchor: unknown;
-    _viewFieldControls: HTMLElement;
+    _viewFieldControls: HTMLDetailsElement;
     _viewFieldList: HTMLElement;
+    _viewFieldStatus: HTMLElement;
+    _viewFieldHome: {
+        parent: ParentNode;
+        next: ChildNode;
+        mounted: string;
+    };
+    _viewNativeMounted: HTMLElement;
+    /** @type {{id: string, action: 'toggle'|'up'|'down'}|null} */
+    _viewFieldFocus: {
+        id: string;
+        action: 'toggle' | 'up' | 'down';
+    } | null;
     _viewFieldSettings: ViewFieldControlsSettings;
     _viewFieldControlsTarget: Element;
     _viewInitialized: boolean;
@@ -343,6 +355,26 @@ export declare class RecordView extends Component<RecordViewOptions> {
     getHiddenFields(): string[];
     /** Returns the complete field id order. @returns {string[]} */
     getFieldOrder(): string[];
+    /**
+     * Returns the element that lets a reader show, hide, and reorder this view's fields: the shared
+     * field chooser, or — for a `TableView` with `fieldControls: true` — the column chooser of its
+     * composed `Table`. Null when the view renders none (`fieldControls: false`).
+     *
+     * The element stays owned by the view: move it with {@link RecordView#mountFieldControls}
+     * rather than appending it elsewhere yourself, so `destroy()` can still find and remove it.
+     * @returns {HTMLElement|null}
+     */
+    getFieldControls(): HTMLElement | null;
+    /**
+     * Moves the view's field chooser into a host element — a list toolbar, a pane header — or, with
+     * `null`, back to where the view first rendered it. It keeps driving this view wherever it
+     * sits, and `destroy()` removes it from the host. `ListToolbar.bind()` calls this for every
+     * record view, which is how its field chooser ends up in the bar.
+     * @param {Element|string|null} target Host element or selector; null returns the chooser home.
+     * @returns {HTMLElement|null} The chooser, or null when the view renders none or the target
+     * does not resolve.
+     */
+    mountFieldControls(target: Element | string | null): HTMLElement | null;
     /**
      * Shows or hides one field. The final visible field cannot be hidden.
      * @param {string} id Field id.
@@ -457,6 +489,24 @@ export declare class RecordView extends Component<RecordViewOptions> {
      * @returns {void}
      */
     protected _removeViewFieldControls(): void;
+    /**
+     * A field chooser the concrete view renders natively instead of the shared one. The base class
+     * recognises a composed `Table` exposed through `getTable()` — `TableView` with
+     * `fieldControls: true` keeps Table's own column chooser — and any other subclass may override
+     * this to publish its own.
+     * @protected
+     * @returns {HTMLElement|null}
+     */
+    protected _nativeFieldControls(): HTMLElement | null;
+    /**
+     * Moves a field one place through the chooser's buttons, keeps focus on that field's control
+     * across the re-render, and announces where it landed.
+     * @private
+     * @param {string} id Field id.
+     * @param {-1|1} delta Direction.
+     * @returns {void}
+     */
+    private _moveViewFieldFromChooser;
     /**
      * Resolves the field-chooser trigger label: the configured one, else the translated message.
      * @protected
@@ -488,7 +538,14 @@ export declare class RecordView extends Component<RecordViewOptions> {
     private _emitViewSelection;
     /** @private @param {string} reason @returns {void} */
     private _emitViewState;
-    /** @private @param {string|null} [focusId=null] @returns {void} */
+    /**
+     * Re-renders the chooser list. A focus request names the field and the control that should
+     * hold focus afterwards — a bare id means its checkbox — and falls back to the field's other
+     * enabled control when the requested one became disabled (a move button at either end).
+     * @private
+     * @param {string|{id:string,action:'toggle'|'up'|'down'}|null} [focus=null] Control to focus.
+     * @returns {void}
+     */
     private _renderViewFieldControls;
 }
 /**