@guiexpert/table 1.1.90 → 1.1.92

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

@@ -1,16 +1,17 @@
-import { DomServiceIf } from './dom-service.if';
-import { DivScope } from './../data/div-scope.type';
-import { GeoData } from './../data/geo-data';
-import { TreeArrowType } from '../data/common/tree-arrow.type';
-import { TreeOptionsIf } from '../data/options/tree-options.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { TableOptionsIf } from '../data/options/table-options.if';
-import { CheckedType } from '../data/common/checked-type';
-import { SideIdent } from '../data/side-ident.type';
-import { SortState } from '../data/common/sort-state.type';
-import { SortedOptionsIf } from '../data/options/sorted-options.if';
-import { HtmlStyle } from './data/html-style.type';
+import { DomServiceIf } from './dom-service.if.js';
+import { DivScope } from './../data/div-scope.type.js';
+import { GeoData } from './../data/geo-data.js';
+import { TreeArrowType } from '../data/common/tree-arrow.type.js';
+import { TreeOptionsIf } from '../data/options/tree-options.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { CheckedType } from '../data/common/checked-type.js';
+import { SideIdent } from '../data/side-ident.type.js';
+import { SortState } from '../data/common/sort-state.type.js';
+import { SortedOptionsIf } from '../data/options/sorted-options.if.js';
+import { HtmlStyle } from './data/html-style.type.js';
 
+/** @category DOM */
 export interface AddColumnDivPara {
     parent: HTMLDivElement;
     geo: GeoData;
@@ -23,9 +24,14 @@ export interface AddColumnDivPara {
     tableOptions?: TableOptionsIf;
     checkedType?: CheckedType | undefined;
     sortState?: SortState;
+    /** Accessible name of the row checkbox (`showCheckboxWihoutExtraColumn`), e.g. "Select row 5". @since 1.1.91 */
+    checkboxAriaLabel?: string;
 }
+/** @category DOM */
 export declare class ConvenienceDomService {
     readonly domService: DomServiceIf;
+    /** Width of the focus frame of a cell in px (WCAG 2.4.7: visible focus, not only a color). @since 1.1.91 */
+    static focusBorderWidthInPx: number;
     constructor(domService: DomServiceIf);
     setStyle(el: any, style: string, value: any): any;
     applyStyle(ele: HTMLDivElement, style: HtmlStyle): HTMLDivElement;
@@ -35,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;
@@ -43,16 +49,33 @@ export declare class ConvenienceDomService {
     removeClass(clazz: string, div: HTMLDivElement): HTMLDivElement;
     addClasses(classes: string[] | undefined, div: HTMLDivElement): HTMLDivElement;
     setAttribute(div: HTMLDivElement, key: string, value: string): HTMLDivElement;
+    /**
+     * Removes an attribute (via {@link DomServiceIf.removeAttribute} if the DOM service has it).
+     *
+     * @since 1.1.91
+     */
+    removeAttribute(ele: HTMLElement, key: string): HTMLElement;
+    /**
+     * Hides a purely decorative element (border, hover, icon …) from screen readers: `aria-hidden="true"`.
+     *
+     * @since 1.1.91
+     */
+    setAriaHidden<T extends HTMLElement>(ele: T): T;
     createAreaDivWithClass(clazz: string, parent: HTMLDivElement, areaIdent: AreaIdent, sideIdent: SideIdent): HTMLDivElement;
     createDivWithClass(clazz: string, parent: HTMLDivElement): HTMLDivElement;
     addRowDiv(divScope: DivScope, geo: GeoData, rowIndex: number | undefined, areaIdent: AreaIdent, sideIdent: SideIdent, text?: string): HTMLDivElement;
     addColumnDiv(para: AddColumnDivPara): HTMLDivElement;
-    addCheckboxToDiv(parent: HTMLDivElement, checkedType: CheckedType, areaIdent: AreaIdent, rowIndex: number): HTMLDivElement;
+    addCheckboxToDiv(parent: HTMLDivElement, checkedType: CheckedType, areaIdent: AreaIdent, rowIndex: number, ariaLabel?: string): HTMLDivElement;
     addLabelDiv(parent: HTMLDivElement, text?: string, firstTreeColumn?: boolean, rowIndex?: number, columnIndex?: number, areaIdent?: AreaIdent): HTMLDivElement;
     addSortedIcon(parent: HTMLDivElement, sorted?: SortState, sortedOptions?: SortedOptionsIf, columnIndex?: number): HTMLDivElement;
     addArrowDiv(parent: HTMLDivElement, arrow?: TreeArrowType, treeOptions?: TreeOptionsIf, rowIndex?: number, columnIndex?: number, areaIdent?: AreaIdent): HTMLDivElement;
     addColumnBorderDivs(tableOptions: TableOptionsIf, parent: HTMLDivElement, geo: GeoData, areaIdent: AreaIdent, sideIdent: SideIdent): HTMLDivElement;
     addHorizontalBorder(geo: GeoData, parent: HTMLDivElement, clazz?: string): HTMLDivElement;
+    /**
+     * Draws the focus frame of a cell: four divs with the class `ge-table-focus-border` (2 px, color
+     * `--ge-table-focus-outline-color` resp. `--ge-table-focus-border`). Hidden from screen readers – they get the
+     * focus through `aria-activedescendant`.
+     */
     addFocusBorderDivs(parent: HTMLDivElement, geo: GeoData, style: HtmlStyle): HTMLDivElement;
     addVerticalBorder(geo: GeoData, parent: HTMLDivElement, clazz?: string): HTMLDivElement;
     addDiv(parent: HTMLDivElement, geo: GeoData, clazz?: string): HTMLDivElement;

package/lib/table/service/copy-service.d.ts

@@ -1,14 +1,28 @@
-import { TableModelIf } from '../data/tablemodel/table-model.if';
-import { SelectionModelIf } from '../selection/selection-model.if';
-import { FocusModelIf } from '../focus/focus-model.if';
-import { CopyServiceIf } from './copy-service.if';
+import { TableModelIf } from '../data/tablemodel/table-model.if.js';
+import { SelectionModelIf } from '../selection/selection-model.if.js';
+import { FocusModelIf } from '../focus/focus-model.if.js';
+import { CopyServiceIf } from './copy-service.if.js';
 
+/** @category Export & clipboard */
 export declare class CopyService implements CopyServiceIf {
+    /**
+     * Upper limit for the number of cells {@link createContent} copies (e.g. after Ctrl+A on a table with millions
+     * of rows). Larger selections are rejected instead of building a huge string and blocking the browser.
+     *
+     * @example
+     * CopyService.maxCopyCells = 5_000_000; // allow bigger copies
+     */
+    static maxCopyCells: number;
     static columnSeparatorChar: string;
     static rowSeparatorChar: string;
     /**
      * Returns the content to be copied based on the provided table model, selection model, and focus model.
      *
+     * - Selection: the bounding box of all selected ranges, one line per row, cells separated by TAB; cells inside the
+     *   box that are not selected become empty strings, hidden columns are left out.
+     * - Everything selected ({@link SelectionModelIf.selectAll}, ⌘/Ctrl+A): all displayed body rows × all columns.
+     * - No selection: the text of the focused cell.
+     *
      * @param {TableModelIf} tableModel - The table model for data retrieval.
      * @param {SelectionModelIf} selectionModel - The selection model to determine the selected range.
      * @param {FocusModelIf} focusModel - The focus model to determine the focused cell.

package/lib/table/service/copy-service.if.d.ts

@@ -1,7 +1,8 @@
-import { TableModelIf } from '../data/tablemodel/table-model.if';
-import { SelectionModelIf } from '../selection/selection-model.if';
-import { FocusModelIf } from '../focus/focus-model.if';
+import { TableModelIf } from '../data/tablemodel/table-model.if.js';
+import { SelectionModelIf } from '../selection/selection-model.if.js';
+import { FocusModelIf } from '../focus/focus-model.if.js';
 
+/** @category Export & clipboard */
 export interface CopyServiceIf {
     /**
      * Copies the selected data from the table to the clipboard.

package/lib/table/service/data/collapsed-expanded.data.d.ts

@@ -1,3 +1,4 @@
+/** @category Internals */
 export declare class CollapsedExpandedData {
     mode: "collapsed" | "expanded";
     rowIds: Array<string | number>;

package/lib/table/service/data/html-style.type.d.ts

@@ -1,3 +1,4 @@
+/** @category DOM */
 export type HtmlStyle = {
     [key: string]: string | number;
 };

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

@@ -1,10 +1,40 @@
+/**
+ * All DOM changes of the table go through this service – the third argument of `new TableScope(…)`.
+ * Plain TypeScript and most wrappers use {@link SimpleDomService}; Angular uses its `Renderer2`.
+ * Cell renderers get it as last argument of {@link CellRendererIf.render}.
+ *
+ * @example
+ * // inside CellRendererIf.render(cellDiv, …, cellValue, dom)
+ * const badge = dom.createElement<HTMLSpanElement>("span");
+ * dom.addClass(badge, "status-badge");
+ * dom.setStyle(badge, "margin-left", "4px");
+ * badge.textContent = String(cellValue);
+ * dom.appendChild(cellDiv, badge);
+ *
+ * @category DOM
+ */
 export interface DomServiceIf {
+    /** Sets one CSS property: `setStyle(el, "background-color", "#fdf2f8")`. */
     setStyle(el: any, style: string, value: any): any;
+    /** Adds a CSS class. */
     addClass(div: HTMLElement, clazz: string): HTMLDivElement;
+    /** Removes a CSS class. */
     removeClass(div: HTMLElement, clazz: string): HTMLDivElement;
+    /** Creates an element: `createElement<HTMLSpanElement>("span")`. */
     createElement<T>(ele: string): T;
+    /** Creates a text node. */
     createText(text: string): HTMLElement;
+    /** Appends text to an element (no HTML parsing). */
     appendText(parent: HTMLDivElement, text: string): HTMLDivElement;
+    /** Appends a child element. */
     appendChild(parent: HTMLElement, child: HTMLElement): void;
+    /** Sets an attribute. */
     setAttribute(ele: HTMLElement, key: string, value: string): void;
+    /**
+     * Removes an attribute (used for ARIA attributes of reused row divs). Optional: without it the table calls
+     * `ele.removeAttribute(key)` itself.
+     *
+     * @since 1.1.91
+     */
+    removeAttribute?(ele: HTMLElement, key: string): void;
 }

package/lib/table/service/excel-service.d.ts

@@ -1,5 +1,28 @@
-import { ExcelServiceIf } from './excel-service.if';
+import { ExcelServiceIf } from './excel-service.if.js';
 
+/**
+ * Writes real `.xlsx` files (Office Open XML) without any library – compressed with the browser's
+ * built-in `CompressionStream`. Numbers stay numbers, everything else becomes text.
+ *
+ * {@link TableApi.downloadExcel} exports what the table shows; use the ExcelService directly for any other data.
+ *
+ * @example
+ * // all rows, own columns – independent of filter and sorting
+ * const body = tableApi.getBodyModel() as AreaModelObjectArray<Order>;
+ * const matrix = [
+ *   ["ID", "Customer", "Total"],
+ *   ...body.getAllRows().map(o => [o.id, o.customer, o.total])
+ * ];
+ * await new ExcelService().downloadExcel(matrix, "orders.xlsx", "GuiExpert");
+ *
+ * @example
+ * // a Blob instead of a download, e.g. for an upload
+ * const blob = await new ExcelService().createExcelBlob(matrix);
+ *
+ * @see Training: [Excel export without a library](https://gui.expert/training/excel-export/)
+ *
+ * @category Export & clipboard
+ */
 export declare class ExcelService implements ExcelServiceIf {
     /**
      * Downloads a matrix data as an Excel file.

package/lib/table/service/excel-service.if.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Writes an Excel file from a matrix of values. The default implementation is {@link ExcelService};
+ * pass your own as last argument of the `TableScope` constructor to change how {@link TableApi.downloadExcel} exports.
+ *
+ * @category Export & clipboard
+ */
 export interface ExcelServiceIf {
+    /** Creates the file from `matrix` (rows of values) and hands it to the browser as download. */
     downloadExcel(matrix: Array<Array<any>>, filename: string, author?: string): void | Promise<void>;
 }

package/lib/table/service/ge-filter.service.d.ts

@@ -1,3 +1,4 @@
+/** @category Sorting & filtering */
 export declare class GeFilterService {
     filterPredict<T>(item: T, filterString: string, toString?: (t: T) => string): boolean;
     filterRows<T>(rows: T[], filterString: string, toString?: (t: T) => string): T[];

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

@@ -1,5 +1,6 @@
-import { DomServiceIf } from './dom-service.if';
+import { DomServiceIf } from './dom-service.if.js';
 
+/** @category DOM */
 export declare class SimpleDomService implements DomServiceIf {
     setStyle(el: any, style: string, value: any): any;
     appendText(parent: HTMLDivElement, text: string): HTMLDivElement;
@@ -9,4 +10,5 @@ export declare class SimpleDomService implements DomServiceIf {
     createElement<T>(name: string): T;
     createText(value: string): any;
     setAttribute(ele: HTMLElement, key: string, value: string): void;
+    removeAttribute(ele: HTMLElement, key: string): void;
 }

package/lib/table/service/store-state-collapsed-expand.service.d.ts

@@ -1,7 +1,8 @@
-import { AbstractStoreStateService } from './abstract-store-state.service';
-import { CollapsedExpandedData } from './data/collapsed-expanded.data';
-import { GetStorageKeyFn } from '../data/options/auto-restore-options.if';
+import { AbstractStoreStateService } from './abstract-store-state.service.js';
+import { CollapsedExpandedData } from './data/collapsed-expanded.data.js';
+import { GetStorageKeyFn } from '../data/options/auto-restore-options.if.js';
 
+/** @category Internals */
 export declare class StoreStateCollapsedExpandService extends AbstractStoreStateService {
     private readonly COLLAPSED_EXPANDED_STATE;
     private collapsedExpandedState;

package/lib/table/service/store-state-scroll-pos.service.d.ts

@@ -1,6 +1,7 @@
-import { AbstractStoreStateService } from './abstract-store-state.service';
-import { GetStorageKeyFn } from '../data/options/auto-restore-options.if';
+import { AbstractStoreStateService } from './abstract-store-state.service.js';
+import { GetStorageKeyFn } from '../data/options/auto-restore-options.if.js';
 
+/** @category Internals */
 export declare class StoreStateScrollPosService extends AbstractStoreStateService {
     private readonly SCROLL_STATE;
     private scrollOffset;

package/lib/table/service/store-state-sorting.service.d.ts

@@ -1,7 +1,8 @@
-import { AbstractStoreStateService } from './abstract-store-state.service';
-import { GetStorageKeyFn } from '../data/options/auto-restore-options.if';
-import { SortItem } from '../data/common/sort-item';
+import { AbstractStoreStateService } from './abstract-store-state.service.js';
+import { GetStorageKeyFn } from '../data/options/auto-restore-options.if.js';
+import { SortItem } from '../data/common/sort-item.js';
 
+/** @category Internals */
 export declare class StoreStateSortingService extends AbstractStoreStateService {
     private readonly SORTING_STATE;
     private sortItems;

package/lib/table/service/tree-row.service.d.ts

@@ -1,6 +1,10 @@
-import { TreeRowIf } from '../data/common/tree-row-if';
+import { TreeRowIf } from '../data/common/tree-row-if.js';
 
+/** @category Tree & checkboxes */
 export declare class TreeRowService {
     flattenTree<T>(rows: TreeRowIf<T>[], ret?: TreeRowIf<T>[]): TreeRowIf<T>[];
+    /** The children of a visible, expanded row are visible – collapsed subtrees are not walked at all
+     *  (before, every node of the tree was visited and checked up to the root on every expand/collapse). */
+    private flattenVisibleChildren;
     isVisible(row: TreeRowIf<any>): boolean;
 }

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;
+}