@guiexpert/table 1.1.91 → 1.1.92

package/lib/table/ele-scope.d.ts

@@ -6,6 +6,7 @@ import { GeoData } from './data/geo-data.js';
 import { AriaIds } from './aria/aria-ids.js';
 import { AreaIdent } from './data/tablemodel/area-ident.type.js';
 import { SideIdent } from './data/side-ident.type.js';
+import { TableOverlay } from './overlay/table-overlay.js';
 
 /**
  * Represents a store for HTML elements.
@@ -50,7 +51,16 @@ export declare class EleScope {
     protected areaBodyEastGeo: GeoData;
     /** The IDs this table uses for ARIA references (prefix from the host id). @since 1.1.91 */
     readonly ariaIds: AriaIds;
+    /** The overlay layer over the body ("Loading…", "No rows to show"). @since 1.1.92 */
+    readonly tableOverlay: TableOverlay;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, dom: ConvenienceDomService, tableOptions: TableOptionsIf);
+    /**
+     * Shows the overlay that fits the current state (requested by the API, or "no rows" for an empty body).
+     * Overwritten in {@link RenderScope}.
+     *
+     * @since 1.1.92
+     */
+    protected updateOverlay(): void;
     /** The values of the host attributes before the table changed them (restored by {@link removeHostAria}). */
     private readonly hostAttributesBefore;
     /**
@@ -60,6 +70,13 @@ export declare class EleScope {
      * @since 1.1.91
      */
     protected setHostAriaAttribute(key: string, value: string | undefined): void;
+    /**
+     * Gives an ARIA attribute of the host back the value it had before the table changed it (e.g. `aria-busy` after
+     * loading), or removes it if the host had none.
+     *
+     * @since 1.1.92
+     */
+    protected restoreHostAriaAttribute(key: string): void;
     /**
      * Removes the ARIA attributes the table has set on the host element (see {@link initHostAria}).
      *

package/lib/table/event-adapter.d.ts

@@ -4,6 +4,7 @@ import { GeScrollEvent } from './data/common/event/ge-scroll-event.js';
 import { EventListenerIf } from './event-listener.if.js';
 import { SelectionModelIf } from './selection/selection-model.if.js';
 import { FocusModelIf } from './focus/focus-model.if.js';
+import { GeStateChangeEvent } from './data/common/event/ge-state-change-event.js';
 
 /**
  * Empty implementation of {@link EventListenerIf} – extend it and override only the events you need.
@@ -30,4 +31,6 @@ export declare class EventAdapter implements EventListenerIf {
     onScroll(_evt: GeScrollEvent): void;
     onSelectionChanged(_model: SelectionModelIf): void;
     onFocusChanged(_model: FocusModelIf): void;
+    /** @since 1.1.92 */
+    onStateChanged(_evt: GeStateChangeEvent): void;
 }

package/lib/table/event-listener.if.d.ts

@@ -1,6 +1,7 @@
 import { GeMouseEvent } from './data/common/event/ge-mouse-event.js';
 import { GeModelChangeEvent } from './data/common/event/ge-model-change-event.js';
 import { GeScrollEvent } from './data/common/event/ge-scroll-event.js';
+import { GeStateChangeEvent } from './data/common/event/ge-state-change-event.js';
 import { SelectionModelIf } from './selection/selection-model.if.js';
 import { FocusModelIf } from './focus/focus-model.if.js';
 import { EventFocusChangedListenerIf } from './focus/event-focus-changed-listener.if.js';
@@ -55,4 +56,11 @@ export interface EventListenerIf extends EventFocusChangedListenerIf, EventSelec
     onSelectionChanged(model: SelectionModelIf): void;
     /** The focused cell changed – read it from {@link FocusModelIf.getFocus}. */
     onFocusChanged(model: FocusModelIf): void;
+    /**
+     * The state of the table changed (column layout, sorting, scroll position, tree, checked or selected rows,
+     * header groups, custom data) – reported once after the changes settled, see {@link GeStateChangeEvent}.
+     * Save `evt.state` e.g. on your server and pass it back as {@link TableOptionsIf.initialState}.
+     * @since 1.1.92
+     */
+    onStateChanged?(evt: GeStateChangeEvent): void;
 }

package/lib/table/mouse-handler.d.ts

@@ -78,4 +78,6 @@ export declare class MouseHandler {
     private mouseDraggingOnFrame;
     private mouseDraggingEndOnFrame;
     private mouseMoveOnFrame;
+    /** A mouse event on a blocking loading overlay ({@link TableOverlay.isEventBlocked}): the table ignores it. */
+    private isBlocked;
 }

package/lib/table/overlay/calc-overlay-kind.d.ts

@@ -0,0 +1,31 @@
+import { GeOverlayKind } from './ge-overlay-kind.type.js';
+
+/**
+ * Input of {@link calcOverlayKind}.
+ *
+ * @since 1.1.92
+ * @category Internals
+ */
+export interface OverlayKindInput {
+    /** The overlay requested by the API ({@link TableApi.showLoadingOverlay}, {@link TableApi.showNoRowsOverlay}). */
+    manual?: "loading" | "noRows";
+    /** `getRowCount()` of the body (after the filter); < 0 = unknown. */
+    rowCount: number;
+    /** `getUnfilteredRowCount()` of the body, `undefined` if the model cannot tell. */
+    unfilteredRowCount?: number;
+    /** {@link OverlayOptionsIf.autoNoRows} */
+    autoNoRows: boolean;
+}
+/**
+ * Decides which overlay the table shows. Order: a manual overlay > "no matching rows" > "no rows to show".
+ * A model that cannot tell its unfiltered row count gets "no rows" (never a wrong "no matching rows"),
+ * an unknown row count (< 0) no overlay.
+ *
+ * @example
+ * calcOverlayKind({ rowCount: 0, unfilteredRowCount: 100, autoNoRows: true }); // "noMatches"
+ * calcOverlayKind({ manual: "loading", rowCount: 0, autoNoRows: true });       // "loading"
+ *
+ * @since 1.1.92
+ * @category Internals
+ */
+export declare function calcOverlayKind(input: OverlayKindInput): GeOverlayKind;

package/lib/table/overlay/ge-overlay-kind.type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The overlay the table shows over its body:
+ * - `"none"` – no overlay;
+ * - `"loading"` – spinner + "Loading…" ({@link TableApi.showLoadingOverlay});
+ * - `"noRows"` – "No rows to show": the body is empty ({@link OverlayOptionsIf.autoNoRows}) or
+ *   {@link TableApi.showNoRowsOverlay} was called;
+ * - `"noMatches"` – "No matching rows": the body has rows, but the external filter hides all of them.
+ *
+ * @example
+ * if (tableApi.getOverlayState() === "noMatches") {
+ *   console.log("Reset the filter to see rows again");
+ * }
+ *
+ * @since 1.1.92
+ * @category Overlays
+ */
+export type GeOverlayKind = "none" | "loading" | "noRows" | "noMatches";

package/lib/table/overlay/table-overlay.d.ts

@@ -0,0 +1,108 @@
+import { ConvenienceDomService } from '../service/convenience-dom.service.js';
+import { OverlayOptionsIf } from '../data/options/overlay-options.if.js';
+import { OverlayOptions } from '../data/options/overlay-options.js';
+import { GeOverlayKind } from './ge-overlay-kind.type.js';
+
+/**
+ * A change of the shown overlay, reported by {@link TableOverlay.update}.
+ *
+ * @since 1.1.92
+ * @category Internals
+ */
+export interface TableOverlayChange {
+    previous: GeOverlayKind;
+    kind: GeOverlayKind;
+    /** the text of the new overlay (`""` for `"none"`) */
+    text: string;
+}
+/**
+ * The overlay layer over the table body: "Loading…" with a CSS spinner, "No rows to show", "No matching rows".
+ * One element per table (`.ge-table-overlay`, a child of the host, `aria-hidden` – the table announces the texts
+ * through its live region instead). It is created once and only changed when the shown overlay changes, so
+ * scrolling costs one comparison per frame.
+ *
+ * Apps use it through {@link TableApi.showLoadingOverlay}, {@link TableApi.showNoRowsOverlay},
+ * {@link TableApi.hideOverlay} and {@link TableApi.getOverlayState}; texts and behaviour come from
+ * {@link TableOptionsIf.overlayOptions}.
+ *
+ * @example
+ * const overlay = new TableOverlay(hostDiv, new ConvenienceDomService(new SimpleDomService()), {}, () => {
+ *   overlay.update(0, 0);
+ * });
+ * overlay.showLoading("Saving…"); // calls the update callback
+ * console.log(overlay.getState()); // "loading"
+ * overlay.destroy();
+ *
+ * @since 1.1.92
+ * @category Internals
+ */
+export declare class TableOverlay {
+    private readonly dom;
+    private readonly requestUpdate;
+    /** The overlay element (`.ge-table-overlay`). */
+    readonly element: HTMLDivElement;
+    /** The content box, centered in the overlay (`.ge-table-overlay-content`). */
+    readonly contentElement: HTMLDivElement;
+    readonly options: OverlayOptions;
+    private manual?;
+    private delayTimeout?;
+    private shownKind;
+    private shownText;
+    private shownBlocking;
+    private bounds;
+    private destroyed;
+    /**
+     * @param {HTMLDivElement} hostElement - the table host; the overlay is appended to it
+     * @param {ConvenienceDomService} dom - DOM access of the table
+     * @param {Partial<OverlayOptionsIf>} [overlayOptions] - {@link TableOptionsIf.overlayOptions}
+     * @param {() => void} [requestUpdate] - called when the requested overlay changed (API call, end of the
+     *   delay); the table answers with {@link update}
+     */
+    constructor(hostElement: HTMLDivElement, dom: ConvenienceDomService, overlayOptions?: Partial<OverlayOptionsIf>, requestUpdate?: () => void);
+    /**
+     * Requests the loading overlay (after {@link OverlayOptionsIf.loadingDelayInMs}).
+     *
+     * @param {string} [text] - text for this overlay, default {@link OverlayOptionsIf.loadingText}
+     */
+    showLoading(text?: string): void;
+    /**
+     * Requests the "no rows" overlay, also over rows and with {@link OverlayOptionsIf.autoNoRows} `false`.
+     *
+     * @param {string} [text] - text for this overlay, default {@link OverlayOptionsIf.noRowsText}
+     */
+    showNoRows(text?: string): void;
+    /** Ends a requested overlay; the automatic "no rows" / "no matching rows" stays as long as the body is empty. */
+    hide(): void;
+    /** The overlay that is shown now. */
+    getState(): GeOverlayKind;
+    /** `true` while a loading overlay blocks mouse and keyboard ({@link OverlayOptionsIf.blockInteractionWhileLoading}). */
+    isBlocking(): boolean;
+    /**
+     * `true` for a mouse event on a blocking loading overlay: the table ignores it (click, double click, mouse down,
+     * context menu, hover). The event is not stopped – page handlers (e.g. "click outside closes the menu") see it.
+     *
+     * @param {Event} evt - a mouse event that reached the host
+     * @returns {boolean} the table must not react to it
+     */
+    isEventBlocked(evt: Event): boolean;
+    /**
+     * Shows the overlay that fits the body: a requested one, else "no matching rows" / "no rows to show"
+     * for an empty body. Changes the DOM only if the result differs from what is shown.
+     *
+     * @param {number} rowCount - `getRowCount()` of the body
+     * @param {number} [unfilteredRowCount] - `getUnfilteredRowCount()` of the body (only needed for 0 rows)
+     * @returns {TableOverlayChange | undefined} the change, `undefined` if nothing changed
+     */
+    update(rowCount: number, unfilteredRowCount?: number): TableOverlayChange | undefined;
+    /**
+     * Places the overlay over the body (px, relative to the host). Unchanged values do not touch the DOM.
+     */
+    setBounds(left: number, top: number, width: number, height: number): void;
+    /** Removes the overlay element and a waiting delay. Calling it twice is harmless. */
+    destroy(): void;
+    private getText;
+    private render;
+    /** The element of {@link OverlayOptionsIf.getOverlayElement}; an error falls back to the built-in content. */
+    private getOwnElement;
+    private clearDelay;
+}

package/lib/table/render-scope.d.ts

@@ -1,3 +1,4 @@
+import { TableOverlayChange } from './overlay/table-overlay.js';
 import { EleScope } from './ele-scope.js';
 import { TableModelIf } from './data/tablemodel/table-model.if.js';
 import { ConvenienceDomService } from './service/convenience-dom.service.js';
@@ -34,11 +35,11 @@ export declare class RenderScope extends EleScope {
     protected dragging: boolean;
     protected editing: boolean;
     protected storedColumnWidths: number[];
+    /** @deprecated since 1.1.92 – no longer used, see {@link TableStateService}. */
     protected storeScrollPosStateService?: StoreStateScrollPosService;
     protected getSelectionModel?: GetT<SelectionModelIf>;
     protected getFocusModel?: GetT<FocusModelIf>;
     protected scrollLeft: number;
-    private scrollPosSaveTimeout?;
     protected scrollViewportLeft: number;
     protected scrollFactorY: number;
     protected scrollFactorX: number;
@@ -145,7 +146,30 @@ export declare class RenderScope extends EleScope {
      */
     adjustAfterScrolling(): void;
     /**
-     * Checks if the scroll position should be saved and saves it.
+     * Called at the end of every render pass (scroll, repaint). {@link TableScope} marks the scroll position of the
+     * table state as changed here (stored and reported debounced, see {@link TableStateService}).
+     *
+     * @since 1.1.92
+     */
+    protected afterRenderPass(): void;
+    /**
+     * Shows the overlay that fits the body now (see {@link TableOverlay.update}) and reports a change to
+     * {@link onOverlayChanged}.
+     *
+     * @since 1.1.92
+     */
+    protected updateOverlay(): void;
+    /**
+     * Called after the shown overlay changed (ARIA in {@link TableScope}).
+     *
+     * @param {TableOverlayChange} _change - previous and new overlay, its text
+     * @since 1.1.92
+     */
+    protected onOverlayChanged(_change: TableOverlayChange): void;
+    /**
+     * Marks the scroll position as changed (it is stored with the table state, see {@link TableStateService}).
+     *
+     * @deprecated since 1.1.92 – the table does this after every render pass.
      *
      * @return {void}
      */

package/lib/table/service/convenience-dom.service.d.ts

@@ -41,7 +41,7 @@ export declare class ConvenienceDomService {
     applyStylePosistionRelative(ele: HTMLDivElement): HTMLDivElement;
     applyStylePosistionAbsolute(ele: HTMLDivElement): HTMLDivElement;
     applyStyleFullSize(ele: HTMLDivElement): HTMLDivElement;
-    applyStyleOverflowAuto(overflowX: "auto" | "scroll" | undefined, overflowY: "auto" | "scroll" | undefined, ele: HTMLDivElement): HTMLDivElement;
+    applyStyleOverflowAuto(overflowX: "scroll" | "auto" | undefined, overflowY: "scroll" | "auto" | undefined, ele: HTMLDivElement): HTMLDivElement;
     applyStyleNoPadding(ele: HTMLDivElement): HTMLDivElement;
     appendRelativeChildDiv(parent: HTMLDivElement): DivScope;
     appendText(parent: HTMLDivElement, text: string): HTMLElement;

package/lib/table/state/state-storage.if.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where {@link AutoRestoreOptionsIf} stores the state of a table ({@link AutoRestoreOptionsIf.storage}). A synchronous
+ * key-value store with the method names of the Web Storage API – `localStorage` (default) and `sessionStorage`
+ * fit directly.
+ *
+ * The table reads the state while it is built, so the storage must answer synchronously. To keep the state on a
+ * server, load it before you create the table and pass it as {@link TableOptionsIf.initialState}; save it in
+ * {@link EventListenerIf.onStateChanged}.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   autoRestoreOptions: {
+ *     ...new AutoRestoreOptions<Order>(),
+ *     getStorageKeyFn: () => "orders",
+ *     storage: sessionStorage,            // forget the layout when the tab is closed
+ *     autoRestoreColumnLayout: true
+ *   }
+ * };
+ *
+ * @example
+ * // an own storage, e.g. a prefix for all keys
+ * const prefixed: StateStorageIf = {
+ *   getItem: key => localStorage.getItem("my-app/" + key),
+ *   setItem: (key, value) => localStorage.setItem("my-app/" + key, value),
+ *   removeItem: key => localStorage.removeItem("my-app/" + key)
+ * };
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface StateStorageIf {
+    /** The stored string or `null`. */
+    getItem(key: string): string | null;
+    /** Stores a string. May throw (quota) – the table catches it. */
+    setItem(key: string, value: string): void;
+    /** Removes a key. */
+    removeItem(key: string): void;
+}

package/lib/table/state/table-state-migration.d.ts

@@ -0,0 +1,36 @@
+import { StateStorageIf } from './state-storage.if.js';
+import { TableStateIf } from './table-state.if.js';
+
+/**
+ * Reads the state that tables before 1.1.92 stored under `<key>sortingState`, `<key>scrollState` and
+ * `<key>collapsedExpandedState` and converts it to a {@link TableStateIf}. The stored sort items hold a column
+ * INDEX – it is converted to the property of the column at that index in the default column order (the order a
+ * table of the old version always started with).
+ *
+ * @param {StateStorageIf} storage - the storage
+ * @param {string} key - the storage key of the table (`getStorageKeyFn()`)
+ * @param {string[]} properties - the properties of the columns in the default order
+ * @returns {TableStateIf | undefined} the state, `undefined` if nothing was stored
+ *
+ * @example
+ * localStorage.setItem("orderssortingState", '[{"columnIndex":2,"sortState":"desc"}]');
+ * readLegacyState(localStorage, "orders", ["id", "customer", "total"]);
+ * // → { version: 1, sort: [{ property: "total", sortState: "desc" }] }
+ *
+ * @category Internals
+ * @since 1.1.92
+ */
+export declare function readLegacyState(storage: StateStorageIf, key: string, properties: string[]): TableStateIf | undefined;
+/**
+ * Removes the keys of tables before 1.1.92 (see {@link readLegacyState}).
+ *
+ * @param {StateStorageIf} storage - the storage
+ * @param {string} key - the storage key of the table
+ *
+ * @example
+ * removeLegacyState(localStorage, "orders");
+ *
+ * @category Internals
+ * @since 1.1.92
+ */
+export declare function removeLegacyState(storage: StateStorageIf, key: string): void;

package/lib/table/state/table-state-part.d.ts

@@ -0,0 +1,13 @@
+import { TableStatePart } from './table-state.if.js';
+
+/**
+ * All parts of a {@link TableStateIf}, in the order the table applies them.
+ *
+ * @example
+ * const withoutScroll = ALL_TABLE_STATE_PARTS.filter(part => part !== "scroll");
+ * const state = tableApi.getState(withoutScroll);
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export declare const ALL_TABLE_STATE_PARTS: readonly TableStatePart[];

package/lib/table/state/table-state.if.d.ts

@@ -0,0 +1,181 @@
+import { SortState } from '../data/common/sort-state.type.js';
+
+/**
+ * The id of a row in a {@link TableStateIf} – what {@link AutoRestoreOptionsIf.getRowId} returns.
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export type TableStateRowId = string | number;
+/**
+ * One part of a {@link TableStateIf}. Use it to read or apply only some parts:
+ * `tableApi.getState(["columns", "sort"])`.
+ *
+ * | Part | Content | {@link AutoRestoreOptionsIf} flag |
+ * |---|---|---|
+ * | `columns` | width, order and visibility of the columns | `autoRestoreColumnLayout` |
+ * | `sort` | sorted columns | `autoRestoreSortingState` |
+ * | `scroll` | scroll position | `autoRestoreScrollPosition` |
+ * | `tree` | expanded / collapsed tree nodes | `autoRestoreCollapsedExpandedState` |
+ * | `checked` | checked rows (row checkboxes) | `autoRestoreCheckedState` |
+ * | `selection` | selected rows, columns, cells or ranges | `autoRestoreSelectedState` |
+ * | `headerGroups` | collapsed header groups | `autoRestoreHeaderGroupState` |
+ * | `custom` | data of your application ({@link TableApi.setCustomState}) | `autoRestoreCustomState` |
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export type TableStatePart = "columns" | "sort" | "scroll" | "tree" | "checked" | "selection" | "headerGroups" | "custom";
+/**
+ * The state of a table as plain JSON: column layout, sorting, scroll position, tree, checked and selected rows,
+ * header groups and data of your own. Get it with {@link TableApi.getState}, apply it with
+ * {@link TableApi.applyState} or pass it at the start as {@link TableOptionsIf.initialState} – e.g. to store it on
+ * your server per user. {@link TableOptionsIf.autoRestoreOptions} stores it in `localStorage` for you.
+ *
+ * Every part is optional: a missing part is not applied (the table keeps its current state of that part).
+ * Columns are identified by their property, rows by their id ({@link AutoRestoreOptionsIf.getRowId}) – never by an
+ * index, so the state survives moved columns and rows that arrive in another order. Unknown columns and rows are
+ * ignored. The state holds no cell values – but row ids can be personal data (e.g. an e-mail address as id).
+ *
+ * @example
+ * const state: TableStateIf = tableApi.getState();
+ * localStorage.setItem("orders-layout", JSON.stringify(state));
+ * // later, e.g. in another table:
+ * tableApi.applyState(JSON.parse(localStorage.getItem("orders-layout")!) as TableStateIf);
+ *
+ * @example
+ * // hand-written: "total" first and 240 px wide, "city" hidden, sorted by total descending
+ * const state: TableStateIf = {
+ *   version: 1,
+ *   columns: [{ property: "total", width: 240 }, { property: "id" }, { property: "city", visible: false }],
+ *   sort: [{ property: "total", sortState: "desc" }]
+ * };
+ *
+ * @see Training: [Remember the state](https://gui.expert/training/persist-state/)
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableStateIf {
+    /** Format version, always `1`. */
+    version: 1;
+    /**
+     * The columns in their order (fixed columns included). Columns of the table that are missing here keep their
+     * place; unknown properties are ignored.
+     */
+    columns?: TableColumnStateIf[];
+    /** The sorted columns, the first one is the primary sort key. `[]` = unsorted. */
+    sort?: TableSortStateIf[];
+    /** The scroll position. */
+    scroll?: TableScrollStateIf;
+    /** Expanded / collapsed nodes of a tree table. */
+    tree?: TableTreeStateIf;
+    /** The ids of the checked rows. */
+    checkedRowIds?: TableStateRowId[];
+    /** The selection. */
+    selection?: TableSelectionStateIf;
+    /** The state of the header groups with a toggle. */
+    headerGroups?: TableHeaderGroupStateIf[];
+    /** Data of your application, e.g. the text of a filter field (must be JSON). */
+    custom?: unknown;
+}
+/**
+ * Width, visibility and (by its position in {@link TableStateIf.columns}) order of one column.
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableColumnStateIf {
+    /** The property of the column ({@link ColumnDefIf.property}). */
+    property: string;
+    /** Width in px – only set for columns the user (or `setColumnWidth`) resized; otherwise the width of the code. */
+    width?: number;
+    /** `false` = hidden with {@link TableApi.setColumnVisible} (a collapsed header group is stored separately). */
+    visible?: boolean;
+}
+/**
+ * One sorted column.
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableSortStateIf {
+    /** The property of the column. */
+    property?: string;
+    /** Only for tables without column definitions (and the format before 1.1.92): the column index. */
+    columnIndex?: number;
+    /** `"asc"` or `"desc"`. */
+    sortState: SortState;
+}
+/**
+ * The scroll position.
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableScrollStateIf {
+    /** Horizontal scroll position in px. */
+    left: number;
+    /** Vertical scroll position in px. */
+    top: number;
+    /**
+     * The id of the first visible row. If other rows are at the top after restoring `top` (new data), the table
+     * scrolls to this row.
+     */
+    firstRowId?: TableStateRowId;
+}
+/**
+ * Expanded and collapsed nodes of a tree. Only one of the two lists is set – the shorter one:
+ * `expandedRowIds` = these nodes are expanded, all others collapsed; `collapsedRowIds` = the other way round.
+ * `{ collapsedRowIds: [] }` = all expanded.
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableTreeStateIf {
+    /** These nodes are expanded, all other nodes are collapsed. */
+    expandedRowIds?: TableStateRowId[];
+    /** These nodes are collapsed, all other nodes are expanded. */
+    collapsedRowIds?: TableStateRowId[];
+}
+/**
+ * The selection: rectangles between rows (ids) and columns (properties).
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableSelectionStateIf {
+    /** Everything selected (⌘/Ctrl+A). */
+    allSelected?: boolean;
+    /** The selected rectangles. */
+    ranges: TableStateRangeIf[];
+    /** Rectangles removed from the selection (Ctrl/⌘+Alt-click). */
+    negativeRanges?: TableStateRangeIf[];
+}
+/**
+ * A rectangle of a selection. Without row ids it spans all rows (a selected column), without properties all columns
+ * (a selected row); without `toRowId` / `toProperty` it reaches to the last row / column. Restored in the current
+ * row order: a rectangle between the same first and last row. Tables without column definitions store only
+ * row selections (columns have no property there).
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableStateRangeIf {
+    fromRowId?: TableStateRowId;
+    toRowId?: TableStateRowId;
+    fromProperty?: string;
+    toProperty?: string;
+}
+/**
+ * Collapsed or expanded header group ({@link CellGroupIf} with `toggle: true`).
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export interface TableHeaderGroupStateIf {
+    /** {@link CellGroupIf.id}, otherwise the path of the labels, e.g. `"Customer"` or `"2026/Q1"`. */
+    id: string;
+    /** `true` = collapsed. */
+    closed: boolean;
+}