@guiexpert/table 1.1.94 → 1.1.96

package/lib/table/data/tablemodel/areamodel/area-model-tree.d.ts

@@ -6,6 +6,10 @@ import { FilterFunction } from '../../common/filter-function.js';
 import { SorterService } from '../../../service/sorter.service.js';
 import { SortItem } from '../../common/sort-item.js';
 import { TreeRowIf } from '../../common/tree-row-if.js';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { DerivedValuesChangeIf } from './derived-values-change.if.js';
+import { ShowValuesAsIf } from '../../../calc/show-values-as.type.js';
+import { RowDropTargetIf } from '../../../row-drag/row-drop-target.if.js';
 
 /**
  * Represents a  tree-based table model.
@@ -57,6 +61,8 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
     private lastPredictFn?;
     /** `row.keep` was set for the current filter (it depends on the filter and the data, not on expand/collapse). */
     private keepMarked;
+    /** „Show values as“: shown value per row and property (cleared on filter, sorting and invalidation). */
+    private showValuesCache;
     constructor(areaIdent: AreaIdent, rows: TreeRowIf<S>[], defaultRowHeight: number, columnDefs?: ColumnDefIf[]);
     changeColumnOrder(sourceColumnIndex: number, targetColumnIndex: number): void;
     /**
@@ -136,7 +142,84 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
      * @since 1.1.92
      */
     getUnfilteredRowCount(): number;
+    /**
+     * Row drag: true if the rows can be moved to the target – no filter hides a displayed row, and the target is none of
+     * the dragged rows and no descendant of them (no cycle). `"before"` / `"after"` = sibling of the target row,
+     * `"inside"` = last child.
+     *
+     * @param {number[]} rowIndices - display indices of the dragged rows
+     * @param {RowDropTargetIf} target - the drop target
+     * @returns {boolean} true if {@link moveRows} would move them
+     *
+     * @example
+     * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+     * treeModel.canMoveRows([0], { rowIndex: 1, position: "inside" });   // false if row 1 is a child of row 0
+     *
+     * @since 1.1.95
+     */
+    canMoveRows(rowIndices: number[], target: RowDropTargetIf): boolean;
+    /**
+     * Row drag: moves tree rows (with their children) in front of / behind the target row (siblings) or into it
+     * (`"inside"`: last children, the target is expanded) – in place in {@link rows} and the `children` arrays;
+     * `parent` and `deep` follow. See {@link canMoveRows}.
+     *
+     * @param {number[]} rowIndices - display indices of the dragged rows
+     * @param {RowDropTargetIf} target - the drop target (display index before the move)
+     * @returns {boolean} true if moved
+     *
+     * @example
+     * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+     * treeModel.moveRows([3], { rowIndex: 0, position: "inside" });
+     * tableApi.repaintHard();   // or simply tableApi.moveRows([3], { rowIndex: 0, position: "inside" })
+     *
+     * @since 1.1.95
+     */
+    moveRows(rowIndices: number[], target: RowDropTargetIf): boolean;
+    /** The topmost tree rows of the display indices (children travel with their parent). */
+    private getDragRows;
     getValueAt(rowIndex: number, columnIndex: number): any;
+    /**
+     * The value of a tree row for a property – before „Show values as“: the computed value of a calculated column,
+     * otherwise the property (path) of `row.data`. Subclasses (row groups) return their aggregates for group rows.
+     *
+     * @param {TreeRowIf<S>} row - the tree row
+     * @param {string} prop - the property of the column
+     * @returns {any} the raw value
+     * @since 1.1.95
+     */
+    protected getRawValueOfRow(row: TreeRowIf<S>, prop: string): any;
+    /**
+     * The text of a cell: for a „Show values as“ column the formatted value (`"66.7%"`), for a formula error its code;
+     * otherwise like before (`'' + value`).
+     *
+     * @param {number} rowIndex - the row
+     * @param {number} columnIndex - the column
+     * @returns {string} the text
+     */
+    getTextValueAt(rowIndex: number, columnIndex: number): string;
+    /** A „Show values as“ column without an own body renderer shows the formatted text. */
+    getCellRenderer(rowIndex: number, columnIndex: number): CellRendererIf | undefined;
+    /** The message of a formula error as tooltip. */
+    getTooltipAt(rowIndex: number, columnIndex: number): any;
+    /**
+     * Drops derived values: cached aggregates of formulas and „Show values as“ (called by the table on filter,
+     * sorting, editing, `updateCells` and `api.repaint()`).
+     *
+     * @param {DerivedValuesChangeIf} [_change] - the changed rows (not used here)
+     * @since 1.1.95
+     */
+    invalidateDerivedValues(_change?: DerivedValuesChangeIf): void;
+    /**
+     * „Show values as“ of one tree row: percentages of the column total relate to the (filtered) leaf rows,
+     * `percentOfParentTotal`, `runningTotal`, `differenceFromPrevious` and `rank` to the displayed siblings.
+     */
+    protected applyShowValuesAs(row: TreeRowIf<S>, property: string, value: unknown, options: ShowValuesAsIf): unknown;
+    protected readPropertyPath(t: any, property: string): unknown;
+    protected getAggregationSourceForValues(): {
+        signal: unknown;
+        length: number;
+        rows: () => ArrayLike<unknown>;
+    };
     getRowHeight(_rowIndex: number): number;
     /**
      * All rows share `defaultRowHeight` – unless a subclass overrides `getRowHeight()`, then row heights may

package/lib/table/data/tablemodel/areamodel/area-model.if.d.ts

@@ -1,3 +1,4 @@
+import { RowDropTargetIf } from '../../../row-drag/row-drop-target.if.js';
 import { DerivedValuesChangeIf } from './derived-values-change.if.js';
 import { CellRendererIf } from '../../../renderer/cell-render.if.js';
 import { CheckedType } from '../../common/checked-type.js';
@@ -281,6 +282,40 @@ export interface AreaModelIf {
      * @since 1.1.92
      */
     getUnfilteredRowCount?(): number;
+    /**
+     * Optional (row drag, managed mode): true if the rows can be moved to the target – e.g. false for a node dropped
+     * into its own child, or while a filter hides rows. Without {@link moveRows} the table cannot move rows itself.
+     *
+     * @param {number[]} rowIndices - display indices of the dragged rows (ascending)
+     * @param {RowDropTargetIf} target - the drop target (display index before the move)
+     * @returns {boolean} true if {@link moveRows} would move them
+     *
+     * @example
+     * class TasksBodyModel extends AreaModel {
+     *   tasks: string[] = ["Write", "Test", "Ship"];
+     *   override getRowCount(): number { return this.tasks.length; }
+     *   override getValueAt(rowIndex: number): any { return this.tasks[rowIndex]; }
+     *   canMoveRows(rowIndices: number[], target: RowDropTargetIf): boolean { return target.position !== "inside"; }
+     *   moveRows(rowIndices: number[], target: RowDropTargetIf): boolean {
+     *     return moveArrayItems(this.tasks, rowIndices, getInsertBeforeIndex(target)) > -1;
+     *   }
+     * }
+     *
+     * @since 1.1.95
+     */
+    canMoveRows?(rowIndices: number[], target: RowDropTargetIf): boolean;
+    /**
+     * Optional (row drag, managed mode): moves the rows to the target in the model – the table calls it on a drop and
+     * for `tableApi.moveRows()`, then repaints. Implemented by `AreaModelObjectArray`, `AreaModelArrayOfArrays` and
+     * `AreaModelTree` (in place in their row arrays). See {@link canMoveRows} for an example.
+     *
+     * @param {number[]} rowIndices - display indices of the dragged rows (ascending)
+     * @param {RowDropTargetIf} target - the drop target (display index before the move)
+     * @returns {boolean} true if the rows were moved
+     *
+     * @since 1.1.95
+     */
+    moveRows?(rowIndices: number[], target: RowDropTargetIf): boolean;
     /**
      * Optional: drops cached, derived values (e.g. the totals of an {@link AreaModelAggregateFooter}). The table calls
      * it for all three areas when data may have changed: filter, sorting, editing, `updateCells()` and the public
@@ -319,6 +354,26 @@ export interface AreaModelIf {
      * @since 1.1.94
      */
     isRowHeaderCell?(rowIndex: number, columnIndex: number): boolean;
+    /**
+     * Optional: true if the column with this property is calculated (`ColumnDefIf.valueGetter` / `formula`).
+     * Implemented by the object-array, tree, row-group and pivot models.
+     *
+     * @example
+     * tableModel.getBodyModel().isCalculatedProperty?.("total");   // true
+     *
+     * @since 1.1.95
+     */
+    isCalculatedProperty?(property: string): boolean;
+    /**
+     * Optional: the value of a column for a row object – computed for a calculated column, otherwise the property
+     * path ({@link TableApi.getRowValue}). Implemented by the object-array, tree, row-group and pivot models.
+     *
+     * @example
+     * tableModel.getBodyModel().getRowValue?.({ price: 25, quantity: 10 }, "total");   // 250
+     *
+     * @since 1.1.95
+     */
+    getRowValue?(row: any, property: string): unknown;
     /**
      * Returns the value of the cell at the specified row and column indices.
      * This is one of the most important methods in the area model, as it provides

package/lib/table/data/tablemodel/column/column-def.d.ts

@@ -1,5 +1,5 @@
 import { SizeIf } from '../../common/size.if.js';
-import { ColumnDefIf, ValueRowSortComparator } from './column-def.if.js';
+import { CellValidator, ColumnDefIf, RowDragColumnOption, ValueRowSortComparator } from './column-def.if.js';
 import { CellRendererIf } from '../../../renderer/cell-render.if.js';
 import { AreaObjectMapType } from '../../common/area-map.type.js';
 import { AreaObjectMap } from '../../common/area-map.js';
@@ -7,6 +7,9 @@ import { BooleanFunction } from '../../common/boolean-function.js';
 import { SortState } from '../../common/sort-state.type.js';
 import { GetEditRenderer } from '../../../renderer/edit/edit-cell-renderer.type.js';
 import { editInputPipe } from '../../../renderer/edit/edit-input-pipe.if.js';
+import { ValueGetter, ValueSetter } from '../../../calc/value-getter.type.js';
+import { ShowValuesAsConfig } from '../../../calc/show-values-as.type.js';
+import { FormulaOptionsIf } from '../../../formula/formula-options.if.js';
 
 /**
  * The column definition – see {@link ColumnDefIf} for all fields.
@@ -52,6 +55,17 @@ export declare class ColumnDef implements ColumnDefIf {
     editInputPipe?: editInputPipe | undefined;
     isVisible: BooleanFunction;
     visible: boolean;
+    /** A calculated column, see {@link ColumnDefIf.valueGetter}. */
+    valueGetter?: ValueGetter;
+    /** Writes an edited calculated value back, see {@link ColumnDefIf.valueSetter}. */
+    valueSetter?: ValueSetter;
+    /** „Show values as“, see {@link ColumnDefIf.showValuesAs}. */
+    showValuesAs?: ShowValuesAsConfig;
+    /** The formula of a formula column, see {@link ColumnDefIf.formula}. */
+    formula?: string;
+    rowDrag?: RowDragColumnOption;
+    /** Checks edited values, see {@link ColumnDefIf.validate} (since 1.1.96). */
+    validate?: CellValidator;
     constructor(property: string, headerLabel: string, width?: SizeIf, classes?: AreaObjectMapType<string[]>, rendererMap?: AreaObjectMapType<CellRendererIf>, minWidth?: SizeIf, maxWidth?: SizeIf, sortable?: BooleanFunction | undefined, sortComparator?: ValueRowSortComparator | undefined, sortState?: SortState | undefined, sortStatesOrder?: SortState[] | undefined, sortIconVisible?: BooleanFunction | undefined, editable?: BooleanFunction | undefined, getEditRenderer?: GetEditRenderer | undefined, editInputPipe?: editInputPipe | undefined, isVisible?: BooleanFunction);
     static bodyRenderer(bodyRenderer: CellRendererIf): AreaObjectMap<CellRendererIf>;
     /**
@@ -109,5 +123,21 @@ export declare class ColumnDef implements ColumnDefIf {
         getEditRenderer?: GetEditRenderer;
         /** Converts the editor text before it is stored, e.g. `editInputPipeForNumber`. */
         editInputPipe?: editInputPipe;
+        /** A calculated column: `(row, context) => value` (since 1.1.95). */
+        valueGetter?: ValueGetter;
+        /** Makes a calculated column editable (since 1.1.95). */
+        valueSetter?: ValueSetter;
+        /** „Show values as“: `"percentOfColumnTotal"`, `"rank"` … (since 1.1.95). */
+        showValuesAs?: ShowValuesAsConfig;
+        /**
+         * A formula column, e.g. `"[price] * [quantity] * 1.19"` – compiled once into the `valueGetter` (since 1.1.95,
+         * see {@link compileFormula}). Takes precedence over `valueGetter`.
+         */
+        formula?: string;
+        /** Own functions of the formula (since 1.1.95). */
+        formulaOptions?: FormulaOptionsIf;
+        rowDrag?: RowDragColumnOption;
+        /** Checks edited values: a message for an invalid value (since 1.1.96). */
+        validate?: CellValidator;
     }): ColumnDefIf;
 }

package/lib/table/data/tablemodel/column/column-def.if.d.ts

@@ -5,6 +5,8 @@ import { BooleanFunction } from '../../common/boolean-function.js';
 import { SortState } from '../../common/sort-state.type.js';
 import { GetEditRenderer } from '../../../renderer/edit/edit-cell-renderer.type.js';
 import { editInputPipe } from '../../../renderer/edit/edit-input-pipe.if.js';
+import { ValueGetter, ValueSetter } from '../../../calc/value-getter.type.js';
+import { ShowValuesAsConfig } from '../../../calc/show-values-as.type.js';
 
 /**
  * Represents a function that compares two values for sorting purposes.
@@ -116,4 +118,88 @@ export interface ColumnDefIf {
     getEditRenderer?: GetEditRenderer;
     /** Converts the text of the editor before it is written into the model, e.g. {@link editInputPipeForNumber}. */
     editInputPipe?: editInputPipe;
+    /**
+     * A calculated column: computes the value from the row instead of reading `property` (the data stays unchanged).
+     * Sorting, filter ({@link TableApi.getRowValue}), copy, Excel, totals (`footerAggregates`) and row groups use the
+     * computed value. `property` stays the id of the column (state, `footerAggregates`, other formulas).
+     * Without a {@link ColumnDefIf.valueSetter} the column cannot be edited.
+     *
+     * Supported by the models of `TableFactory.createTableModel({ rows })`, trees, row groups (not by array-of-arrays
+     * models; an own `AreaModel` calls it itself).
+     *
+     * @example
+     * ColumnDef.create({ property: "total", headerLabel: "Total", sortable: TrueFn,
+     *                    valueGetter: (o: Item) => o.price * o.quantity })
+     *
+     * @see Training: [Columns with ColumnDef](https://gui.expert/training/column-definitions/)
+     * @since 1.1.95
+     */
+    valueGetter?: ValueGetter;
+    /**
+     * Makes a calculated column editable: writes the edited value back into the row (return `false` to reject).
+     *
+     * @example
+     * valueSetter: (o: Item, v: unknown) => { o.price = Number(v) / o.quantity; }
+     *
+     * @since 1.1.95
+     */
+    valueSetter?: ValueSetter;
+    /**
+     * Shows the numbers of the column differently without changing the data: share of the column total, running
+     * total, rank … (see {@link ShowValuesAs}). Change it at runtime with {@link TableApi.setShowValuesAs}.
+     *
+     * @example
+     * ColumnDef.create({ property: "total", headerLabel: "Share", showValuesAs: "percentOfColumnTotal" })
+     *
+     * @since 1.1.95
+     */
+    showValuesAs?: ShowValuesAsConfig;
+    /**
+     * The formula of a formula column (`ColumnDef.create({ formula })` compiles it into the `valueGetter`), e.g.
+     * `"[price] * [quantity] * 1.19"`. Informational – change it with {@link TableApi.setColumnFormula}.
+     *
+     * @since 1.1.95
+     */
+    formula?: string;
+    /**
+     * Row drag: the body cells of this column get a drag handle (`true`, or a function that decides per row – e.g. no
+     * handle for locked rows). Dragging the handle moves the row (see {@link TableOptionsIf.rowDragOptions}); the keyboard
+     * alternative is Ctrl+Alt+↑/↓. `TableFactory.createTableModel({ rows, rowDrag: true })` sets it on the first data
+     * column.
+     *
+     * @example
+     * ColumnDef.create({ property: "title", headerLabel: "Task", rowDrag: (task: { locked: boolean }) => !task.locked })
+     *
+     * @since 1.1.95
+     */
+    rowDrag?: RowDragColumnOption;
+    /**
+     * Checks an edited, filled or pasted value (after `editInputPipe`): return a message for an invalid value,
+     * `undefined` for a valid one. Batch edit: invalid values are marked (`ge-table-cell-invalid`, the message as
+     * tooltip) and block {@link TableApi.commitBatchEdit}; otherwise an invalid value is not written.
+     *
+     * @example
+     * ColumnDef.create({
+     *   property: "price", headerLabel: "Price", editable: TrueFn, editInputPipe: editInputPipeForNumber,
+     *   validate: (value: unknown) => typeof value === "number" && value >= 0 ? undefined : "A price is a number ≥ 0",
+     * })
+     *
+     * @since 1.1.96
+     */
+    validate?: CellValidator;
 }
+/**
+ * {@link ColumnDefIf.validate}: a message for an invalid value, `undefined` (or `null`, `""`) for a valid one.
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export type CellValidator<T = any> = (value: unknown, row: T) => string | undefined | null | void;
+/**
+ * {@link ColumnDefIf.rowDrag}: `true` = every row has a drag handle in this column, a function decides per row
+ * (`row` = the row object, a `TreeRow` in a tree; `rowIndex` = display index).
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export type RowDragColumnOption = boolean | ((row: any, rowIndex: number) => boolean);

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

@@ -5,6 +5,8 @@ import { EventListenerIf } from './event-listener.if.js';
 import { SelectionModelIf } from './selection/selection-model.if.js';
 import { FocusModelIf } from './focus/focus-model.if.js';
 import { GeStateChangeEvent } from './data/common/event/ge-state-change-event.js';
+import { GeBatchEditEvent } from './data/common/event/ge-batch-edit-event.js';
+import { GeRowDragEvent } from './data/common/event/ge-row-drag-event.js';
 
 /**
  * Empty implementation of {@link EventListenerIf} – extend it and override only the events you need.
@@ -33,4 +35,9 @@ export declare class EventAdapter implements EventListenerIf {
     onFocusChanged(_model: FocusModelIf): void;
     /** @since 1.1.92 */
     onStateChanged(_evt: GeStateChangeEvent): void;
+    onRowDragStart(_evt: GeRowDragEvent): void;
+    onRowDragMove(_evt: GeRowDragEvent): void;
+    onRowDragEnd(_evt: GeRowDragEvent): void;
+    /** @since 1.1.96 */
+    onBatchEditChanged(_evt: GeBatchEditEvent): void;
 }

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

@@ -2,6 +2,8 @@ import { GeMouseEvent } from './data/common/event/ge-mouse-event.js';
 import { GeModelChangeEvent } from './data/common/event/ge-model-change-event.js';
 import { GeScrollEvent } from './data/common/event/ge-scroll-event.js';
 import { GeStateChangeEvent } from './data/common/event/ge-state-change-event.js';
+import { GeRowDragEvent } from './data/common/event/ge-row-drag-event.js';
+import { GeBatchEditEvent } from './data/common/event/ge-batch-edit-event.js';
 import { SelectionModelIf } from './selection/selection-model.if.js';
 import { FocusModelIf } from './focus/focus-model.if.js';
 import { EventFocusChangedListenerIf } from './focus/event-focus-changed-listener.if.js';
@@ -63,4 +65,34 @@ export interface EventListenerIf extends EventFocusChangedListenerIf, EventSelec
      * @since 1.1.92
      */
     onStateChanged?(evt: GeStateChangeEvent): void;
+    /**
+     * Optional: a row drag started (drag handle moved past the threshold, or Ctrl+Alt+↑/↓). `evt.preventDefault()`
+     * cancels it. See {@link GeRowDragEvent}.
+     *
+     * @since 1.1.95
+     */
+    onRowDragStart?(evt: GeRowDragEvent): void;
+    /**
+     * Optional: the drop target of a row drag changed (not on every pixel). `evt.preventDefault()` marks the target as
+     * invalid (no drop marker, no drop).
+     *
+     * @since 1.1.95
+     */
+    onRowDragMove?(evt: GeRowDragEvent): void;
+    /**
+     * Optional: a row drag ended – `evt.type` is `"end"` (dropped; `evt.moved` = the table moved the rows) or `"cancel"`.
+     * Managed: called after the move (`evt.toIndex` = the real position). Save the new order here; to veto a drop, call
+     * `evt.preventDefault()` in {@link onRowDragMove}.
+     *
+     * @since 1.1.95
+     */
+    onRowDragEnd?(evt: GeRowDragEvent): void;
+    /**
+     * The pending changes of a batch edit changed: values were marked, set back, written or discarded
+     * ({@link TableApi.startBatchEdit}, {@link TableOptionsIf.batchEdit}). Optional.
+     *
+     * @param {GeBatchEditEvent} evt - type, cells of this step, number of pending and invalid cells
+     * @since 1.1.96
+     */
+    onBatchEditChanged?(evt: GeBatchEditEvent): void;
 }

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

@@ -78,6 +78,17 @@ export interface CreateTableModelPara {
      * @since 1.1.93
      */
     rowNumbersVisible: boolean | Partial<RowNumberOptionsIf>;
+    /**
+     * Row drag: `true` puts a drag handle into the first data column (behind row numbers and checkboxes) –
+     * sets {@link ColumnDefIf.rowDrag} on that column definition. Options: {@link TableOptionsIf.rowDragOptions}.
+     * Default false.
+     *
+     * @example
+     * const tableModel = TableFactory.createTableModel({ rows: orders, rowDrag: true });
+     *
+     * @since 1.1.95
+     */
+    rowDrag: boolean;
     /** Row heights of header, body and footer in px. Default: `tableOptions.defaultRowHeights`, otherwise 34 / 34 / 34. */
     defaultRowHeights: DefaultRowHeightsIf;
     /** The columns: property, header label, width, classes, renderers, sorting, editing. See {@link ColumnDef}. */

package/lib/table/fill/compute-fill-changes.d.ts

@@ -0,0 +1,67 @@
+import { CellRange } from '../data/common/cell-range.js';
+import { CellValueChangeIf } from '../batch-edit/cell-value-change.if.js';
+import { FillDirection } from './fill-direction.type.js';
+import { FillValueContextIf } from './fill-value-context.if.js';
+import { FillMode } from './fill-series.js';
+
+/**
+ * Input of {@link computeFillChanges}.
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface FillRequestIf {
+    /** The selected source range (body display indices, `r1 <= r2`, `c1 <= c2`). */
+    source: CellRange;
+    /** Where the range is extended to. */
+    direction: FillDirection;
+    /** The number of rows (down/up) or columns (right/left) to fill. */
+    count: number;
+    /** Series or copy, see {@link FillMode}. */
+    mode?: FillMode;
+    /** The shown value of a cell (batch edit: the pending value). */
+    getValue: (rowIndex: number, columnIndex: number) => unknown;
+    /** `false` skips a target cell (not editable, hidden column …); the series keeps counting. */
+    isFillable?: (rowIndex: number, columnIndex: number) => boolean;
+    /** Own fill function, see {@link FillHandleOptionsIf.fillValue}. */
+    fillValue?: (ctx: FillValueContextIf) => unknown;
+    /** Row object and property of a cell – for `fillValue`. */
+    getCellInfo?: (rowIndex: number, columnIndex: number) => {
+        row: unknown;
+        property: string;
+    };
+}
+/**
+ * The cells a fill covers: the source range extended by `count` rows or columns in `direction`.
+ *
+ * @param {CellRange} source - the selected range
+ * @param {FillDirection} direction - the direction of the fill
+ * @param {number} count - rows or columns added
+ * @returns {CellRange} source and filled cells together
+ *
+ * @example
+ * getFillRange(new CellRange(2, 1, 3, 1), "down", 3);   // rows 2…6 of column 1
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function getFillRange(source: CellRange, direction: FillDirection, count: number): CellRange;
+/**
+ * The values a fill writes: per line of the source range (each column when filling down/up, each row when filling
+ * right/left) the continuation of its values ({@link computeFillValues}) – DOM-free, the table applies the result with
+ * {@link TableApi.applyCellChanges}.
+ *
+ * @param {FillRequestIf} request - source range, direction, count, value access
+ * @returns {CellValueChangeIf[]} one change per fillable target cell (column = model index)
+ *
+ * @example
+ * const values = [[1], [2]];                                    // a 2 × 1 source range
+ * computeFillChanges({
+ *   source: new CellRange(0, 0, 1, 0), direction: "down", count: 2,
+ *   getValue: (r, c) => values[r]?.[c],
+ * });   // [{ rowIndex: 2, column: 0, value: 3 }, { rowIndex: 3, column: 0, value: 4 }]
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function computeFillChanges(request: FillRequestIf): CellValueChangeIf[];

package/lib/table/fill/fill-direction.type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The direction of a fill: the fill handle was dragged down, up, right or left of the selected range.
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export type FillDirection = "down" | "up" | "right" | "left";

package/lib/table/fill/fill-handle-options.d.ts

@@ -0,0 +1,29 @@
+import { FillHandleOptionsIf } from './fill-handle-options.if.js';
+import { FillValueContextIf } from './fill-value-context.if.js';
+
+/**
+ * The defaults of {@link FillHandleOptionsIf}.
+ *
+ * @example
+ * const options = FillHandleOptions.create(true);
+ * options?.direction;   // "both"
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare class FillHandleOptions implements FillHandleOptionsIf {
+    direction: "vertical" | "horizontal" | "both";
+    fillValue?: (ctx: FillValueContextIf) => unknown;
+    maxCells: number;
+    dragThresholdInPx: number;
+    autoScrollZoneInPx: number;
+    autoScrollMaxSpeedInPx: number;
+    /**
+     * The options of {@link TableOptionsIf.fillHandle}: `undefined`/`false` = no fill handle, `true` = the defaults, an
+     * object = the defaults overridden by its values (`undefined` keeps the default).
+     *
+     * @param {boolean | Partial<FillHandleOptionsIf>} [option] - `tableOptions.fillHandle`
+     * @returns {FillHandleOptionsIf | undefined} complete options, `undefined` if the fill handle is off
+     */
+    static create(option?: boolean | Partial<FillHandleOptionsIf>): FillHandleOptionsIf | undefined;
+}

package/lib/table/fill/fill-handle-options.if.d.ts

@@ -0,0 +1,35 @@
+import { FillValueContextIf } from './fill-value-context.if.js';
+
+/**
+ * Options of the fill handle ({@link TableOptionsIf.fillHandle}): the small square at the bottom right corner of the
+ * selected range. Dragging it fills the neighbouring cells – copies values or continues series (1, 2, 3 …; dates;
+ * `Item 1` → `Item 2`). Needs a {@link SelectionModel} of the type `"range"`.
+ *
+ * @example
+ * const selectionModel = new SelectionModel("range", "multi");   // one model – not a new one per call
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   getSelectionModel: () => selectionModel,
+ *   fillHandle: { direction: "vertical" },
+ * };
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface FillHandleOptionsIf {
+    /** Allowed directions: `"vertical"` (down/up), `"horizontal"` (right/left) or `"both"` (default). */
+    direction: "vertical" | "horizontal" | "both";
+    /**
+     * Own fill function, called for every filled cell. Return the value – or `undefined` for the default
+     * (`ctx.defaultValue`).
+     */
+    fillValue?: (ctx: FillValueContextIf) => unknown;
+    /** At most this many cells are filled at once (default 100,000); a bigger fill is refused and announced. */
+    maxCells: number;
+    /** Distance in px the pointer has to move before a fill starts (default 3). */
+    dragThresholdInPx: number;
+    /** Width in px of the zone at the edges of the body that scrolls automatically (default 40). */
+    autoScrollZoneInPx: number;
+    /** Maximum auto-scroll speed in px per animation frame (default 24). */
+    autoScrollMaxSpeedInPx: number;
+}

package/lib/table/fill/fill-handle-service.d.ts

@@ -0,0 +1,55 @@
+import { TableScope } from '../table-scope.js';
+
+/**
+ * The fill handle of one table (`tableScope.fillHandleService`): the square at the bottom right corner of the selected
+ * range, the pointer drag with preview and auto-scroll, Escape. The values come from {@link TableScope.fillRange}.
+ * Use {@link TableApi.fillRange}, {@link TableApi.isFilling} and {@link TableApi.cancelFill} instead.
+ *
+ * Pointer Events (mouse, touch, pen) only on the handle; its `pointerdown` is prevented, so the mouse handler of the
+ * table (range selection, column drag) never sees it.
+ *
+ * @category Internals
+ * @since 1.1.96
+ */
+export declare class FillHandleService {
+    private readonly tableScope;
+    private handle?;
+    private preview?;
+    private pending?;
+    private session?;
+    private sessionAbortController?;
+    private autoScrollFrame;
+    private suppressClick;
+    private shortcutsSet;
+    constructor(tableScope: TableScope);
+    /** true while the handle is dragged. */
+    isFilling(): boolean;
+    /**
+     * Places the handle at the bottom right corner of the last selected range (called after every render pass) – or
+     * hides it: no fill handle option, no range, the corner scrolled out, an open editor, a blocking overlay.
+     */
+    update(): void;
+    /** The handle's position (the corner of the range) in host coordinates – `undefined` if it is not visible. */
+    private getCornerOf;
+    private ensureHandle;
+    private removeHandle;
+    /** Keyboard alternative on the grid: Ctrl/⌘+D, Ctrl/⌘+R (only directions the options allow). */
+    private updateHostShortcuts;
+    private isHandle;
+    private onPointerDown;
+    private listenToDocument;
+    private onPointerMove;
+    private onPointerUp;
+    private suppressNextClick;
+    private onClickCapture;
+    /** Target cell under the pointer → direction and count; preview; auto-scroll. */
+    private updateTarget;
+    private renderPreview;
+    private updateAutoScroll;
+    private autoScrollStep;
+    /** Cancels a running fill (Escape, `pointercancel`, {@link TableApi.cancelFill}): nothing is changed. */
+    cancel(): void;
+    private stopListening;
+    /** Releases everything (TableScope.destroy). */
+    destroy(): void;
+}