@alaarab/ogrid-core 2.0.14 → 2.0.16

package/dist/esm/utils/clipboardHelpers.js

@@ -0,0 +1,56 @@
+import { getCellValue } from './cellValue';
+import { normalizeSelectionRange } from '../types';
+/**
+ * Format a single cell value for inclusion in a TSV clipboard string.
+ * Strips tabs and newlines so they don't corrupt the TSV structure.
+ *
+ * @param raw         Raw cell value (from getCellValue).
+ * @param formatted   Formatted value (from valueFormatter, if present).
+ * @returns TSV-safe string representation of the cell.
+ */
+export function formatCellValueForTsv(raw, formatted) {
+    const val = formatted != null && formatted !== '' ? formatted : raw;
+    if (val == null || val === '')
+        return '';
+    return String(val).replace(/\t/g, ' ').replace(/\n/g, ' ');
+}
+/**
+ * Serialize a rectangular cell range to a TSV (tab-separated values) string
+ * suitable for writing to the clipboard.
+ *
+ * @param items       Flat array of all row data objects.
+ * @param visibleCols Visible column definitions.
+ * @param range       The selection range to serialize (will be normalized).
+ * @returns TSV string with rows separated by \\r\\n and columns by \\t.
+ */
+export function formatSelectionAsTsv(items, visibleCols, range) {
+    const norm = normalizeSelectionRange(range);
+    const rows = [];
+    for (let r = norm.startRow; r <= norm.endRow; r++) {
+        const cells = [];
+        for (let c = norm.startCol; c <= norm.endCol; c++) {
+            if (r >= items.length || c >= visibleCols.length)
+                break;
+            const item = items[r];
+            const col = visibleCols[c];
+            const raw = getCellValue(item, col);
+            const formatted = col.valueFormatter ? col.valueFormatter(raw, item) : raw;
+            cells.push(formatCellValueForTsv(raw, formatted));
+        }
+        rows.push(cells.join('\t'));
+    }
+    return rows.join('\r\n');
+}
+/**
+ * Parse a TSV clipboard string into a 2D array of cell strings.
+ * Handles both \\r\\n and \\n line endings. Ignores trailing empty lines.
+ *
+ * @param text  Raw clipboard text (TSV format).
+ * @returns 2D array: rows of cells. Empty if text is blank.
+ */
+export function parseTsvClipboard(text) {
+    if (!text.trim())
+        return [];
+    const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
+    return lines.map((line) => line.split('\t'));
+}

package/dist/esm/utils/index.js

@@ -17,3 +17,7 @@ export { debounce } from './debounce';
 export { measureRange, injectGlobalStyles } from './dom';
 export { computeNextSortState } from './sortHelpers';
 export { measureColumnContentWidth, AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX } from './columnAutosize';
+export { findCtrlArrowTarget, computeTabNavigation } from './keyboardNavigation';
+export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed } from './selectionHelpers';
+export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, } from './clipboardHelpers';
+export { UndoRedoStack } from './undoRedoStack';

package/dist/esm/utils/keyboardNavigation.js

@@ -0,0 +1,72 @@
+/**
+ * Pure keyboard navigation helpers shared across React, Vue, Angular, and JS.
+ * No framework dependencies — takes plain values, returns plain values.
+ */
+/**
+ * Excel-style Ctrl+Arrow: find the target position along a 1D axis.
+ * - Non-empty current + non-empty next → scan through non-empties, stop at last before empty/edge.
+ * - Otherwise → skip empties, land on next non-empty or edge.
+ *
+ * @param pos   Current position (row or column index).
+ * @param edge  The boundary position (0 for backward, max for forward).
+ * @param step  Direction: +1 (forward) or -1 (backward).
+ * @param isEmpty  Predicate: returns true if the cell at this index is empty.
+ * @returns     The target position after the jump.
+ */
+export function findCtrlArrowTarget(pos, edge, step, isEmpty) {
+    if (pos === edge)
+        return pos;
+    const next = pos + step;
+    if (!isEmpty(pos) && !isEmpty(next)) {
+        // Scan forward through non-empties; stop at the last before an empty or edge
+        let p = next;
+        while (p !== edge) {
+            if (isEmpty(p + step))
+                return p;
+            p += step;
+        }
+        return edge;
+    }
+    // Skip empties; land on first non-empty or edge
+    let p = next;
+    while (p !== edge) {
+        if (!isEmpty(p))
+            return p;
+        p += step;
+    }
+    return edge;
+}
+/**
+ * Compute the new Tab navigation position given the current position and direction.
+ *
+ * @param rowIndex      Current row index.
+ * @param columnIndex   Current absolute column index (includes checkbox offset).
+ * @param maxRowIndex   Maximum row index (items.length - 1).
+ * @param maxColIndex   Maximum absolute column index.
+ * @param colOffset     Number of non-data leading columns (checkbox column offset).
+ * @param shiftKey      True if Shift is held (backward tab).
+ * @returns New { rowIndex, columnIndex } after tab.
+ */
+export function computeTabNavigation(rowIndex, columnIndex, maxRowIndex, maxColIndex, colOffset, shiftKey) {
+    let newRow = rowIndex;
+    let newCol = columnIndex;
+    if (shiftKey) {
+        if (columnIndex > colOffset) {
+            newCol = columnIndex - 1;
+        }
+        else if (rowIndex > 0) {
+            newRow = rowIndex - 1;
+            newCol = maxColIndex;
+        }
+    }
+    else {
+        if (columnIndex < maxColIndex) {
+            newCol = columnIndex + 1;
+        }
+        else if (rowIndex < maxRowIndex) {
+            newRow = rowIndex + 1;
+            newCol = colOffset;
+        }
+    }
+    return { rowIndex: newRow, columnIndex: newCol };
+}

package/dist/esm/utils/selectionHelpers.js

@@ -0,0 +1,46 @@
+/**
+ * Compare two selection ranges by value (deep equality).
+ * Returns true if both ranges are equal, including when both are null.
+ */
+export function rangesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return (a.startRow === b.startRow &&
+        a.endRow === b.endRow &&
+        a.startCol === b.startCol &&
+        a.endCol === b.endCol);
+}
+/**
+ * Clamp a selection range to the grid bounds (0-based, inclusive).
+ *
+ * @param range         The selection range to clamp.
+ * @param maxRow        Maximum valid row index (items.length - 1).
+ * @param maxCol        Maximum valid column index (visibleCols.length - 1).
+ * @returns The clamped range, or null if the grid is empty.
+ */
+export function clampSelectionToBounds(range, maxRow, maxCol) {
+    if (maxRow < 0 || maxCol < 0)
+        return null;
+    return {
+        startRow: Math.max(0, Math.min(range.startRow, maxRow)),
+        endRow: Math.max(0, Math.min(range.endRow, maxRow)),
+        startCol: Math.max(0, Math.min(range.startCol, maxCol)),
+        endCol: Math.max(0, Math.min(range.endCol, maxCol)),
+    };
+}
+/**
+ * Auto-scroll speed: proportional to how far past the scroll edge the pointer is.
+ * Used by drag-selection auto-scroll in both React and Vue.
+ *
+ * @param distance  Distance past the edge threshold (pixels).
+ * @param edgePx    Scroll edge threshold in pixels (default: 40).
+ * @param minSpeed  Minimum scroll speed (default: 2).
+ * @param maxSpeed  Maximum scroll speed (default: 20).
+ * @returns Scroll speed in pixels per interval tick.
+ */
+export function computeAutoScrollSpeed(distance, edgePx = 40, minSpeed = 2, maxSpeed = 20) {
+    const t = Math.min(distance / edgePx, 1);
+    return minSpeed + t * (maxSpeed - minSpeed);
+}

package/dist/esm/utils/undoRedoStack.js

@@ -0,0 +1,125 @@
+/**
+ * Pure undo/redo stack data structure shared across React, Vue, Angular, and JS.
+ * No framework dependencies — all state is plain arrays.
+ *
+ * Usage:
+ *   const stack = new UndoRedoStack<MyEvent>(100);
+ *   stack.push([event]);        // single event
+ *   stack.beginBatch();
+ *   stack.push([event1]);
+ *   stack.push([event2]);
+ *   stack.endBatch();           // event1 + event2 are one undo step
+ *   const batch = stack.undo(); // returns the batch to reverse
+ *   const batch = stack.redo(); // returns the batch to re-apply
+ */
+export class UndoRedoStack {
+    constructor(maxDepth = 100) {
+        this.history = [];
+        this.redoStack = [];
+        this.batch = null;
+        this.maxDepth = maxDepth;
+    }
+    /** Whether there are undo steps available. */
+    get canUndo() {
+        return this.history.length > 0;
+    }
+    /** Whether there are redo steps available. */
+    get canRedo() {
+        return this.redoStack.length > 0;
+    }
+    /** Number of history entries. */
+    get historyLength() {
+        return this.history.length;
+    }
+    /** Number of redo entries. */
+    get redoLength() {
+        return this.redoStack.length;
+    }
+    /** Whether a batch is currently open. */
+    get isBatching() {
+        return this.batch !== null;
+    }
+    /**
+     * Record a group of events as a single undoable step.
+     * If a batch is open, accumulates into the batch instead.
+     * Clears the redo stack on any new entry.
+     */
+    push(events) {
+        if (events.length === 0)
+            return;
+        if (this.batch !== null) {
+            this.batch.push(...events);
+        }
+        else {
+            this.history = [...this.history, events].slice(-this.maxDepth);
+            this.redoStack = [];
+        }
+    }
+    /**
+     * Record a single event as a step (shorthand for push([event])).
+     * If a batch is open, accumulates into the batch instead.
+     */
+    record(event) {
+        this.push([event]);
+    }
+    /**
+     * Start a batch — subsequent record/push calls accumulate into one undo step.
+     * Has no effect if a batch is already open.
+     */
+    beginBatch() {
+        if (this.batch === null) {
+            this.batch = [];
+        }
+    }
+    /**
+     * End a batch — commits all accumulated events as one undo step.
+     * Has no effect if no batch is open or if the batch is empty.
+     */
+    endBatch() {
+        const b = this.batch;
+        this.batch = null;
+        if (!b || b.length === 0)
+            return;
+        this.history = [...this.history, b].slice(-this.maxDepth);
+        this.redoStack = [];
+    }
+    /**
+     * Pop the most recent history entry for undo.
+     * Returns the batch of events (in original order) to be reversed by the caller,
+     * or null if there is nothing to undo.
+     *
+     * The caller is responsible for applying the events in reverse order.
+     */
+    undo() {
+        if (this.history.length === 0)
+            return null;
+        const lastBatch = this.history[this.history.length - 1];
+        this.history = this.history.slice(0, -1);
+        this.redoStack = [...this.redoStack, lastBatch];
+        return lastBatch;
+    }
+    /**
+     * Pop the most recent redo entry.
+     * Returns the batch of events (in original order) to be re-applied by the caller,
+     * or null if there is nothing to redo.
+     */
+    redo() {
+        if (this.redoStack.length === 0)
+            return null;
+        const nextBatch = this.redoStack[this.redoStack.length - 1];
+        this.redoStack = this.redoStack.slice(0, -1);
+        this.history = [...this.history, nextBatch];
+        return nextBatch;
+    }
+    /**
+     * Clear all history and redo state.
+     * Does not affect any open batch — call endBatch() first if needed.
+     */
+    clear() {
+        this.history = [];
+        this.redoStack = [];
+        // Intentionally leaves this.batch untouched. If a batch is open,
+        // subsequent records will still accumulate until endBatch() is called.
+        // Callers that want to abort an open batch should call endBatch() first.
+    }
+}

package/dist/types/utils/clipboardHelpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure clipboard helpers shared across React, Vue, Angular, and JS.
+ * No framework dependencies — operates on plain values and produces strings.
+ */
+import type { IColumnDef } from '../types/columnTypes';
+import type { ISelectionRange } from '../types/dataGridTypes';
+/**
+ * Format a single cell value for inclusion in a TSV clipboard string.
+ * Strips tabs and newlines so they don't corrupt the TSV structure.
+ *
+ * @param raw         Raw cell value (from getCellValue).
+ * @param formatted   Formatted value (from valueFormatter, if present).
+ * @returns TSV-safe string representation of the cell.
+ */
+export declare function formatCellValueForTsv(raw: unknown, formatted: unknown): string;
+/**
+ * Serialize a rectangular cell range to a TSV (tab-separated values) string
+ * suitable for writing to the clipboard.
+ *
+ * @param items       Flat array of all row data objects.
+ * @param visibleCols Visible column definitions.
+ * @param range       The selection range to serialize (will be normalized).
+ * @returns TSV string with rows separated by \\r\\n and columns by \\t.
+ */
+export declare function formatSelectionAsTsv<T>(items: T[], visibleCols: IColumnDef<T>[], range: ISelectionRange): string;
+/**
+ * Parse a TSV clipboard string into a 2D array of cell strings.
+ * Handles both \\r\\n and \\n line endings. Ignores trailing empty lines.
+ *
+ * @param text  Raw clipboard text (TSV format).
+ * @returns 2D array: rows of cells. Empty if text is blank.
+ */
+export declare function parseTsvClipboard(text: string): string[][];

package/dist/types/utils/index.d.ts

@@ -29,3 +29,7 @@ export type { OverlayRect } from './dom';
 export { computeNextSortState } from './sortHelpers';
 export type { ISortState } from './sortHelpers';
 export { measureColumnContentWidth, AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX } from './columnAutosize';
+export { findCtrlArrowTarget, computeTabNavigation } from './keyboardNavigation';
+export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed } from './selectionHelpers';
+export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, } from './clipboardHelpers';
+export { UndoRedoStack } from './undoRedoStack';

package/dist/types/utils/keyboardNavigation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure keyboard navigation helpers shared across React, Vue, Angular, and JS.
+ * No framework dependencies — takes plain values, returns plain values.
+ */
+/**
+ * Excel-style Ctrl+Arrow: find the target position along a 1D axis.
+ * - Non-empty current + non-empty next → scan through non-empties, stop at last before empty/edge.
+ * - Otherwise → skip empties, land on next non-empty or edge.
+ *
+ * @param pos   Current position (row or column index).
+ * @param edge  The boundary position (0 for backward, max for forward).
+ * @param step  Direction: +1 (forward) or -1 (backward).
+ * @param isEmpty  Predicate: returns true if the cell at this index is empty.
+ * @returns     The target position after the jump.
+ */
+export declare function findCtrlArrowTarget(pos: number, edge: number, step: number, isEmpty: (i: number) => boolean): number;
+/**
+ * Compute the new Tab navigation position given the current position and direction.
+ *
+ * @param rowIndex      Current row index.
+ * @param columnIndex   Current absolute column index (includes checkbox offset).
+ * @param maxRowIndex   Maximum row index (items.length - 1).
+ * @param maxColIndex   Maximum absolute column index.
+ * @param colOffset     Number of non-data leading columns (checkbox column offset).
+ * @param shiftKey      True if Shift is held (backward tab).
+ * @returns New { rowIndex, columnIndex } after tab.
+ */
+export declare function computeTabNavigation(rowIndex: number, columnIndex: number, maxRowIndex: number, maxColIndex: number, colOffset: number, shiftKey: boolean): {
+    rowIndex: number;
+    columnIndex: number;
+};

package/dist/types/utils/selectionHelpers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure selection helpers shared across React, Vue, Angular, and JS.
+ * No framework dependencies — operates only on plain ISelectionRange values.
+ */
+import type { ISelectionRange } from '../types/dataGridTypes';
+/**
+ * Compare two selection ranges by value (deep equality).
+ * Returns true if both ranges are equal, including when both are null.
+ */
+export declare function rangesEqual(a: ISelectionRange | null, b: ISelectionRange | null): boolean;
+/**
+ * Clamp a selection range to the grid bounds (0-based, inclusive).
+ *
+ * @param range         The selection range to clamp.
+ * @param maxRow        Maximum valid row index (items.length - 1).
+ * @param maxCol        Maximum valid column index (visibleCols.length - 1).
+ * @returns The clamped range, or null if the grid is empty.
+ */
+export declare function clampSelectionToBounds(range: ISelectionRange, maxRow: number, maxCol: number): ISelectionRange | null;
+/**
+ * Auto-scroll speed: proportional to how far past the scroll edge the pointer is.
+ * Used by drag-selection auto-scroll in both React and Vue.
+ *
+ * @param distance  Distance past the edge threshold (pixels).
+ * @param edgePx    Scroll edge threshold in pixels (default: 40).
+ * @param minSpeed  Minimum scroll speed (default: 2).
+ * @param maxSpeed  Maximum scroll speed (default: 20).
+ * @returns Scroll speed in pixels per interval tick.
+ */
+export declare function computeAutoScrollSpeed(distance: number, edgePx?: number, minSpeed?: number, maxSpeed?: number): number;

package/dist/types/utils/undoRedoStack.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Pure undo/redo stack data structure shared across React, Vue, Angular, and JS.
+ * No framework dependencies — all state is plain arrays.
+ *
+ * Usage:
+ *   const stack = new UndoRedoStack<MyEvent>(100);
+ *   stack.push([event]);        // single event
+ *   stack.beginBatch();
+ *   stack.push([event1]);
+ *   stack.push([event2]);
+ *   stack.endBatch();           // event1 + event2 are one undo step
+ *   const batch = stack.undo(); // returns the batch to reverse
+ *   const batch = stack.redo(); // returns the batch to re-apply
+ */
+export declare class UndoRedoStack<T> {
+    private history;
+    private redoStack;
+    private batch;
+    readonly maxDepth: number;
+    constructor(maxDepth?: number);
+    /** Whether there are undo steps available. */
+    get canUndo(): boolean;
+    /** Whether there are redo steps available. */
+    get canRedo(): boolean;
+    /** Number of history entries. */
+    get historyLength(): number;
+    /** Number of redo entries. */
+    get redoLength(): number;
+    /** Whether a batch is currently open. */
+    get isBatching(): boolean;
+    /**
+     * Record a group of events as a single undoable step.
+     * If a batch is open, accumulates into the batch instead.
+     * Clears the redo stack on any new entry.
+     */
+    push(events: T[]): void;
+    /**
+     * Record a single event as a step (shorthand for push([event])).
+     * If a batch is open, accumulates into the batch instead.
+     */
+    record(event: T): void;
+    /**
+     * Start a batch — subsequent record/push calls accumulate into one undo step.
+     * Has no effect if a batch is already open.
+     */
+    beginBatch(): void;
+    /**
+     * End a batch — commits all accumulated events as one undo step.
+     * Has no effect if no batch is open or if the batch is empty.
+     */
+    endBatch(): void;
+    /**
+     * Pop the most recent history entry for undo.
+     * Returns the batch of events (in original order) to be reversed by the caller,
+     * or null if there is nothing to undo.
+     *
+     * The caller is responsible for applying the events in reverse order.
+     */
+    undo(): T[] | null;
+    /**
+     * Pop the most recent redo entry.
+     * Returns the batch of events (in original order) to be re-applied by the caller,
+     * or null if there is nothing to redo.
+     */
+    redo(): T[] | null;
+    /**
+     * Clear all history and redo state.
+     * Does not affect any open batch — call endBatch() first if needed.
+     */
+    clear(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "2.0.14",
+  "version": "2.0.16",
   "description": "OGrid core – framework-agnostic types, algorithms, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",