@guiexpert/table 1.1.90 → 1.1.92

package/lib/table/renderer/edit/select-cell-renderer.d.ts

@@ -1,10 +1,11 @@
-import { CellRendererIf } from '../cell-render.if';
-import { AreaIdent } from '../../data/tablemodel/area-ident.type';
-import { AreaModelIf } from '../../data/tablemodel/areamodel/area-model.if';
-import { DomServiceIf } from '../../service/dom-service.if';
-import { RendererCleanupFnType } from '../renderer-cleanup-fn.type';
-import { ValueLabelIf } from '../../data/common/value-label.if';
+import { CellRendererIf } from '../cell-render.if.js';
+import { AreaIdent } from '../../data/tablemodel/area-ident.type.js';
+import { AreaModelIf } from '../../data/tablemodel/areamodel/area-model.if.js';
+import { DomServiceIf } from '../../service/dom-service.if.js';
+import { RendererCleanupFnType } from '../renderer-cleanup-fn.type.js';
+import { ValueLabelIf } from '../../data/common/value-label.if.js';
 
+/** @category Renderers & editing */
 export declare class SelectCellRenderer implements CellRendererIf {
     protected options: ValueLabelIf[];
     constructor(options: ValueLabelIf[]);

package/lib/table/renderer/male-female-to-icon-cell-renderer.d.ts

@@ -1,9 +1,22 @@
-import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if';
-import { CellRendererIf } from './cell-render.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
+import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if.js';
+import { CellRendererIf } from './cell-render.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
 
+/** @category Renderers & editing */
 export declare class MaleFemaleToIconCellRenderer implements CellRendererIf {
-    render(cellDiv: HTMLDivElement, _rowIndex: number, _columnIndex: number, _areaIdent: AreaIdent, _areaModel: AreaModelIf, cellValue: any, _domService: DomServiceIf): RendererCleanupFnType | undefined;
+    ariaLabels: {
+        male: string;
+        female: string;
+    };
+    /**
+     * @param ariaLabels - texts for screen readers (the symbols ♂ / ♀ are images). Default: "male" / "female". @since 1.1.91
+     */
+    constructor(ariaLabels?: {
+        male: string;
+        female: string;
+    });
+    render(cellDiv: HTMLDivElement, _rowIndex: number, _columnIndex: number, _areaIdent: AreaIdent, _areaModel: AreaModelIf, cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
+    private addSymbol;
 }

package/lib/table/renderer/number-cell-progress-bar-cell-renderer.d.ts

@@ -1,12 +1,17 @@
-import { CellRendererIf } from './cell-render.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
-import { AreaModelObjectArray } from '../data/tablemodel/areamodel/area-model-object-array';
+import { CellRendererIf } from './cell-render.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
+import { AreaModelObjectArray } from '../data/tablemodel/areamodel/area-model-object-array.js';
 
+/** @category Renderers & editing */
 export declare class NumberCellProgressBarCellRenderer<T> implements CellRendererIf {
     maxValue: number;
     labelVisible: boolean;
-    constructor(maxValue?: number, labelVisible?: boolean);
+    /** Text for screen readers (the bar is an image). Default: `"75 %"`. @since 1.1.91 */
+    ariaLabel: (percent: number, value: number) => string;
+    constructor(maxValue?: number, labelVisible?: boolean, 
+    /** Text for screen readers (the bar is an image). Default: `"75 %"`. @since 1.1.91 */
+    ariaLabel?: (percent: number, value: number) => string);
     render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, _areaModel: AreaModelObjectArray<T>, cellValue: number, domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

package/lib/table/renderer/number-cell-renderer.d.ts

@@ -1,9 +1,10 @@
-import { CellRendererIf } from './cell-render.if';
-import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
+import { CellRendererIf } from './cell-render.if.js';
+import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
 
+/** @category Renderers & editing */
 export declare class NumberCellRenderer implements CellRendererIf {
     protected min: number;
     protected max: number;

package/lib/table/renderer/positive-and-negative-number-renderer.d.ts

@@ -1,9 +1,10 @@
-import { CellRendererIf } from './cell-render.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
+import { CellRendererIf } from './cell-render.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
 
+/** @category Renderers & editing */
 export declare class PositiveAndNegativeNumberRenderer implements CellRendererIf {
     render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, _areaModel: AreaModelIf, cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

package/lib/table/renderer/progress-bar-cell-renderer.d.ts

@@ -1,16 +1,22 @@
-import { CellRendererIf } from './cell-render.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
-import { AreaModelObjectArray } from '../data/tablemodel/areamodel/area-model-object-array';
+import { CellRendererIf } from './cell-render.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
+import { AreaModelObjectArray } from '../data/tablemodel/areamodel/area-model-object-array.js';
 
 /**
  * Works with AreaModelObjectArray only
+ *
+ * @category Renderers & editing
  */
 export declare class ProgressBarCellRenderer<T> implements CellRendererIf {
     property: string;
     maxValue: number;
     labelVisible: boolean;
-    constructor(property: string, maxValue?: number, labelVisible?: boolean);
+    /** Text for screen readers (the bar is an image). Default: `"75 %"`. @since 1.1.91 */
+    ariaLabel: (percent: number, value: number) => string;
+    constructor(property: string, maxValue?: number, labelVisible?: boolean, 
+    /** Text for screen readers (the bar is an image). Default: `"75 %"`. @since 1.1.91 */
+    ariaLabel?: (percent: number, value: number) => string);
     render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, areaModel: AreaModelObjectArray<T>, _cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

package/lib/table/renderer/renderer-cleanup-fn.type.d.ts

@@ -1 +1,2 @@
+/** @category Renderers & editing */
 export type RendererCleanupFnType = Function;

package/lib/table/renderer/renderer.d.ts

@@ -1,6 +1,7 @@
-import { CellRendererIf } from './cell-render.if';
-import { AreaObjectMap } from '../data/common/area-map';
+import { CellRendererIf } from './cell-render.if.js';
+import { AreaObjectMap } from '../data/common/area-map.js';
 
+/** @category Renderers & editing */
 export declare class Renderer {
     static bodyRenderer(bodyCellRenderer: CellRendererIf): AreaObjectMap<CellRendererIf>;
 }

package/lib/table/renderer/simple-array-cell-renderer.d.ts

@@ -1,9 +1,10 @@
-import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if';
-import { CellRendererIf } from './cell-render.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
+import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if.js';
+import { CellRendererIf } from './cell-render.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
 
+/** @category Renderers & editing */
 export declare class SimpleArrayCellRenderer implements CellRendererIf {
     render(cellDiv: HTMLDivElement, _rowIndex: number, _columnIndex: number, _areaIdent: AreaIdent, _areaModel: AreaModelIf, cellValue: any[], domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

package/lib/table/renderer/star-rating-cell-renderer.d.ts

@@ -1,14 +1,20 @@
-import { CellRendererIf } from './cell-render.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
-import { AreaModelObjectArray } from '../data/tablemodel/areamodel/area-model-object-array';
+import { CellRendererIf } from './cell-render.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
+import { AreaModelObjectArray } from '../data/tablemodel/areamodel/area-model-object-array.js';
 
 /**
  * Works with AreaModelObjectArray only
+ *
+ * @category Renderers & editing
  */
 export declare class StarRatingCellRenderer<T> implements CellRendererIf {
     property: string;
-    constructor(property: string);
+    /** Text for screen readers (the stars are an image). Default: `"4 stars"`. @since 1.1.91 */
+    ariaLabel: (stars: number) => string;
+    constructor(property: string, 
+    /** Text for screen readers (the stars are an image). Default: `"4 stars"`. @since 1.1.91 */
+    ariaLabel?: (stars: number) => string);
     render(cellDiv: HTMLDivElement, rowIndex: number, columnIndex: number, areaIdent: AreaIdent, areaModel: AreaModelObjectArray<T>, _cellValue: any, domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

package/lib/table/renderer/true-false-cell-renderer.d.ts

@@ -1,9 +1,21 @@
-import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if';
-import { CellRendererIf } from './cell-render.if';
-import { DomServiceIf } from '../service/dom-service.if';
-import { AreaIdent } from '../data/tablemodel/area-ident.type';
-import { RendererCleanupFnType } from './renderer-cleanup-fn.type';
+import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if.js';
+import { CellRendererIf } from './cell-render.if.js';
+import { DomServiceIf } from '../service/dom-service.if.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { RendererCleanupFnType } from './renderer-cleanup-fn.type.js';
 
+/** @category Renderers & editing */
 export declare class TrueFalseCellRenderer implements CellRendererIf {
+    ariaLabels: {
+        true: string;
+        false: string;
+    };
+    /**
+     * @param ariaLabels - texts for screen readers (the icons ✅ / ❌ are images). Default: "Yes" / "No". @since 1.1.91
+     */
+    constructor(ariaLabels?: {
+        true: string;
+        false: string;
+    });
     render(cellDiv: HTMLDivElement, _rowIndex: number, _columnIndex: number, _areaIdent: AreaIdent, _areaModel: AreaModelIf, cellValue: any, _domService: DomServiceIf): RendererCleanupFnType | undefined;
 }

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

@@ -1,9 +1,11 @@
-import { TableScope } from './table-scope';
+import { TableScope } from './table-scope.js';
 
 /**
  * Class representing a ResizeHandler.
  * @class
  * @classdesc Handles resizing of elements and calls a callback function on resize. These calls will be debounced with 500 ms.
+ *
+ * @category Internals
  */
 export declare class ResizeHandler {
     protected tableScope: TableScope;

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

@@ -1,5 +1,6 @@
-import { SelectionModelIf } from './selection-model.if';
+import { SelectionModelIf } from './selection-model.if.js';
 
+/** @category Events */
 export interface EventSelectionChangedListenerIf {
     onSelectionChanged(model: SelectionModelIf): void;
 }

package/lib/table/selection/multi-rows-selection-model.d.ts

@@ -1,18 +1,21 @@
-import { SelectionModel } from './selection-model';
-import { ObjectArrayHolderIf } from '../data/tablemodel/areamodel/object-array-holder.if';
+import { SelectionModel } from './selection-model.js';
+import { ObjectArrayHolderIf } from '../data/tablemodel/areamodel/object-array-holder.if.js';
 
 /**
  * Class representing a multi-row selection model.
  * @extends SelectionModel
+ *
+ * @category Selection & focus
  */
 export declare class MultiRowsSelectionModel<T> extends SelectionModel {
     model: ObjectArrayHolderIf<T>;
     constructor(model: ObjectArrayHolderIf<T>);
     /**
      * Retrieves the selected rows from an array of all table rows.
+     * The selection holds row indices of the displayed rows – pass the displayed (filtered, sorted) rows.
      *
      * @param {T[]} allrows - The array of all rows from the table model.
-     * @returns {T[]} - The selected rows from the given array.
+     * @returns {T[]} - The selected rows from the given array (the array itself if everything is selected).
      */
     getSelectedRowItems(allrows: T[]): T[];
     /**
@@ -42,7 +45,7 @@ export declare class MultiRowsSelectionModel<T> extends SelectionModel {
      */
     toggleFilteredRowsSelection(): void;
     /**
-     * Toggles the selection state of a row.
+     * Toggles the selection state of a row. A row that was toggled off can be toggled on again.
      *
      * @param {number} rowIndex - The index of the row to toggle.
      *

package/lib/table/selection/selection-model.d.ts

@@ -1,8 +1,18 @@
-import { CellRange } from '../data/common/cell-range';
-import { ExtendedSelectionType, SelectionMode } from './selection.type';
-import { SelectionModelIf } from './selection-model.if';
-import { EventSelectionChangedListenerIf } from './event-selection-changed-listener.if';
+import { CellRange } from '../data/common/cell-range.js';
+import { ExtendedSelectionType, SelectionMode } from './selection.type.js';
+import { SelectionModelIf } from './selection-model.if.js';
+import { EventSelectionChangedListenerIf } from './event-selection-changed-listener.if.js';
 
+/**
+ * Saved state of a {@link SelectionModel} – see {@link SelectionModel.createSnapshot}.
+ *
+ * @category Selection & focus
+ */
+export interface SelectionSnapshot {
+    ranges: CellRange[];
+    negativeRanges: CellRange[];
+    allSelected: boolean;
+}
 /**
  * `SelectionModel` is a class that manages the various modes and types of selections within a grid.
  * It supports basic modes like single cell, row, column, and range selections, as well as advanced mode like negative ranges.
@@ -30,14 +40,16 @@ import { EventSelectionChangedListenerIf } from './event-selection-changed-liste
  * @method clear(): void - Clears all selections in all ranges and resets allSelected and negativeRanges arrays.
  * @method hasSelection(): boolean - Checks whether there is any selection. Returns true if yes, false if no.
  * @method hasNoSelection(): boolean - Checks whether there is no selection. Returns true if yes, false if no.
- * @method getMergedRowIndices(): number[] - Gets the array of merged row indices.
- * @method selectAll(): void - Selects all selectable entities.
+ * @method getMergedRowIndices(rowCount?: number): number[] - Gets the sorted indices of all rows with at least one selected cell.
+ * @method selectAll(): void - Selects all selectable entities (also cells that were deselected before). No-op for type "none".
  * @method isAllSelected() - Checks if all selectable entities are selected.
- * @method addSelection(range: CellRange): void - Adds a certain range to the selection.
+ * @method addSelection(range: CellRange): void - Adds a certain range to the selection (selects removed cells again).
  * @method removeSelection(range: CellRange): void - Removes a certain range from the selection.
  * @method togglePoint(row: number, col: number): void - Toggles the selection state of a point at the specified row and column in a grid.
  * @method isSelected(row: number, col: number): boolean - Checks if a specific cell in a grid is selected.
  * @method addRange(range: CellRange): void - Adds a range of cells to the selection.
+ *
+ * @category Selection & focus
  */
 export declare class SelectionModel implements SelectionModelIf {
     selectionType: ExtendedSelectionType;
@@ -52,7 +64,26 @@ export declare class SelectionModel implements SelectionModelIf {
     addEventSelectionChangedListener(listener: EventSelectionChangedListenerIf): void;
     removeEventSelectionChangedListener(listener: EventSelectionChangedListenerIf): void;
     fireChangeEvent(): void;
+    /**
+     * A plain click: selects the clicked row (`"row"`), column (`"column"`) or cell (`"cell"`, `"range"`).
+     *
+     * @param {number} rowIndex - row index of the clicked cell
+     * @param {number} columnIndex - column index of the clicked cell
+     */
     firstClick(rowIndex: number, columnIndex: number): void;
+    /**
+     * A copy of the current selection state, e.g. to restore it while a drag rectangle changes
+     * (see {@link restoreSnapshot}). The ranges themselves are shared – they are never changed after being added.
+     *
+     * @returns {SelectionSnapshot} the state
+     */
+    createSnapshot(): SelectionSnapshot;
+    /**
+     * Restores a state created by {@link createSnapshot} (fires a change event).
+     *
+     * @param {SelectionSnapshot} snapshot - the state to restore
+     */
+    restoreSnapshot(snapshot: SelectionSnapshot): void;
     getSelectionCount(rowIndex: number, columnIndex: number): number;
     isInNegativeRange(rowIndex: number, columnIndex: number): boolean;
     getRanges(): CellRange[];
@@ -60,16 +91,87 @@ export declare class SelectionModel implements SelectionModelIf {
     hasSelection(): boolean;
     hasNoSelection(): boolean;
     /**
-     * Retrieves the merged row indices from the given range selection.
+     * The indices of all rows that contain at least one selected cell, sorted ascending and without duplicates.
+     * A row whose selected cells were all removed again ({@link removeSelection}) is left out.
      *
-     * @returns {number[]} Array of merged row indices
+     * Ranges that cover all rows (selection type `"column"`, {@link CellRange.singleColumn}: `r2 = Number.MAX_SAFE_INTEGER`)
+     * and {@link selectAll} can only be resolved with `rowCount`. Without it they are skipped (before, such a range
+     * made this method loop forever) – pass the number of (displayed) body rows to get them, too.
+     *
+     * @param {number} [rowCount] - number of body rows; rows `>= rowCount` are left out, and "all rows"
+     *   (column ranges, {@link selectAll}) becomes `0 … rowCount - 1`
+     * @returns {number[]} row indices, sorted ascending
+     *
+     * @example
+     * const rowCount = tableModel.getBodyModel().getRowCount();
+     * const rowIndices = selectionModel.getMergedRowIndices(rowCount);   // e.g. [1, 2, 5]
+     * console.log(`${rowIndices.length} rows with selected cells`);
+     */
+    getMergedRowIndices(rowCount?: number): number[];
+    /**
+     * Selects all cells. Cells that were deselected before ({@link removeSelection}) are selected again;
+     * removing cells afterwards cuts holes into "all selected".
      */
-    getMergedRowIndices(): number[];
     selectAll(): void;
     isAllSelected(): boolean;
+    /**
+     * Adds a rectangle to the selection (adjusted to the selection type: whole rows for `"row"`, whole columns for
+     * `"column"`, the first cell for `"cell"`). Cells of the rectangle that were deselected before
+     * ({@link removeSelection}) are selected again – the last operation wins.
+     *
+     * @param {CellRange} range - the cells to select (adjusted in place to the selection type)
+     */
     addSelection(range: CellRange): void;
+    /**
+     * Deselects a rectangle (stored as a "negative" range, so it also cuts holes into {@link selectAll}).
+     * For selection type `"row"` all rows `r1 … r2` are removed, for `"column"` all columns `c1 … c2`.
+     * A following {@link addSelection} / {@link togglePoint} of these cells selects them again.
+     *
+     * @param {CellRange} range - the cells to deselect
+     */
     removeSelection(range: CellRange): void;
+    /**
+     * Toggles the selection state of a cell (for selection type `"row"`/`"column"`: of its row/column).
+     * A cell that was deselected inside a selected range (or after {@link selectAll}) gets selected again
+     * without adding a second, overlapping range.
+     *
+     * @param {number} row - row index
+     * @param {number} col - column index
+     */
     togglePoint(row: number, col: number): void;
     isSelected(row: number, col: number): boolean;
     protected addRange(range: CellRange): void;
+    /**
+     * Adjusts a range (in place) to the selection type: whole rows for `"row"`, whole columns for `"column"`,
+     * the first cell for `"cell"`; `"range"` and `"none"` keep it as it is.
+     *
+     * @param {CellRange} range - the range to adjust
+     * @returns {CellRange} the same range object
+     */
+    protected adjustRangeToSelectionType(range: CellRange): CellRange;
+    /**
+     * Selects a deselected cell again ("toggle on") by lifting the negative ranges at this cell (for selection type
+     * `"row"`/`"column"`: at its whole row/column) – only possible while the cell is still inside a selected range
+     * or everything is selected. Fires no event.
+     *
+     * @param {number} row - row index
+     * @param {number} col - column index
+     * @returns {boolean} true if the cell is selected again, false if it has to be added as a new range
+     */
+    protected reselectPoint(row: number, col: number): boolean;
+    /**
+     * Removes the cells of `range` from all negative ranges ("last operation wins": cells added after they were
+     * removed are selected again). A negative range that overlaps `range` is split into up to four rectangles
+     * (above, below, left and right of the overlap); unbounded ranges (`Number.MAX_SAFE_INTEGER`) work as well.
+     *
+     * @param {CellRange} range - the cells that are selected again
+     */
+    protected liftNegativeRanges(range: CellRange): void;
+    /** True if every cell of `range` is inside one of the negative ranges (rectangle difference, works unbounded). */
+    private isCoveredByNegativeRanges;
+    /** `a` minus `b`: up to four rectangles (above, below, left and right of the overlap). */
+    private static difference;
+    private static intersects;
+    /** Are the columns c1 … c2 of this row completely covered by the given (negative) ranges? */
+    private static coversColumns;
 }

package/lib/table/selection/selection-model.if.d.ts

@@ -1,9 +1,30 @@
-import { CellRange } from '../data/common/cell-range';
-import { EventSelectionChangedListenerIf } from './event-selection-changed-listener.if';
+import { CellRange } from '../data/common/cell-range.js';
+import { EventSelectionChangedListenerIf } from './event-selection-changed-listener.if.js';
 
+/**
+ * What is selected in a table – a list of rectangles ({@link CellRange}). The implementation is {@link SelectionModel};
+ * every table gets its own, or you pass one via {@link TableOptionsIf.getSelectionModel}.
+ * Changes are reported to {@link EventListenerIf.onSelectionChanged}.
+ *
+ * @example
+ * override onSelectionChanged(model: SelectionModelIf): void {
+ *   // rows with at least one selected cell – also for "row"/"column" selections (their ranges are unbounded:
+ *   // r2/c2 = Number.MAX_SAFE_INTEGER, so (r2 - r1 + 1) * (c2 - c1 + 1) is no cell count)
+ *   const rowCount = tableModel.getBodyModel().getRowCount();
+ *   const rows = model.getMergedRowIndices(rowCount);
+ *   console.log(model.hasSelection() ? `${rows.length} rows with selected cells` : "nothing selected");
+ * }
+ *
+ * @see Training: [Select cells, rows and ranges – and copy them](https://gui.expert/training/selection-and-copy/)
+ *
+ * @category Selection & focus
+ */
 export interface SelectionModelIf {
+    /** The registered listeners (the table registers itself). */
     getEventSelectionChangedListeners(): EventSelectionChangedListenerIf[];
+    /** Get notified on every change of the selection. */
     addEventSelectionChangedListener(listener: EventSelectionChangedListenerIf): void;
+    /** Stop notifications. */
     removeEventSelectionChangedListener(listener: EventSelectionChangedListenerIf): void;
     /**
      * Toggles the selection state of a point at the specified row and column in a grid.
@@ -27,14 +48,38 @@ export interface SelectionModelIf {
      * @return {CellRange[]} Array of CellRange objects representing the ranges.
      */
     getRanges(): CellRange[];
-    getMergedRowIndices(): number[];
+    /**
+     * The indices of all rows that contain at least one selected cell, sorted ascending.
+     *
+     * Ranges that cover all rows (selection type `"column"`) and {@link selectAll} need `rowCount` to be listed;
+     * without it they are skipped. Implementations written before `rowCount` existed may ignore it.
+     *
+     * @param rowCount - number of body rows (optional): limits the result to `0 … rowCount - 1`
+     *
+     * @example
+     * const sm = tableApi.getSelectionModel();
+     * const rowIndices = sm?.getMergedRowIndices(tableModel.getBodyModel().getRowCount()) ?? [];
+     */
+    getMergedRowIndices(rowCount?: number): number[];
+    /** Removes the whole selection. */
     clear(): void;
+    /** Is anything selected? */
     hasSelection(): boolean;
+    /** Is nothing selected? */
     hasNoSelection(): boolean;
+    /**
+     * Adds a rectangle to the selection, e.g. `new CellRange(0, 0, 9, 3)` (rows 0–9, columns 0–3).
+     * Cells removed before ({@link removeSelection}) are selected again – the last operation wins.
+     */
     addSelection(range: CellRange): void;
+    /** Removes a rectangle from the selection (also from "all selected"); a later {@link addSelection} selects it again. */
     removeSelection(range: CellRange): void;
+    /** In how many selected ranges is this cell (0 = not selected)? */
     getSelectionCount(rowIndex: number, columnIndex: number): number;
+    /** Selects all cells (⌘/Ctrl+A) – also those removed from the selection before. */
     selectAll(): void;
+    /** Was everything selected with {@link selectAll}? */
     isAllSelected(): boolean;
+    /** Called by the table on a click: starts a selection at this cell, depending on selection type and mode. */
     firstClick(rowIndex: number, columnIndex: number): void;
 }

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

@@ -1,11 +1,14 @@
-import { GeMouseEvent } from '../data/common/event/ge-mouse-event';
-import { TableScope } from '../table-scope';
-import { GetT } from '../data/common/get-t';
-import { SelectionModelIf } from './selection-model.if';
-import { FocusModelIf } from '../focus/focus-model.if';
-import { OnActionTriggeredIf } from '../action/on-action-triggered.if';
-import { ActionId } from '../action/action-id.type';
+import { GeMouseEvent } from '../data/common/event/ge-mouse-event.js';
+import { TableScope } from '../table-scope.js';
+import { GetT } from '../data/common/get-t.js';
+import { SelectionModelIf } from './selection-model.if.js';
+import { FocusModelIf } from '../focus/focus-model.if.js';
+import { CellRange } from '../data/common/cell-range.js';
+import { OnActionTriggeredIf } from '../action/on-action-triggered.if.js';
+import { ActionId } from '../action/action-id.type.js';
+import { SelectionSnapshot } from './selection-model.js';
 
+/** @category Internals */
 export declare class SelectionService implements OnActionTriggeredIf {
     protected readonly tableScope: TableScope;
     getSelectionModel?: GetT<SelectionModelIf>;
@@ -13,6 +16,10 @@ export declare class SelectionService implements OnActionTriggeredIf {
     protected previousEvt?: GeMouseEvent;
     /** A drag selection ends with a click on another cell – that click must not clear the new range. */
     protected ignoreNextClick: boolean;
+    /** The ranges the anchor click (or the last shift-click) added – the next shift-click replaces them. */
+    protected anchorRanges: CellRange[];
+    /** The selection before a Ctrl/⌘-drag – each drag frame replaces only the dragged rectangle. */
+    protected dragSnapshot?: SelectionSnapshot;
     constructor(tableScope: TableScope);
     /**
      * Called on mouse down: a new gesture starts.
@@ -21,13 +28,34 @@ export declare class SelectionService implements OnActionTriggeredIf {
     /**
      * Selects a range by dragging the mouse over body cells (selection type "range").
      * The cell where the drag started stays the anchor, so a following shift-click extends from there.
+     * With Ctrl/⌘ held at the start the dragged range is added to the existing selection, otherwise it replaces it.
      *
      * @param {GeMouseEvent} evt - the current mouse position
      * @param {GeMouseEvent} startEvt - the mouse down event that started the drag
      * @returns {boolean} true if the selection changed (repaint needed)
      */
     onMouseDragging(evt: GeMouseEvent, startEvt: GeMouseEvent | undefined): boolean;
+    /**
+     * A click on a body cell: moves the focus and changes the selection.
+     * - plain click: new selection (the clicked cell, row or column – by selection type);
+     * - Shift: the rectangle from the previous click (the anchor) to this cell replaces what that click had selected –
+     *   repeated Shift-clicks change the rectangle, ranges added before the anchor stay;
+     * - Ctrl/⌘: toggles the cell (row, column); Ctrl/⌘+Alt: deselects it.
+     *
+     * Header/footer clicks and the second click of a double click (`clickCount` 2) do not change selection or focus.
+     * All changes of one click are reported as one `onSelectionChanged` event.
+     *
+     * @param {GeMouseEvent} evt - the click
+     * @param {GeMouseEvent | undefined} _previousEvt - not used (the service keeps its own anchor)
+     * @returns {boolean} true if focus or selection changed (repaint needed)
+     */
     onMouseClicked(evt: GeMouseEvent, _previousEvt: GeMouseEvent | undefined): boolean;
     onActionTriggered(actionId: ActionId): boolean;
+    /** Speaks a message for screen readers – only if the selection model can select anything. */
+    private announce;
+    /** Runs `fn` so that all selection changes in it reach the table's listener as ONE onSelectionChanged event. */
+    private batch;
+    /** The built-in SelectionModel can save and restore its state; an own SelectionModelIf implementation may not. */
+    private static hasSnapshots;
     private createRangeByEvents;
 }

package/lib/table/selection/selection.type.d.ts

@@ -1,3 +1,6 @@
+/** @category Selection & focus */
 export type ExtendedSelectionType = SelectionType | "range";
+/** @category Selection & focus */
 export type SelectionType = "none" | "cell" | "row" | "column";
+/** @category Selection & focus */
 export type SelectionMode = "single" | "multi";

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

@@ -1,4 +1,4 @@
-import { GetStorageKeyFn } from '../data/options/auto-restore-options.if';
+import { GetStorageKeyFn } from '../data/options/auto-restore-options.if.js';
 
 export declare abstract class AbstractStoreStateService {
     protected getStorageKeyFn?: undefined | GetStorageKeyFn;