@guiexpert/table 1.1.91 → 1.1.92

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

@@ -0,0 +1,158 @@
+import { TableScope } from '../table-scope.js';
+import { TableStateIf, TableStatePart } from './table-state.if.js';
+
+/**
+ * Collects and applies the {@link TableStateIf} of one table, stores it ({@link AutoRestoreOptionsIf}) and reports
+ * changes ({@link EventListenerIf.onStateChanged}). One instance per {@link TableScope} (`tableScope.stateService`);
+ * use the methods of {@link TableApi} instead.
+ *
+ * Changes are only marked ({@link markDirty}); after {@link TableOptionsIf.stateChangedDebounceDelay} the dirty
+ * parts are computed once, compared with the last reported state, stored with ONE storage write and reported with
+ * ONE event – no storage access per scroll frame.
+ *
+ * @category Internals
+ * @since 1.1.92
+ */
+export declare class TableStateService {
+    private readonly scope;
+    /** Suffix of the storage key: `<key>tableState`. */
+    static readonly STORAGE_SUFFIX = "tableState";
+    /** Parts that need a pass over all rows: no baseline at the start, computed only when they are used. */
+    private static readonly EXPENSIVE;
+    /** The restore of the first `firstInit()` is running (or has not finished). */
+    private restoring;
+    private started;
+    private destroyed;
+    private readonly dirty;
+    private timer?;
+    /** JSON per part of the last reported (or restored) state. */
+    private readonly lastReported;
+    /** The last reported state – a flush recomputes only the dirty parts. */
+    private reported;
+    /** The scroll position of the last reported state (a number compare – no string prefixes). */
+    private reportedScroll?;
+    /** The last stored JSON (no second write for the same state). */
+    private lastPersisted?;
+    /** The keys before 1.1.92 are removed with the first save of this table. */
+    private legacyRemoved;
+    /** Properties of the sorted columns, primary key first (the header shows only the sort states). */
+    private sortPriority;
+    /** The widths of the column definitions before anything was restored (a width is stored only if it changed). */
+    private readonly initialWidths;
+    /** The state right after the table was built – {@link resetState}. */
+    private defaultState?;
+    /** The state applied at the start: stored state over `initialState`. */
+    private startState;
+    private custom;
+    private warnedNoRowObject;
+    private warnedNoId;
+    constructor(scope: TableScope);
+    /**
+     * First `firstInit()` only, before `tableModel.init()`: reads the start state and applies the header groups
+     * (they decide which column definitions exist).
+     */
+    initBeforeModel(): void;
+    /** After `tableModel.init()`: remembers the defaults, applies the column layout. */
+    initAfterModel(): void;
+    /** After the external filter: tree, sorting, checked rows, selection. */
+    initAfterFilter(): void;
+    /** After the layout (scroll height known): scroll position; the restore is finished. */
+    initAfterLayout(): void;
+    /**
+     * The current state (all parts, or the given ones). Parts that do not apply to the table are left out (e.g. `tree`
+     * without a tree, `columns` without column definitions).
+     *
+     * @param {TableStatePart[]} [parts] - the parts to read, default: all
+     * @returns {TableStateIf} the state
+     */
+    getState(parts?: readonly TableStatePart[]): TableStateIf;
+    /**
+     * Applies the parts of a state (only the parts it contains, optionally only the given ones) and repaints.
+     * Reports the change with `onStateChanged` and stores it.
+     *
+     * @param {Partial<TableStateIf>} state - the state
+     * @param {TableStatePart[]} [parts] - only these parts
+     */
+    applyState(state: Partial<TableStateIf>, parts?: readonly TableStatePart[]): void;
+    /**
+     * Back to the state right after the table was built (the code's column layout, sort icons, header groups, without
+     * the restored state; tree, checked rows and selection when they are stored or were given as `initialState`),
+     * scrolled to the top, custom data removed – and removes the stored state.
+     */
+    resetState(): void;
+    /** Sets the part `custom` (data of the application). */
+    setCustomState(custom: unknown): void;
+    /** The column was sorted by a header click / `sortByColumn` – it becomes the primary sort key. */
+    sortedByColumn(property: string | undefined): void;
+    /**
+     * Marks a part as changed. After {@link TableOptionsIf.stateChangedDebounceDelay} the state is stored and
+     * reported – only if it really changed. No effect before the table is built.
+     *
+     * @param {TableStatePart} part - the changed part
+     */
+    markDirty(part: TableStatePart): void;
+    /** Called after each render pass: marks the scroll position as changed if it changed. */
+    rendered(): void;
+    /**
+     * Stores and reports the dirty parts now (normally called by the timer of {@link markDirty}).
+     */
+    flush(): void;
+    /** Stops the timer and stores / reports a pending change (called by `TableScope.destroy()`). */
+    destroy(): void;
+    private storageKey;
+    private storage;
+    /** The parts switched on in {@link AutoRestoreOptionsIf}. */
+    private persistedParts;
+    private warnWithoutStorageKey;
+    /** The stored state (or the one of the keys before 1.1.92) over `tableOptions.initialState`. */
+    private readStartState;
+    private persist;
+    private rememberAsReported;
+    private partJson;
+    private computePart;
+    private computeColumns;
+    private computeSort;
+    private computeScroll;
+    private computeTree;
+    private computeChecked;
+    private computeSelection;
+    /**
+     * A cell range → ids and properties. A range to the last row / column (`MAX_SAFE_INTEGER`) has no `toRowId` /
+     * `toProperty` ("to the end"); a range over all rows / columns has neither.
+     */
+    private toStateRange;
+    /** @returns true if a group changed */
+    private applyHeaderGroups;
+    /**
+     * Order, visibility and widths of the columns.
+     *
+     * @param {TableColumnStateIf[]} columns - the stored columns
+     * @param {boolean} resetMissingWidths - columns without width get the width of the code back (applyState)
+     * @returns true if the widths must be recalculated (a `%` or weight width came back)
+     */
+    private applyColumns;
+    private applyTree;
+    private applySort;
+    private applyChecked;
+    private applySelection;
+    private applyScroll;
+    private columnDefs;
+    private body;
+    private headerGroupModel;
+    /** Warn about rows without id only for parts that are stored (a `getState()` for an own use stays quiet). */
+    private warns;
+    /** The own `getRowId`, `undefined` for the default of {@link AutoRestoreOptions} (or none). */
+    private ownGetRowId;
+    /** The id of the displayed row at `index`. */
+    private idAt;
+    /**
+     * The id of a row (tree rows: of `row.data`): an own `getRowId`, otherwise the property `id` or `uuid`. Rows
+     * without id are not stored – the JSON fallback of the default `getRowId` would write whole rows (personal data)
+     * into the storage. Rows without an object get an id only from an own `getRowId` that declares the second
+     * parameter (`(_row, rowIndex) => rowIndex`).
+     */
+    private idOfRow;
+    /** id → displayed row index (one pass over the displayed rows). */
+    private rowIndexMap;
+    private walkTree;
+}

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

@@ -1,3 +1,5 @@
+import { GeOverlayKind } from './overlay/ge-overlay-kind.type.js';
+import { TableStateIf, TableStatePart } from './state/table-state.if.js';
 import { SortState } from './data/common/sort-state.type.js';
 import { TableScope } from './table-scope.js';
 import { ColumnDefIf } from './data/tablemodel/column/column-def.if.js';
@@ -36,6 +38,7 @@ import { AreaModelIf } from './data/tablemodel/areamodel/area-model.if.js';
  * | redraw | {@link repaint} (same row count), {@link repaintHard} (row count or heights changed) |
  * | columns | {@link autoResizeColumns}, {@link setColumnWidth}, {@link recalcColumnWidths} |
  * | tree | {@link expandAll}, {@link collapseAll}, {@link setRowExpanded} |
+ * | state | {@link getState}, {@link applyState}, {@link resetState} (with {@link TableOptionsIf.autoRestoreOptions}) |
  * | lifecycle | {@link destroy} |
  *
  * @example
@@ -605,6 +608,157 @@ export declare class TableApi {
      * @see Training: [Accessible tables: keyboard and screen readers](https://gui.expert/training/accessibility/)
      */
     announce(text: string): void;
+    /**
+     * Shows "Loading…" with a CSS spinner over the body – e.g. while a server answers. The header and footer stay
+     * readable; rows already shown stay visible under a semi-transparent layer. By default mouse and editing on the
+     * body are blocked until {@link hideOverlay} ({@link OverlayOptionsIf.blockInteractionWhileLoading}).
+     * Screen readers: the host gets `aria-busy="true"`, the text is announced.
+     *
+     * Texts, delay and own content: {@link TableOptionsIf.overlayOptions}. Framework wrappers have a `loading` prop
+     * that calls this method (no re-creation of the table).
+     *
+     * @example
+     * tableApi.showLoadingOverlay();
+     * fetch("/api/orders")
+     *   .then(response => response.json())
+     *   .then((orders: object[]) => {
+     *     tableApi.setRows(orders);
+     *     tableApi.repaintHard();
+     *   })
+     *   .finally(() => tableApi.hideOverlay()); // 0 rows? "No rows to show" appears by itself
+     *
+     * @param {string} [text] - text for this overlay only, e.g. `"Saving…"`; default {@link OverlayOptionsIf.loadingText}
+     * @since 1.1.92
+     * @see Training: [Live data](https://gui.expert/training/live-data/)
+     */
+    showLoadingOverlay(text?: string): void;
+    /**
+     * Shows the "no rows" overlay, also over rows – e.g. when the server says "no permission". An empty body shows
+     * "No rows to show" anyway ({@link OverlayOptionsIf.autoNoRows}); this method is for other cases.
+     * Ends with {@link hideOverlay}.
+     *
+     * @example
+     * tableApi.showNoRowsOverlay("You may not see these orders");
+     *
+     * @param {string} [text] - text for this overlay only; default {@link OverlayOptionsIf.noRowsText}
+     * @since 1.1.92
+     */
+    showNoRowsOverlay(text?: string): void;
+    /**
+     * Ends the overlay shown by {@link showLoadingOverlay} or {@link showNoRowsOverlay}.
+     * "No rows to show" / "No matching rows" are not ended: they show the state of the body and stay as long as it
+     * is empty (switch them off with `overlayOptions: { autoNoRows: false }`).
+     *
+     * @example
+     * tableApi.showLoadingOverlay("Saving…");
+     * save(order).finally(() => tableApi.hideOverlay());
+     *
+     * @since 1.1.92
+     */
+    hideOverlay(): void;
+    /**
+     * The overlay shown now: `"none"`, `"loading"`, `"noRows"` or `"noMatches"`. During
+     * {@link OverlayOptionsIf.loadingDelayInMs} the loading overlay is requested but not shown yet – the automatic
+     * overlay stays meanwhile (e.g. `"noRows"` of an empty table), so a fast answer causes no flicker.
+     *
+     * @example
+     * if (tableApi.getOverlayState() === "noMatches") {
+     *   resetFilterButton.hidden = false;
+     * }
+     *
+     * @returns {GeOverlayKind} the shown overlay
+     * @since 1.1.92
+     */
+    getOverlayState(): GeOverlayKind;
+    /**
+     * The state of the table as plain JSON: column layout (order, widths, visibility), sorting, scroll position,
+     * expanded tree nodes, checked and selected rows, header groups and your own data ({@link setCustomState}).
+     * Columns are identified by property and rows by id ({@link AutoRestoreOptionsIf.getRowId}), never by index.
+     * Parts that do not apply to this table are left out (e.g. `tree` for a flat table).
+     *
+     * Store it wherever you like and give it back with {@link applyState} or {@link TableOptionsIf.initialState};
+     * {@link TableOptionsIf.autoRestoreOptions} does this for you in `localStorage`.
+     *
+     * @param {TableStatePart[]} [parts] - only these parts, default: all
+     * @returns {TableStateIf} the state
+     *
+     * @example
+     * const state = tableApi.getState();                       // { version: 1, columns: [...], sort: [...], ... }
+     * await fetch("/api/prefs/orders", { method: "PUT", body: JSON.stringify(state) });
+     *
+     * @example
+     * const layout = tableApi.getState(["columns", "sort"]);   // only the layout, no scroll position or selection
+     *
+     * @see Training: [Remember the state](https://gui.expert/training/persist-state/)
+     * @since 1.1.92
+     */
+    getState(parts?: TableStatePart[]): TableStateIf;
+    /**
+     * Applies a state from {@link getState} (or one written by hand) and repaints. Only the parts contained in the
+     * state are applied (optionally only the given ones); the others stay as they are – pass a part empty to reset it,
+     * e.g. `sort: []` (clears the sort icons; the rows keep their current order). Unknown columns and rows are ignored. The change is stored ({@link TableOptionsIf.autoRestoreOptions})
+     * and reported ({@link EventListenerIf.onStateChanged}).
+     *
+     * @param {Partial<TableStateIf>} state - the state
+     * @param {TableStatePart[]} [parts] - only these parts, default: all parts of the state
+     *
+     * @example
+     * // two saved views of the same table
+     * const views: Record<string, TableStateIf> = {};
+     * views["compact"] = tableApi.getState(["columns"]);
+     * tableApi.applyState(views["compact"]);
+     *
+     * @example
+     * tableApi.applyState({ sort: [{ property: "total", sortState: "desc" }] });
+     *
+     * @since 1.1.92
+     */
+    applyState(state: Partial<TableStateIf>, parts?: TableStatePart[]): void;
+    /**
+     * Back to the state of the code: column layout, sort icons and header groups as they were right after the table was
+     * built (before a stored state was applied) – tree, checked and selected rows too when they are remembered
+     * ({@link TableOptionsIf.autoRestoreOptions}) or given as {@link TableOptionsIf.initialState} –, scrolled to the top,
+     * custom data removed. Deletes the stored state. The rows keep their current order (a table has no "unsorted" order
+     * to go back to); only the sort icons of the code come back.
+     *
+     * @example
+     * document.querySelector("#reset-layout")!.addEventListener("click", () => tableApi.resetState());
+     *
+     * @since 1.1.92
+     */
+    resetState(): void;
+    /**
+     * Stores data of your application with the table state (part `custom`), e.g. the text of a filter field. It is
+     * reported with {@link EventListenerIf.onStateChanged}, stored with `autoRestoreCustomState` and returned by
+     * {@link getState} – also after a reload, so you can restore your filter in `tableReady`. Must be JSON.
+     *
+     * @param {unknown} custom - your data (JSON)
+     *
+     * @example
+     * filterInput.addEventListener("input", () => {
+     *   tableApi.setCustomState({ filter: filterInput.value });
+     *   tableApi.externalFilterChanged();
+     * });
+     * // after a reload (tableReady):
+     * const custom = tableApi.getState(["custom"]).custom as { filter?: string } | undefined;
+     * filterInput.value = custom?.filter ?? "";
+     *
+     * @since 1.1.92
+     */
+    setCustomState(custom: unknown): void;
+    /**
+     * Collapses or expands a header group ({@link CellGroupIf} with `toggle: true`) – like a click on its toggle.
+     *
+     * @param {string} id - {@link CellGroupIf.id}, otherwise the path of the labels, e.g. `"Customer"` or `"2026/Q1"`
+     * @param {boolean} collapsed - true = collapse
+     * @returns {boolean} false if the header has no such group
+     *
+     * @example
+     * tableApi.setHeaderGroupCollapsed("Customer", true);
+     *
+     * @since 1.1.92
+     */
+    setHeaderGroupCollapsed(id: string, collapsed?: boolean): boolean;
     /**
      * The header cell that has the keyboard focus. Arrow up in the first body row moves the focus into the header
      * (Enter sorts or opens/closes a header group there); arrow down leaves it. The {@link FocusModelIf} holds

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

@@ -1,3 +1,5 @@
+import { TableOverlayChange } from './overlay/table-overlay.js';
+import { GeOverlayKind } from './overlay/ge-overlay-kind.type.js';
 import { TableModelIf } from './data/tablemodel/table-model.if.js';
 import { AreaIdent } from './data/tablemodel/area-ident.type.js';
 import { GeMouseEvent } from './data/common/event/ge-mouse-event.js';
@@ -10,6 +12,9 @@ import { SortState } from './data/common/sort-state.type.js';
 import { StoreStateCollapsedExpandService } from './service/store-state-collapsed-expand.service.js';
 import { StoreStateSortingService } from './service/store-state-sorting.service.js';
 import { RenderScope } from './render-scope.js';
+import { SortItem } from './data/common/sort-item.js';
+import { TableStateService } from './state/table-state.service.js';
+import { GeStateChangeEvent } from './data/common/event/ge-state-change-event.js';
 import { InputHandler } from './input-handler.js';
 import { SelectionService } from './selection/selection-service.js';
 import { GeKeyEvent } from './data/common/event/ge-key-event.js';
@@ -72,8 +77,16 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     inputHandler: InputHandler;
     resizeHandler: ResizeHandler;
     shortcutService: ShortcutService;
+    /** @deprecated since 1.1.92 – always `undefined`; the state is kept by {@link stateService}. */
     storeStateCollapsedExpandService?: StoreStateCollapsedExpandService;
+    /** @deprecated since 1.1.92 – always `undefined`; the state is kept by {@link stateService}. */
     storeSortingService?: StoreStateSortingService;
+    /**
+     * Collects, applies, stores and reports the state of this table (column layout, sorting, scroll, tree, checked
+     * and selected rows …). Use {@link TableApi.getState} / {@link TableApi.applyState}.
+     * @since 1.1.92
+     */
+    readonly stateService: TableStateService;
     protected selectionService: SelectionService;
     protected keyEvent?: GeKeyEvent;
     private api;
@@ -83,8 +96,12 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @since 1.1.91
      */
     readonly liveAnnouncer: LiveAnnouncer;
+    /** Keyboard actions ignored while a blocking loading overlay is shown ({@link OverlayOptionsIf.blockInteractionWhileLoading}). */
+    static actionsBlockedWhileLoading: ActionId[];
     /** Delay of the "42 rows" announcement after a filter change (typing in a filter field: one announcement). */
     static filterAnnouncementDelayInMs: number;
+    /** The text announced when the loading overlay appeared (dropped if loading ends before it is spoken). */
+    private lastLoadingAnnouncement?;
     /** firstInit() has finished: announcements are made from now on (not for the initial filter). */
     private initialized;
     private mouseStartAction;
@@ -135,6 +152,38 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @since 1.1.91
      */
     announce(text: string, delayInMs?: number): void;
+    /**
+     * Shows the loading overlay over the body (see {@link TableApi.showLoadingOverlay}).
+     *
+     * @param {string} [text] - text for this overlay, default {@link OverlayOptionsIf.loadingText}
+     * @since 1.1.92
+     */
+    showLoadingOverlay(text?: string): void;
+    /**
+     * Shows the "no rows" overlay (see {@link TableApi.showNoRowsOverlay}).
+     *
+     * @param {string} [text] - text for this overlay, default {@link OverlayOptionsIf.noRowsText}
+     * @since 1.1.92
+     */
+    showNoRowsOverlay(text?: string): void;
+    /**
+     * Ends an overlay shown by the API (see {@link TableApi.hideOverlay}).
+     *
+     * @since 1.1.92
+     */
+    hideOverlay(): void;
+    /**
+     * The overlay shown now (see {@link TableApi.getOverlayState}).
+     *
+     * @since 1.1.92
+     */
+    getOverlayState(): GeOverlayKind;
+    /**
+     * Screen readers: `aria-busy` while loading, the loading text is spoken; "no rows" is spoken when it appears
+     * after the start (not for the initially empty table). "No matching rows" is not spoken: the filter
+     * announcement ({@link AriaTextsIf.filtered}) already says it.
+     */
+    protected onOverlayChanged(change: TableOverlayChange): void;
     /** "12 cells copied" – the selected cells of the shown columns (without a selection: the focused cell). */
     announceCopied(_text?: string): void;
     /** The number of cells a copy takes: selected cells of shown columns (like CopyService), otherwise 1 (focus). */
@@ -280,8 +329,6 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @returns {boolean} false if the body is no tree or the state was already set
      */
     setTreeRowExpanded(row: TreeRowIf<any>, expanded: boolean): boolean;
-    /** Remembers the expanded/collapsed state of a row (autoRestoreOptions.getRowId). */
-    private storeTreeRowState;
     /**
      * Toggles the checkbox state of a specific row in a table.
      *
@@ -309,6 +356,12 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     cancelPendingRepaint(): boolean;
     publishGeMouseEvent(evt: GeMouseEvent): void;
     onFocusChanged(sm: FocusModelIf): void;
+    /**
+     * Reports a changed state to the event listener (called by {@link TableStateService}).
+     * @since 1.1.92
+     */
+    stateChanged(evt: GeStateChangeEvent): void;
+    protected afterRenderPass(): void;
     onSelectionChanged(sm: SelectionModelIf): void;
     private selectionEventsHeld;
     private heldSelectionModel?;
@@ -387,6 +440,21 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      */
     setSelectionModel(sm: SelectionModel, rerender?: boolean): void;
     toggleHeaderGroup(mouseTargetData: MouseTargetData): void;
+    /**
+     * Collapses or expands a header group by its id ({@link TableApi.setHeaderGroupCollapsed}).
+     *
+     * @param {string} id - {@link CellGroupIf.id} or the path of the labels, e.g. `"Customer"`
+     * @param {boolean} collapsed - true = collapse
+     * @returns {boolean} false if the header has no such group
+     * @since 1.1.92
+     */
+    setHeaderGroupCollapsed(id: string, collapsed: boolean): boolean;
+    /**
+     * Rebuilds the layout after a header group was collapsed or expanded (other columns are shown) and marks the
+     * state as changed.
+     * @since 1.1.92
+     */
+    headerGroupsChanged(): void;
     /**
      * Retrieves the selection model.
      * @returns {SelectionModelIf | undefined} The selection model if available, otherwise undefined.
@@ -426,35 +494,6 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {void}
      */
     private clearSelectionModel;
-    /**
-     * Restores the scroll position of the table if auto restore options are enabled.
-     *
-     *
-     * @returns {void}
-     */
-    private autoRestoreScrollPosition;
-    /**
-     * Automatically restores the sorting state of the table.
-     *
-     * @private
-     * @function autoRestoreSortingState
-     * @memberof ClassName
-     *
-     * @description
-     * This method checks if the autoRestoreSortingState option is enabled in the tableOptions.
-     * If enabled, it uses the storeSortingService to retrieve the sort items array.
-     * If there are sort items present, it applies them to the table's body model using the doSort method.
-     *
-     * @returns {void}
-     */
-    private autoRestoreSortingState;
-    /**
-     * Restores the collapsed/expanded state of the rows in the table based on the autoRestoreOptions
-     * specified in the tableOptions. This method is private and should not be called directly.
-     *
-     * @private
-     */
-    private autoRestoreCollapsedExpandedState;
     /**
      * Calculates a width per column that fits the widest text of header, body and footer.
      *
@@ -492,6 +531,14 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     recalcWrappers(): void;
     reSort(): void;
     sort(compareFn: (a: any, b: any) => number): void;
+    /**
+     * Sorts the body by the given items (first = primary key) and sets the header icons – used to apply a stored
+     * state. Does not repaint.
+     *
+     * @param {SortItem[]} sortItems - column index and sort state per sorted column; `[]` only clears the icons
+     * @since 1.1.92
+     */
+    applySortItems(sortItems: SortItem[]): void;
     /**
      * Sorts the (freshly filtered) body rows again, so a filter keeps the current order:
      * the last `sort(compareFn)` call, otherwise the columns with a `sortState` (header icons).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.91",
+  "version": "1.1.92",
   "license": "MIT",
   "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
   "repository": {