@guiexpert/table 1.1.94 → 1.1.96

package/lib/table/row-drag/move-rows.d.ts

@@ -0,0 +1,157 @@
+import { RowDropTargetIf } from './row-drop-target.if.js';
+import { TreeRowIf } from '../data/common/tree-row-if.js';
+
+/**
+ * Sorted, unique row indices inside `0 … rowCount - 1` (the order of the dragged rows is their display order).
+ *
+ * @param {number[]} rowIndices - any indices, e.g. from a selection
+ * @param {number} rowCount - number of rows
+ * @returns {number[]} a new, ascending array
+ *
+ * @example
+ * normalizeRowIndices([5, 2, 2, 99, -1], 10);   // [2, 5]
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function normalizeRowIndices(rowIndices: readonly number[], rowCount: number): number[];
+/**
+ * The index in front of which the rows are inserted (before the move): `"after"` row 7 = in front of row 8.
+ * `"inside"` counts like `"after"` (flat lists have no children).
+ *
+ * @param {RowDropTargetIf} target - the drop target
+ * @returns {number} the insert position, 0 … rowCount
+ *
+ * @example
+ * getInsertBeforeIndex({ rowIndex: 7, position: "after" });    // 8
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function getInsertBeforeIndex(target: RowDropTargetIf): number;
+/**
+ * The index of the first moved row after a move in a flat list: the insert position minus the moved rows in front
+ * of it. A target inside the moved rows (or right next to them) returns their current index – nothing changes.
+ *
+ * @param {number[]} rowIndices - ascending, unique row indices ({@link normalizeRowIndices})
+ * @param {RowDropTargetIf} target - the drop target
+ * @returns {number} the new index of the first moved row, -1 without rows
+ *
+ * @example
+ * // D1: row 3 (index 2) dropped between row 7 and 8 → it is row 7 (index 6) afterwards
+ * calcMoveToIndex([2], { rowIndex: 6, position: "after" });   // 6
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function calcMoveToIndex(rowIndices: readonly number[], target: RowDropTargetIf): number;
+/**
+ * Moves items of an array **in place** (like `Array.prototype.sort`): the items at `indices` keep their order and are
+ * inserted in front of `insertBefore` (an index of the array before the move, `array.length` = at the end).
+ *
+ * @param {T[]} array - the array to change
+ * @param {number[]} indices - ascending, unique indices ({@link normalizeRowIndices})
+ * @param {number} insertBefore - 0 … array.length
+ * @returns {number} the new index of the first moved item (-1 if nothing was given)
+ *
+ * @example
+ * const list = ["a", "b", "c", "d", "e"];
+ * moveArrayItems(list, [1, 3], 5);   // 3
+ * list;                              // ["a", "c", "e", "b", "d"]
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function moveArrayItems<T>(array: T[], indices: readonly number[], insertBefore: number): number;
+/**
+ * The dragged tree rows without the ones that travel with an ancestor (a child of a dragged node moves with it).
+ *
+ * @param {TreeRowIf<S>[]} rows - dragged rows in display order
+ * @returns {TreeRowIf<S>[]} the topmost dragged rows, same order
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function getTopmostTreeRows<S>(rows: readonly TreeRowIf<S>[]): TreeRowIf<S>[];
+/**
+ * True if the tree rows can be dropped at the target row: the target is none of the dragged rows and no descendant
+ * of them (a node cannot become its own child – no cycle).
+ *
+ * @param {TreeRowIf<S>[]} rows - dragged rows
+ * @param {TreeRowIf<S>} targetRow - the row under the drop marker
+ * @returns {boolean} false for a cycle
+ *
+ * @example
+ * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+ * const node = treeModel.rows[0];
+ * canMoveTreeRows([node], node.children?.[0]);   // false – into its own child
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function canMoveTreeRows<S>(rows: readonly TreeRowIf<S>[], targetRow: TreeRowIf<S> | undefined): boolean;
+/**
+ * Moves tree rows **in place**: in front of / behind `targetRow` (siblings, same parent) or `"inside"` it (last
+ * children; the target is expanded). Children travel with their parent; `parent` and `deep` are updated.
+ *
+ * @param {TreeRowIf<S>[]} roots - the top-level rows (e.g. `AreaModelTree.rows`)
+ * @param {TreeRowIf<S>[]} rows - dragged rows in display order
+ * @param {TreeRowIf<S>} targetRow - the row under the drop marker
+ * @param {"before" | "after" | "inside"} position - where to drop
+ * @returns {boolean} false if nothing was moved (cycle, no rows)
+ *
+ * @example
+ * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+ * moveTreeRows(treeModel.rows, [treeModel.rows[2]], treeModel.rows[0], "inside");   // 3rd root → child of the 1st
+ * treeModel.recalcVisibleTreeRows();
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function moveTreeRows<S>(roots: TreeRowIf<S>[], rows: readonly TreeRowIf<S>[], targetRow: TreeRowIf<S>, position: RowDropTargetIf["position"]): boolean;
+/**
+ * Flat area models: true if the dragged rows can be moved – all rows are displayed (no filter hides one), the target
+ * row exists and is not `"inside"`.
+ *
+ * @param {number} displayedCount - displayed rows (`getRowCount()`)
+ * @param {number} allCount - all rows (`getUnfilteredRowCount()`)
+ * @param {number[]} rowIndices - display indices of the dragged rows
+ * @param {RowDropTargetIf} target - the drop target
+ * @returns {boolean} true if a move is possible
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function canMoveFlatRows(displayedCount: number, allCount: number, rowIndices: readonly number[], target: RowDropTargetIf): boolean;
+/**
+ * Flat area models: moves the rows in the displayed array and writes the new order back to the array of all rows –
+ * both in place. Used by `AreaModelObjectArray` and `AreaModelArrayOfArrays`.
+ *
+ * @param {T[]} displayed - displayed rows (display order)
+ * @param {T[]} all - all rows (same rows – no filter hides one)
+ * @param {number[]} rowIndices - display indices of the dragged rows
+ * @param {RowDropTargetIf} target - the drop target
+ * @returns {boolean} true if moved
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function moveFlatRows<T>(displayed: T[], all: T[], rowIndices: readonly number[], target: RowDropTargetIf): boolean;
+/**
+ * The row at a content position (y in px from the top of all body rows): constant row heights are computed directly,
+ * variable ones by a binary search over the row tops. Positions above / below the rows give the first / last row.
+ *
+ * @param {number} contentY - y in content pixels
+ * @param {number} rowCount - number of rows (> 0)
+ * @param {(rowIndex: number) => number} getYPosByRowIndex - top of a row in content pixels (`AreaModelIf.getYPosByRowIndex`)
+ * @param {number} [constantRowHeight] - the height of every row, if they are all equal (`AreaModelIf.getConstantRowHeight`)
+ * @returns {number} the row index, 0 … rowCount - 1
+ *
+ * @example
+ * const body = tableModel.getBodyModel();
+ * const rowIndex = findRowIndexAtY(1234, body.getRowCount(), i => body.getYPosByRowIndex(i), body.getConstantRowHeight?.());
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare function findRowIndexAtY(contentY: number, rowCount: number, getYPosByRowIndex: (rowIndex: number) => number, constantRowHeight?: number): number;

package/lib/table/row-drag/row-drag-options.d.ts

@@ -0,0 +1,28 @@
+import { RowDragOptionsIf } from './row-drag-options.if.js';
+
+/**
+ * The defaults of {@link RowDragOptionsIf}.
+ *
+ * @example
+ * const options = RowDragOptions.create({ managed: false });
+ * options.autoScrollZoneInPx;   // 40
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export declare class RowDragOptions implements RowDragOptionsIf {
+    managed: boolean;
+    multiRow: boolean;
+    treeDropInside: boolean;
+    dragThresholdInPx: number;
+    autoScrollZoneInPx: number;
+    autoScrollMaxSpeedInPx: number;
+    ghostText?: (rows: any[]) => string;
+    /**
+     * The defaults, overridden by the given values (`undefined` keeps the default).
+     *
+     * @param {Partial<RowDragOptionsIf>} [options] - e.g. `tableOptions.rowDragOptions`
+     * @returns {RowDragOptionsIf} complete options
+     */
+    static create(options?: Partial<RowDragOptionsIf>): RowDragOptionsIf;
+}

package/lib/table/row-drag/row-drag-options.if.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Options of row dragging ({@link TableOptionsIf.rowDragOptions}). Rows get a drag handle in every column with
+ * {@link ColumnDefIf.rowDrag} (or `TableFactory.createTableModel({ rows, rowDrag: true })`).
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   rowDragOptions: { managed: false, autoScrollMaxSpeedInPx: 40 }   // events only – the app moves the rows
+ * };
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export interface RowDragOptionsIf {
+    /**
+     * `true` (default): the table moves the rows itself (`AreaModelIf.moveRows`) – only while the table is neither
+     * sorted (a column with sort state asc/desc) nor filtered. `false`: the table only reports the drag
+     * (`onRowDragStart/Move/End`), the app moves the rows (e.g. after the server confirmed), always allowed.
+     */
+    managed: boolean;
+    /** `true` (default): grabbing a selected row drags all rows with a selection (their order stays). */
+    multiRow: boolean;
+    /** `true` (default): tree – dropping on the middle of a row makes the rows its children. */
+    treeDropInside: boolean;
+    /** Distance in px the pointer has to move before a drag starts (default 4) – below it is a click on the handle. */
+    dragThresholdInPx: number;
+    /** Height in px of the zone at the top and bottom edge of the body that scrolls automatically (default 40). */
+    autoScrollZoneInPx: number;
+    /** Maximum auto-scroll speed in px per animation frame (default 24). */
+    autoScrollMaxSpeedInPx: number;
+    /**
+     * Text of the drag ghost. Default: the text of the handle cell of the first row, "(+2)" for two more rows.
+     * The text is shown as text (never as HTML).
+     */
+    ghostText?: (rows: any[]) => string;
+}

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

@@ -0,0 +1,130 @@
+import { TableScope } from '../table-scope.js';
+import { AreaModelIf } from '../data/tablemodel/areamodel/area-model.if.js';
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+import { RowDropTargetIf } from './row-drop-target.if.js';
+import { RowDragOptionsIf } from './row-drag-options.if.js';
+
+/**
+ * Whether a body cell shows a drag handle: `"none"`, `"enabled"`, or `"disabled"` (managed drag while the table is
+ * sorted or filtered).
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export type RowDragHandleState = "none" | "enabled" | "disabled";
+/**
+ * Row drag of one table (`tableScope.rowDragService`): drag handles ({@link ColumnDefIf.rowDrag}), pointer drag with
+ * ghost, drop marker and auto-scroll, the keyboard alternative (`MOVE_ROW_UP` / `MOVE_ROW_DOWN`) and the managed move.
+ * Use {@link TableApi.moveRows}, {@link TableApi.isRowDragging} and {@link TableApi.cancelRowDrag} instead.
+ *
+ * Pointer Events (mouse, touch, pen) – only on the drag handle; its `pointerdown` is prevented, so the mouse handler
+ * of the table (range selection, column drag) never sees it.
+ *
+ * @category Internals
+ * @since 1.1.95
+ */
+export declare class RowDragService {
+    private readonly tableScope;
+    private pending?;
+    private session?;
+    private sessionAbortController?;
+    private ghost?;
+    private indicator?;
+    private autoScrollFrame;
+    private suppressClick;
+    private warnedUnsupported;
+    constructor(tableScope: TableScope);
+    /** The options of this table ({@link TableOptionsIf.rowDragOptions} + defaults). */
+    get options(): RowDragOptionsIf;
+    /** true while rows are dragged with the pointer. */
+    isDragging(): boolean;
+    /** true if the row is one of the dragged rows (it is painted dimmed). */
+    isDragSourceRow(rowIndex: number): boolean;
+    /**
+     * Why a managed drag is not possible right now: `"sorted"` (a column has the sort state asc/desc), `"filtered"`
+     * (a filter hides rows) – `undefined` if it is possible or the drag is unmanaged.
+     */
+    getBlockReason(): "sorted" | "filtered" | undefined;
+    /**
+     * The drag handle of a body cell: none (no `rowDrag`, a group or pivot row, a managed drag the model cannot do),
+     * enabled or disabled (managed + sorted/filtered).
+     */
+    getHandleState(rowIndex: number, columnDef: ColumnDefIf | undefined, areaModel: AreaModelIf): RowDragHandleState;
+    /**
+     * Adds the drag handle to a rendered body cell (called by the render pass for columns with `rowDrag`).
+     *
+     * @param {HTMLDivElement} cell - the cell div
+     * @param {RowDragHandleState} state - from {@link getHandleState}
+     */
+    decorateCell(cell: HTMLDivElement, state: RowDragHandleState): void;
+    private onPointerDown;
+    private listenToDocument;
+    private onPointerMove;
+    private onPointerUp;
+    private onPointerCancel;
+    private onKeyDown;
+    private onClickCapture;
+    /** Starts the drag after the threshold – false if the listener vetoed it. */
+    private startPointerDrag;
+    /** Computes the drop target from the pointer position, reports a change, moves ghost and marker, auto-scrolls. */
+    private updateTarget;
+    private autoScrollStep;
+    /**
+     * Speed in px per frame (negative = up): a quadratic ramp inside the zone at the top/bottom edge of the body, full
+     * speed above (header) and below (footer) the body.
+     */
+    private calcAutoScrollSpeed;
+    /** The row under the pointer and the position (before/after/inside) – computed, not read from the DOM. */
+    private computeTarget;
+    private isValidTarget;
+    private drop;
+    /**
+     * Cancels a running drag (Escape, `pointercancel`, {@link TableApi.cancelRowDrag}, destroy): `onRowDragEnd` with the
+     * type `"cancel"`, nothing is moved.
+     */
+    cancel(originalEvent?: PointerEvent | KeyboardEvent): void;
+    /** Ends the pointer session: listeners, ghost, marker, auto-scroll. */
+    private stopListening;
+    /** Releases everything (TableScope.destroy). A running drag is cancelled. */
+    destroy(): void;
+    private createDragElements;
+    private getGhostText;
+    private renderDragElements;
+    /** The rows' width (fixed columns + center columns), at most the visible width – the marker ends with the rows. */
+    private getMarkerWidth;
+    /**
+     * Moves rows in the model (managed), repaints, keeps focus and selection on the moved rows and announces the new
+     * position.
+     *
+     * @param {number[]} rowIndices - display indices
+     * @param {RowDropTargetIf} target - drop target
+     * @param {boolean} reselect - select the moved rows again (multi-row drag)
+     * @returns {number} the new display index of the first moved row, -1 if nothing moved
+     */
+    moveRows(rowIndices: number[], target: RowDropTargetIf, reselect?: boolean): number;
+    private findDisplayIndices;
+    /**
+     * `MOVE_ROW_UP` / `MOVE_ROW_DOWN`: moves the focused row (or the selected rows, if it is one of them) one position.
+     * Trees: among the siblings.
+     *
+     * @param {-1 | 1} direction - up or down
+     * @returns {boolean} true if the key was used (a row with a drag handle has the focus)
+     */
+    moveByKeyboard(direction: -1 | 1): boolean;
+    private getFlatKeyboardTarget;
+    private getTreeKeyboardTarget;
+    /** The dragged rows for a grabbed row: all rows with a selection if it is one of them (multiRow), else this one. */
+    getDragRowIndices(rowIndex: number): number[];
+    private getRows;
+    /** Index of the first column whose drag handle is shown for the row, -1 if none. */
+    private getHandleColumnIndex;
+    /** The state of the handle of a row that has one (see {@link getHandleColumnIndex}). */
+    private getHandleStateOfRow;
+    /** true if a column has the sort state asc or desc (the header shows the arrow). */
+    private isSorted;
+    private isManaged;
+    private canModelMove;
+    private createEvent;
+    private announceNotPossible;
+    private texts;
+}

package/lib/table/row-drag/row-drop-target.if.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where dragged rows are dropped, relative to the row under the drop marker:
+ * `"before"` / `"after"` that row, or `"inside"` it (it becomes the last child – trees only).
+ *
+ * @example
+ * const target: RowDropTargetIf = { rowIndex: 7, position: "before" };   // between row 7 and row 8 (1-based)
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export type RowDropPosition = "before" | "after" | "inside";
+/**
+ * The drop target of a row drag ({@link GeRowDragEvent.target}, {@link TableApi.moveRows}).
+ *
+ * `rowIndex` is the display index (body row index) of the target row **before** the rows are moved.
+ *
+ * @example
+ * // move the rows 2 and 3 behind the last row
+ * tableApi.moveRows([2, 3], { rowIndex: tableApi.getDisplayedRowCount() - 1, position: "after" });
+ *
+ * @category Row drag
+ * @since 1.1.95
+ */
+export interface RowDropTargetIf {
+    /** Display index of the row next to (or under) the drop marker – before the move. */
+    rowIndex: number;
+    /** Before or after that row, or inside it (tree: becomes its last child). */
+    position: RowDropPosition;
+}

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

@@ -24,6 +24,8 @@ import { ExcelServiceIf } from './excel-service.if.js';
  * @category Export & clipboard
  */
 export declare class ExcelService implements ExcelServiceIf {
+    /** Understands cells `{ value, numberFormat }` ({@link ExcelFormattedValueIf}), since 1.1.95. */
+    readonly supportsNumberFormats = true;
     /**
      * Downloads a matrix data as an Excel file.
      *
@@ -44,6 +46,10 @@ export declare class ExcelService implements ExcelServiceIf {
     createExcelBlob(matrix: Array<Array<any>>, author?: string): Promise<Blob>;
     private generateMap;
     private getX1WorksheetsSheet1Xml;
+    /** Number format → cell style index (1-based; 0 = default), filled by withNumberFormats() before the sheet is written. */
+    private numberFormatStyles;
+    /** Adds one cell style per number format used in the matrix (`<numFmts>` + `<cellXfs>`); unchanged without formats. */
+    private withNumberFormats;
     private escapeXml;
     private getCellAddress;
     /**

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

@@ -7,4 +7,39 @@
 export interface ExcelServiceIf {
     /** Creates the file from `matrix` (rows of values) and hands it to the browser as download. */
     downloadExcel(matrix: Array<Array<any>>, filename: string, author?: string): void | Promise<void>;
+    /**
+     * True if the service understands cells of the form {@link ExcelFormattedValueIf} (`{ value, numberFormat }`).
+     * Only then {@link TableApi.downloadExcel} exports percentages of „Show values as“ columns with the format `0.0%`;
+     * otherwise a service gets plain numbers (since 1.1.95).
+     */
+    readonly supportsNumberFormats?: boolean;
 }
+/**
+ * A cell of an Excel matrix with a number format, e.g. a share shown as percentage. Understood by
+ * {@link ExcelService} (`supportsNumberFormats`).
+ *
+ * @example
+ * await new ExcelService().downloadExcel([["Share"], [{ value: 0.667, numberFormat: "0.0%" }]], "shares.xlsx");
+ *
+ * @since 1.1.95
+ * @category Export & clipboard
+ */
+export interface ExcelFormattedValueIf {
+    /** The number. */
+    value: number;
+    /** An Excel number format code, e.g. `"0.0%"`, `"#,##0.00"`. */
+    numberFormat: string;
+}
+/**
+ * True for a cell of the form {@link ExcelFormattedValueIf}.
+ *
+ * @param {unknown} cell - a cell of an Excel matrix
+ * @returns {boolean} whether it is a number with format
+ *
+ * @example
+ * isExcelFormattedValue({ value: 0.5, numberFormat: "0%" });   // true
+ *
+ * @since 1.1.95
+ * @category Export & clipboard
+ */
+export declare function isExcelFormattedValue(cell: unknown): cell is ExcelFormattedValueIf;