@guiexpert/table 1.1.90 → 1.1.91

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

@@ -1,57 +1,61 @@
-import { TableModelIf } from './data/tablemodel/table-model.if';
-import { AreaIdent } from './data/tablemodel/area-ident.type';
-import { GeMouseEvent } from './data/common/event/ge-mouse-event';
-import { DomServiceIf } from './service/dom-service.if';
-import { TableOptionsIf } from './data/options/table-options.if';
-import { MouseHandler } from './mouse-handler';
-import { EventListenerIf } from './event-listener.if';
-import { TableApi } from './table-api';
-import { SortState } from './data/common/sort-state.type';
-import { StoreStateCollapsedExpandService } from './service/store-state-collapsed-expand.service';
-import { StoreStateSortingService } from './service/store-state-sorting.service';
-import { RenderScope } from './render-scope';
-import { InputHandler } from './input-handler';
-import { SelectionService } from './selection/selection-service';
-import { GeKeyEvent } from './data/common/event/ge-key-event';
-import { OnActionTriggeredIf } from './action/on-action-triggered.if';
-import { ActionId } from './action/action-id.type';
-import { ShortcutService } from './action/shortcut.service';
-import { LicenseManager } from './license-manager';
-import { SelectionModel } from './selection/selection-model';
-import { CopyServiceIf } from './service/copy-service.if';
-import { MouseTargetData } from './data/event/mouse-target-data';
-import { SelectionModelIf } from './selection/selection-model.if';
-import { FocusModelIf } from './focus/focus-model.if';
-import { EventFocusChangedListenerIf } from './focus/event-focus-changed-listener.if';
-import { EventSelectionChangedListenerIf } from './selection/event-selection-changed-listener.if';
-import { ResizeHandler } from './resize-handler';
-import { ExcelServiceIf } from './service/excel-service.if';
+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';
+import { DomServiceIf } from './service/dom-service.if.js';
+import { TableOptionsIf } from './data/options/table-options.if.js';
+import { MouseHandler } from './mouse-handler.js';
+import { EventListenerIf } from './event-listener.if.js';
+import { TableApi } from './table-api.js';
+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 { InputHandler } from './input-handler.js';
+import { SelectionService } from './selection/selection-service.js';
+import { GeKeyEvent } from './data/common/event/ge-key-event.js';
+import { OnActionTriggeredIf } from './action/on-action-triggered.if.js';
+import { ActionId } from './action/action-id.type.js';
+import { ShortcutService } from './action/shortcut.service.js';
+import { TreeRowIf } from './data/common/tree-row-if.js';
+import { LicenseManager } from './license-manager.js';
+import { SelectionModel } from './selection/selection-model.js';
+import { CopyServiceIf } from './service/copy-service.if.js';
+import { MouseTargetData } from './data/event/mouse-target-data.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';
+import { EventSelectionChangedListenerIf } from './selection/event-selection-changed-listener.if.js';
+import { ResizeHandler } from './resize-handler.js';
+import { ExcelServiceIf } from './service/excel-service.if.js';
+import { ColumnDefIf } from './data/tablemodel/column/column-def.if.js';
+import { LiveAnnouncer } from './aria/live-announcer.js';
 
 /**
- * The TableScope class extends the RenderScope class and provides functionality for rendering and interacting with a table.
+ * Creates and runs one table in a host element – the core that every framework wrapper uses.
  *
- * @property {LicenseManager} licenseManager - An instance of LicenseManager.
- * @property {MouseHandler} mouseHandler - An instance of MouseHandler to handle mouse events.
- * @property {InputHandler} inputHandler - An instance of InputHandler to handle keyboard inputs.
- * @property {ShortcutService} shortcutService - An instance of ShortcutService to register and handle shortcuts.
- * @property {StoreStateCollapsedExpandService | undefined} storeStateCollapsedExpandService - A service to manage and restore the collapsed or expanded state of the table's rows.
- * @property {StoreStateSortingService | undefined} storeSortingService - A service to manage and restore the sort state of the table's columns.
- * @property {SelectionService} selectionService - An instance of SelectionService to manage cell selection in the table.
- * @property {GeKeyEvent | undefined} keyEvent - An object representing the last processed keyboard event.
- * @property {TableApi} api - An instance of TableApi, providing an API for table interactions.
+ * It connects the four building blocks: host element, {@link TableModelIf table model}, {@link TableOptionsIf options}
+ * and an {@link EventListenerIf event listener}, renders only the visible cells (virtual scrolling in both
+ * directions) and handles mouse, keyboard, selection, sorting and editing. Talk to the table through
+ * {@link getApi} – the {@link TableApi}.
  *
- * Additional properties related to the dragging state of the table:
- * - mouseStartAction: The action performed at the start of a mouse drag operation.
- * - mouseStartWidth: The initial width of an element at the start of a resizing drag operation.
- * - mouseStartColumnIndex: The index of the column at the start of a resizing drag operation.
- * - dragFrom: The initial cell index of a drag operation.
- * - dragTo: The current cell index of a drag operation.
- * - lastDragFrom: The previous initial cell index of a drag operation.
- * - lastDragTo: The previous current cell index of a drag operation.
- * - firstDraggingRendering: A boolean indicating if this is the first render during the current drag operation.
+ * The host element needs a height: the table fills it.
  *
- * Methods: Please refer to the documentation of the superclass RenderScope for the inherited methods.
- * The TableScope class introduces additional methods not listed here. Please refer to the source code for further details.
+ * @example
+ * import "@guiexpert/table/css/main.css";
+ * import { EventAdapter, SimpleDomService, TableFactory, TableOptions, TableScope } from "@guiexpert/table";
+ *
+ * const host = document.querySelector<HTMLDivElement>(".table-div")!;   // CSS: .table-div { height: 500px }
+ * const tableModel = TableFactory.createTableModel({ rows: orders });
+ * const tableScope = new TableScope(host, tableModel, new SimpleDomService(), new TableOptions(), new EventAdapter());
+ * tableScope.firstInit();
+ * const tableApi = tableScope.getApi();
+ *
+ * // later: remove the table (route change, new model)
+ * tableScope.destroy();
+ *
+ * @see Training: [Your first table in plain TypeScript](https://gui.expert/training/first-table/)
+ *
+ * @category Table & API
  */
 export declare class TableScope extends RenderScope implements OnActionTriggeredIf, EventFocusChangedListenerIf, EventSelectionChangedListenerIf {
     protected readonly eventListener: EventListenerIf;
@@ -73,6 +77,16 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     protected selectionService: SelectionService;
     protected keyEvent?: GeKeyEvent;
     private api;
+    /**
+     * The live region of this table: screen readers speak its messages (sorting, filter, copy …).
+     * Use {@link TableApi.announce} for own messages.
+     * @since 1.1.91
+     */
+    readonly liveAnnouncer: LiveAnnouncer;
+    /** Delay of the "42 rows" announcement after a filter change (typing in a filter field: one announcement). */
+    static filterAnnouncementDelayInMs: number;
+    /** firstInit() has finished: announcements are made from now on (not for the initial filter). */
+    private initialized;
     private mouseStartAction;
     private mouseStartWidth;
     private mouseStartColumnIndex;
@@ -84,6 +98,13 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     /** Last comparator passed to `sort()`; re-applied after filtering. Cleared by a header sort. */
     private lastSortCompareFn?;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, domService: DomServiceIf, tableOptions: TableOptionsIf, eventListener: EventListenerIf, copyService?: CopyServiceIf, excelService?: ExcelServiceIf);
+    /** Time of the last Tab key press on the page (the host is focused right after it). */
+    private lastTabKeyTime;
+    /**
+     * The host got the keyboard focus (Tab): without a focus cell the first shown cell of the first visible row
+     * gets the focus, so screen readers announce a cell (`aria-activedescendant`).
+     */
+    private onHostKeyboardFocus;
     /**
      * Creates a TableScope instance.
      *
@@ -106,6 +127,51 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {boolean} - Returns true if the action was triggered successfully, false otherwise.
      */
     onActionTriggered(actionId: ActionId): boolean;
+    /**
+     * Speaks a message to screen reader users (polite live region, see {@link LiveAnnouncer}).
+     *
+     * @param {string} text - plain text, e.g. "Orders loaded"
+     * @param {number} [delayInMs] - wait before the text is written (default {@link LiveAnnouncer.defaultDelayInMs})
+     * @since 1.1.91
+     */
+    announce(text: string, delayInMs?: number): 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). */
+    private countCopiedCells;
+    /**
+     * The header cell with the keyboard focus (arrow up in the first body row moves the focus into the header).
+     *
+     * @returns {[number, number] | undefined} header row and column index of the cell, `undefined` if the focus is in the body
+     * @since 1.1.91
+     */
+    getHeaderFocus(): [number, number] | undefined;
+    /** Moves the body focus to a cell, scrolls it into view and repaints (also leaves the header). */
+    private setFocusCell;
+    private getFirstShownColumnIndex;
+    private getLastShownColumnIndex;
+    /** Home, End, Ctrl+Home, Ctrl+End, Page Up/Down and Enter in the body; `undefined` = not such an action. */
+    private onBodyNavigation;
+    /** Enter on a body cell: toggles its row checkbox, otherwise expands/collapses its tree row. */
+    private activateBodyCell;
+    /** Arrow up in the first body row: the focus moves to the lowest header row (same column). */
+    private moveFocusIntoHeader;
+    /** Focuses a header cell – the origin of a span cell that covers (row, column) – and repaints. */
+    private setHeaderFocus;
+    /**
+     * Keys while a header cell has the focus. Returns `undefined` for actions that work as in the body (copy,
+     * select all …) – they leave the header focus as it is.
+     */
+    private onHeaderAction;
+    /** Enter on a header cell: a group with a toggle opens/closes, a sortable (lowest) header cell sorts. */
+    private activateHeaderCell;
+    /**
+     * Closes the cell editor without changing the model (Escape in the editor).
+     *
+     * @param {HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement} [editor] - the editor element: its value is reset
+     *        first, so the blur caused by closing does not commit the typed text ("change" event)
+     */
+    cancelEditing(editor?: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
     updateModelValueAfterEdit(areaIdent: AreaIdent, rowIndex: number, columnIndex: number, value: string): void;
     /**
      * Retrieves the TableApi object.
@@ -150,6 +216,15 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {GeMouseEvent} - The created GeMouseEvent object.
      */
     createGeMouseEvent(mouseEvent: MouseEvent): GeMouseEvent;
+    /**
+     * The element a mouse event belongs to – usually `evt.target`. The scroll viewport lies above the footer areas (its
+     * horizontal scroll bar must stay usable), so a mouse event on a footer cell arrives at the viewport: then the footer
+     * element below the mouse pointer is returned (not on the scroll bar itself).
+     *
+     * @param {MouseEvent} evt - a mouse event on the host element
+     * @returns {EventTarget | null} the target element
+     */
+    getMouseEventTarget(evt: MouseEvent): EventTarget | null;
     /**
      * Handles the mouse down event.
      *
@@ -195,6 +270,18 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {void}
      */
     toggleExpandCollapseAll(expand?: boolean): void;
+    /** The last "expand / collapse all" state – the header icon toggles it. */
+    allExpanded: boolean;
+    /**
+     * Expands or collapses one row of a tree table, repaints, and remembers the state (`autoRestoreOptions`).
+     *
+     * @param {TreeRowIf<any>} row - a tree row of the body model
+     * @param {boolean} expanded - the new state
+     * @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.
      *
@@ -214,9 +301,24 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      */
     onMouseClicked(evt: GeMouseEvent, previousEvt: GeMouseEvent | undefined): boolean;
     debounceRepaint(): void;
+    /**
+     * Cancels a repaint scheduled by {@link debounceRepaint}.
+     *
+     * @returns true if a repaint was pending
+     */
+    cancelPendingRepaint(): boolean;
     publishGeMouseEvent(evt: GeMouseEvent): void;
     onFocusChanged(sm: FocusModelIf): void;
     onSelectionChanged(sm: SelectionModelIf): void;
+    private selectionEventsHeld;
+    private heldSelectionModel?;
+    /**
+     * Runs `fn` and reports all selection changes made in it as ONE `onSelectionChanged` event (a click used to fire
+     * up to three: `clear()`, adding the new range and the selection service itself).
+     *
+     * @param {() => void} fn - code that changes the selection model
+     */
+    holdSelectionEvents(fn: () => void): void;
     /**
      * Updates the table (repaint) when an external filter is changed.
      *
@@ -254,13 +356,26 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      */
     scrollToPixel(px: number, py: number): void;
     /**
-     * Scrolls to the specified index in the table.
+     * Scrolls to a column and a row: the row becomes the first row of the viewport, the column the first column of the
+     * scrollable center area (as far as the scroll range allows).
      *
-     * @param {number} _indexX - The horizontal index of the table where scrolling is needed.
-     * @param {number} indexY - The vertical index of the table where scrolling is needed.
+     * A fixed west column scrolls back to the start (x = 0, like before columns were supported). A fixed east column,
+     * `-1` or any other index outside the column range keeps the current horizontal position.
+     *
+     * @param {number} indexX - The column index (model index over west + center + east), `-1` = keep the horizontal position.
+     * @param {number} indexY - The row index of the body.
      * @return {void}
      */
-    scrollToIndex(_indexX: number, indexY: number): void;
+    scrollToIndex(indexX: number, indexY: number): void;
+    /**
+     * The horizontal scroll position (`scrollLeft` of the scroll viewport) that shows a column as the first column of
+     * the scrollable center area, clamped to the scroll range.
+     * A fixed west column returns 0 (start); fixed east columns and indices outside the columns return the current position.
+     *
+     * @param {number} columnIndex - model column index (west + center + east)
+     * @returns {number} scrollLeft in scroll bar pixels
+     */
+    protected getScrollLeftForColumnIndex(columnIndex: number): number;
     adjustAfterScrolling(): void;
     /**
      * Sets the selection model for the table.
@@ -285,13 +400,20 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     focusModel(): FocusModelIf | undefined;
     setDragging(dragging: boolean): void;
     /**
-     * Changes the focus cell using the specified deltas.
+     * Changes the focus cell using the specified deltas (keyboard navigation).
+     * The new focus stays inside the body (first/last row and column) and the focused row is scrolled into view.
+     * `onFocusChanged` is fired by the focus model itself (TableScope listens to it).
      *
      * @param {number} dx - The delta for the column index.
      * @param {number} dy - The delta for the row index.
-     * @return {boolean} - True if the focus cell was changed, false otherwise.
+     * @return {boolean} - True if the key was handled (a focus model exists and the table is not editing), false otherwise.
      */
     private changeFocusCell;
+    /**
+     * The column index `dx` steps from `colIdx`, skipping hidden columns (width 0, e.g. `setColumnVisible(…, false)`).
+     * Stays inside the columns; if there is no shown column in that direction, the focus stays where it is.
+     */
+    private getNextShownColumnIndex;
     /**
      * Resizes the column based on the mouse event.
      *
@@ -304,7 +426,6 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {void}
      */
     private clearSelectionModel;
-    private debugOnce;
     /**
      * Restores the scroll position of the table if auto restore options are enabled.
      *
@@ -346,6 +467,27 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      */
     calcAutoColumnWidths(): number[];
     setColumnWidth(columnIndex: number, width: number): void;
+    /**
+     * Shows or hides a column and repaints (see {@link TableApi.setColumnVisible}).
+     *
+     * @param {number | string | ColumnDefIf} column - column index, property or column definition
+     * @param {boolean} visible - false hides the column
+     * @returns {boolean} false if the column has no column definition (or the table model can't hide columns)
+     */
+    setColumnVisible(column: number | string | ColumnDefIf, visible: boolean): boolean;
+    /**
+     * Shows or hides the header and repaints (see {@link TableApi.setHeaderVisible}).
+     *
+     * @param {boolean} visible - false hides the header
+     */
+    setHeaderVisible(visible: boolean): void;
+    /**
+     * Shows or hides the footer and repaints (see {@link TableApi.setFooterVisible}).
+     *
+     * @param {boolean} visible - false hides the footer
+     */
+    setFooterVisible(visible: boolean): void;
+    private setAreaVisible;
     autoResizeColumns(recalcWrappers?: boolean): void;
     recalcWrappers(): void;
     reSort(): void;
@@ -363,7 +505,7 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * The method performs the following:
      * 1. Checks if the row is above the current viewport (before first visible row)
      * 2. Checks if the row is below the current viewport (after last visible row)
-     * 3. Scrolls to make the row visible if needed
+     * 3. Scrolls to make the row visible if needed – vertically only, the horizontal position is kept
      *
      * @param {number} rowIndex - The index of the row to make visible
      * @returns {boolean} Returns true if scrolling was needed and performed, false if the row was already visible
@@ -372,39 +514,24 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * // Ensure row 5 is visible in the viewport
      * tableScope.ensureRowIsVisible(5);
      *
-     * @example
-     * // Example usage in a component
-     * class MyTableComponent {
-     *   private tableScope: TableScope;
-     *
-     *   scrollToSpecificRow(rowIndex: number) {
-     *     // This will scroll the row into view if it's not visible
-     *     const didScroll = this.tableScope.ensureRowIsVisible(rowIndex);
-     *
-     *     if (didScroll) {
-     *       console.log(`Table scrolled to show row ${rowIndex}`);
-     *     } else {
-     *       console.log(`Row ${rowIndex} was already visible`);
-     *     }
-     *   }
-     * }
-     *
-     * @example
-     * // Example with row selection
-     * class TableHandler {
-     *   selectAndShowRow(rowIndex: number) {
-     *     // First ensure the row is visible
-     *     this.tableScope.ensureRowIsVisible(rowIndex);
-     *
-     *     // Then perform selection
-     *     this.selectionModel.selectRow(rowIndex);
-     *   }
-     * }
-     *
      * @throws {Error} Implicitly may throw if rowIndex is not a number or if required properties are undefined
      *
      * @see {@link scrollToIndex} - The underlying method used for scrolling
      * @see {@link getDisplayedRowCount} - Related method for getting visible row count
      */
     ensureRowIsVisible(rowIndex: number): boolean;
+    /**
+     * Ensures that a column of the scrollable center area is fully visible by scrolling horizontally if necessary –
+     * the counterpart of {@link ensureRowIsVisible}. A column left of the viewport becomes the first visible column,
+     * a column right of it the last one (a column wider than the viewport: the first). The vertical position is kept.
+     *
+     * Fixed west/east columns are always visible: nothing to do.
+     *
+     * @param {number} columnIndex - model column index (west + center + east)
+     * @returns {boolean} true if the table was scrolled, false if the column was already visible (or is fixed / hidden / out of range)
+     *
+     * @example
+     * tableScope.ensureColumnIsVisible(12);
+     */
+    ensureColumnIsVisible(columnIndex: number): boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.90",
+  "version": "1.1.91",
   "license": "MIT",
   "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
   "repository": {
@@ -23,7 +23,10 @@
   },
   "exports": {
     ".": {
-      "import": "./index.js",
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
       "require": "./index.cjs"
     },
     "./css/*": "./css/*",
@@ -34,7 +37,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.11.17",
-    "vite": "6.3.4",
+    "vite": "6.4.4",
     "vite-plugin-dts": "^3.7.2",
     "vite-plugin-eslint": "^1.8.1",
     "vite-plugin-static-copy": "^0.17.0",
@@ -46,7 +49,12 @@
     "typedoc-plugin-rename-defaults": "^0.7.0",
     "typedoc-plugin-markdown": "3.17.1",
     "typescript": "5.2.2",
-    "@babel/core": "~7.28.6"
+    "@babel/core": "~7.28.6",
+    "vitest": "5.0.4",
+    "@vitest/browser-playwright": "5.0.4",
+    "@vitest/coverage-v8": "5.0.4",
+    "axe-core": "4.10.3",
+    "playwright": "1.64.0"
   },
   "scripts": {
     "i": "pnpm i",
@@ -54,10 +62,17 @@
     "build": "vite build && npm run concat-css:main && npm run concat-css:dist",
     "concat-css:main": "cat css/table*.css > css/main.css",
     "concat-css:dist": "cat css/table*.css > dist/css/main.css",
-    "typedoc:json": "npx typedoc --json ../../apps/table-website/src/assets/json/doctype.json src/index.ts",
-    "typedoc:docs-html": "npx typedoc --out ../../apps/table-website/src/assets/docs src/index.ts",
-    "typedoc:docs-html-custom-css": "npx typedoc --customCss ./doc.css --out ../../apps/table-website/src/assets/docs src/index.ts",
-    "typedoc:docs-md": "npx typedoc --plugin typedoc-plugin-markdown --out ../../apps/table-website/src/assets/docsmd src/index.ts",
+    "typedoc:website": "node scripts/typedoc-website.mjs",
+    "typedoc:json": "npx typedoc --json ../../apps/table-website/src/assets/json/doctype.json",
+    "typedoc:docs-html": "npx typedoc --out ../../apps/table-website/src/assets/docs",
+    "typedoc:docs-md": "npx typedoc --plugin typedoc-plugin-markdown --out ../../apps/table-website/src/assets/docsmd",
+    "docs:check": "node scripts/check-doc-examples.mjs",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:browser": "vitest run --project browser",
+    "test:watch": "vitest --project unit",
+    "test:coverage": "vitest run --coverage",
+    "test:types": "tsc -p tsconfig.spec.json --noEmit",
     "npm-pub": "pnpm publish --no-git-checks --access public"
   }
 }