@alaarab/ogrid-core 2.0.22 → 2.1.0

package/dist/esm/constants/index.js

@@ -1,3 +1,3 @@
-export * from './layout';
-export * from './timing';
-export * from './zIndex';
+export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './layout';
+export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './timing';
+export { Z_INDEX } from './zIndex';

package/dist/esm/constants/timing.js

@@ -2,9 +2,9 @@
  * Timing constants used across OGrid.
  * Centralizes magic numbers for consistency and easier tuning.
  */
-/** Debounce delay for people/user search inputs (milliseconds) */
-export const PEOPLE_SEARCH_DEBOUNCE_MS = 300;
 /** Default debounce delay for generic inputs (milliseconds) */
 export const DEFAULT_DEBOUNCE_MS = 300;
+/** Debounce delay for people/user search inputs (milliseconds) */
+export const PEOPLE_SEARCH_DEBOUNCE_MS = DEFAULT_DEBOUNCE_MS;
 /** Sidebar panel transition duration (milliseconds) */
 export const SIDEBAR_TRANSITION_MS = 300;

package/dist/esm/index.js

@@ -1,10 +1,54 @@
-// Types
-export * from './types';
-// Utils
-export * from './utils';
-// Constants
-export * from './constants';
-// Explicit constant exports for better test resolution
-export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './constants/layout';
-export { PEOPLE_SEARCH_DEBOUNCE_MS, DEFAULT_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './constants/timing';
-export { Z_INDEX } from './constants/zIndex';
+export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './types';
+// Utils — exportToCsv
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';
+// Utils — cellValue, columnUtils
+export { getCellValue } from './utils';
+export { flattenColumns, buildHeaderRows } from './utils';
+// Utils — ogridHelpers
+export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './utils';
+// Utils — statusBarHelpers, dataGridStatusBar
+export { getStatusBarParts } from './utils';
+export { getDataGridStatusBarConfig } from './utils';
+// Utils — paginationHelpers
+export { getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, } from './utils';
+// Utils — gridContextMenuHelpers
+export { GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut, } from './utils';
+// Utils — valueParsers
+export { parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, } from './utils';
+// Utils — aggregationUtils
+export { computeAggregations } from './utils';
+// Utils — clientSideData
+export { processClientSideData } from './utils';
+// Utils — gridRowComparator
+export { areGridRowPropsEqual, isRowInRange } from './utils';
+// Utils — columnReorder
+export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './utils';
+// Utils — virtualScroll
+export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './utils';
+// Utils — dataGridViewModel
+export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './utils';
+// Utils — debounce, dom
+export { debounce } from './utils';
+export { measureRange, injectGlobalStyles } from './utils';
+// Utils — sortHelpers
+export { computeNextSortState } from './utils';
+// Utils — columnAutosize
+export { measureColumnContentWidth, AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX } from './utils';
+// Utils — keyboardNavigation
+export { findCtrlArrowTarget, computeTabNavigation, computeArrowNavigation, applyCellDeletion } from './utils';
+// Utils — selectionHelpers
+export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, applyRangeRowSelection, computeRowSelectionState } from './utils';
+// Utils — clipboardHelpers
+export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, } from './utils';
+// Utils — fillHelpers
+export { applyFillValues } from './utils';
+// Utils — undoRedoStack
+export { UndoRedoStack } from './utils';
+// Utils — validation
+export { validateColumns, validateRowIds } from './utils';
+// Constants — layout
+export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './constants';
+// Constants — timing
+export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './constants';
+// Constants — zIndex
+export { Z_INDEX } from './constants';

package/dist/esm/utils/cellValue.js

@@ -1,5 +1,11 @@
 /**
  * Get the cell value for a row/column, using valueGetter when defined otherwise item[columnId].
+ *
+ * @param item - The row data object.
+ * @param col  - Column definition. If `valueGetter` is defined it takes priority;
+ *               otherwise the value is read via `item[col.columnId]`.
+ *               Assumes `columnId` is a valid key on the item when no `valueGetter` is provided.
+ * @returns The raw cell value (`unknown`). May be `undefined` if the key does not exist on the item.
  */
 export function getCellValue(item, col) {
     if (col.valueGetter)

package/dist/esm/utils/clientSideData.js

@@ -36,6 +36,9 @@ export function processClientSideData(data, columns, filters, sortBy, sortDirect
             continue;
         switch (val.type) {
             case 'multiSelect':
+                // NOTE: Cell values are coerced to string via String() for set membership checks.
+                // Object-typed column values will produce "[object Object]" — use valueGetter or
+                // valueFormatter on the column def to ensure meaningful string representation.
                 if (val.value.length > 0) {
                     const allowedSet = new Set(val.value);
                     predicates.push((r) => allowedSet.has(String(getCellValue(r, col))));
@@ -76,7 +79,8 @@ export function processClientSideData(data, columns, filters, sortBy, sortDirect
             }
         }
     }
-    const rows = predicates.length > 0
+    const filtered = predicates.length > 0;
+    const rows = filtered
         ? data.filter((row) => {
             for (let i = 0; i < predicates.length; i++) {
                 if (!predicates[i](row))
@@ -84,18 +88,23 @@ export function processClientSideData(data, columns, filters, sortBy, sortDirect
             }
             return true;
         })
-        : data.slice();
+        : data;
     // --- Sorting ---
     if (sortBy) {
+        // Copy before sorting if we didn't filter (filter already creates a new array).
+        // This avoids mutating the caller's original data array.
+        const sortable = filtered ? rows : rows.slice();
         const sortCol = columnMap.get(sortBy);
         const compare = sortCol?.compare;
         const dir = sortDirection === 'asc' ? 1 : -1;
         const isDateSort = sortCol?.type === 'date';
-        // For date columns, pre-compute timestamps to avoid repeated new Date() in O(n log n) comparisons
+        // For date columns, pre-compute timestamps to avoid repeated new Date() in O(n log n) comparisons.
+        // NOTE: The timestamp cache is scoped to this single sort invocation. It is rebuilt on every call,
+        // so mutating row objects between calls is safe — stale timestamps cannot persist across invocations.
         if (isDateSort && !compare) {
             const timestampCache = new Map();
-            for (let i = 0; i < rows.length; i++) {
-                const row = rows[i];
+            for (let i = 0; i < sortable.length; i++) {
+                const row = sortable[i];
                 const val = sortCol ? getCellValue(row, sortCol) : row[sortBy];
                 if (val == null) {
                     timestampCache.set(row, NaN);
@@ -105,9 +114,9 @@ export function processClientSideData(data, columns, filters, sortBy, sortDirect
                     timestampCache.set(row, Number.isNaN(t) ? 0 : t);
                 }
             }
-            rows.sort((a, b) => {
-                const at = timestampCache.get(a);
-                const bt = timestampCache.get(b);
+            sortable.sort((a, b) => {
+                const at = timestampCache.get(a) ?? NaN;
+                const bt = timestampCache.get(b) ?? NaN;
                 if (Number.isNaN(at) && Number.isNaN(bt))
                     return 0;
                 if (Number.isNaN(at))
@@ -118,7 +127,7 @@ export function processClientSideData(data, columns, filters, sortBy, sortDirect
             });
         }
         else {
-            rows.sort((a, b) => {
+            sortable.sort((a, b) => {
                 if (compare)
                     return compare(a, b) * dir;
                 const av = sortCol
@@ -140,6 +149,7 @@ export function processClientSideData(data, columns, filters, sortBy, sortDirect
                 return as === bs ? 0 : as > bs ? dir : -dir;
             });
         }
+        return sortable;
     }
     return rows;
 }

package/dist/esm/utils/clipboardHelpers.js

@@ -1,4 +1,5 @@
 import { getCellValue } from './cellValue';
+import { parseValue } from './valueParsers';
 import { normalizeSelectionRange } from '../types';
 /**
  * Format a single cell value for inclusion in a TSV clipboard string.
@@ -12,7 +13,12 @@ export function formatCellValueForTsv(raw, formatted) {
     const val = formatted != null && formatted !== '' ? formatted : raw;
     if (val == null || val === '')
         return '';
-    return String(val).replace(/[\t\n]/g, ' ');
+    try {
+        return String(val).replace(/[\t\n]/g, ' ');
+    }
+    catch {
+        return '[Object]';
+    }
 }
 /**
  * Serialize a rectangular cell range to a TSV (tab-separated values) string
@@ -55,3 +61,82 @@ export function parseTsvClipboard(text) {
     const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
     return lines.map((line) => line.split('\t'));
 }
+/**
+ * Apply parsed clipboard rows to the grid starting at anchor position.
+ * For each cell in the parsed rows, validates editability, parses the value,
+ * and produces a cell value changed event.
+ *
+ * @param parsedRows   2D array of string values (from parseTsvClipboard).
+ * @param anchorRow    Target starting row index.
+ * @param anchorCol    Target starting column index (data column, not absolute).
+ * @param items        Array of all row data objects.
+ * @param visibleCols  Visible column definitions.
+ * @returns Array of cell value changed events to apply.
+ */
+export function applyPastedValues(parsedRows, anchorRow, anchorCol, items, visibleCols) {
+    const events = [];
+    for (let r = 0; r < parsedRows.length; r++) {
+        const cells = parsedRows[r];
+        for (let c = 0; c < cells.length; c++) {
+            const targetRow = anchorRow + r;
+            const targetCol = anchorCol + c;
+            if (targetRow >= items.length || targetCol >= visibleCols.length)
+                continue;
+            const item = items[targetRow];
+            const col = visibleCols[targetCol];
+            const colEditable = col.editable === true ||
+                (typeof col.editable === 'function' && col.editable(item));
+            if (!colEditable)
+                continue;
+            const rawValue = cells[c] ?? '';
+            const oldValue = getCellValue(item, col);
+            const result = parseValue(rawValue, oldValue, item, col);
+            if (!result.valid)
+                continue;
+            events.push({
+                item,
+                columnId: col.columnId,
+                oldValue,
+                newValue: result.value,
+                rowIndex: targetRow,
+            });
+        }
+    }
+    return events;
+}
+/**
+ * Clear cells in a cut range by setting each editable cell to an empty-string-parsed value.
+ * Used after pasting cut content to clear the original cells.
+ *
+ * @param cutRange     The normalized range of cells to clear.
+ * @param items        Array of all row data objects.
+ * @param visibleCols  Visible column definitions.
+ * @returns Array of cell value changed events to apply.
+ */
+export function applyCutClear(cutRange, items, visibleCols) {
+    const events = [];
+    for (let r = cutRange.startRow; r <= cutRange.endRow; r++) {
+        for (let c = cutRange.startCol; c <= cutRange.endCol; c++) {
+            if (r >= items.length || c >= visibleCols.length)
+                continue;
+            const item = items[r];
+            const col = visibleCols[c];
+            const colEditable = col.editable === true ||
+                (typeof col.editable === 'function' && col.editable(item));
+            if (!colEditable)
+                continue;
+            const oldValue = getCellValue(item, col);
+            const result = parseValue('', oldValue, item, col);
+            if (!result.valid)
+                continue;
+            events.push({
+                item,
+                columnId: col.columnId,
+                oldValue,
+                newValue: result.value,
+                rowIndex: r,
+            });
+        }
+    }
+    return events;
+}

package/dist/esm/utils/columnReorder.js

@@ -28,15 +28,12 @@ export function reorderColumnArray(order, columnId, targetIndex) {
  * finds the midpoint of each header cell, and determines insertion side.
  * Respects pinning zones: a left-pinned column can only drop among left-pinned, etc.
  *
- * @param mouseX - Current mouse X position (client coordinates)
- * @param columnOrder - Current column display order (array of column ids)
- * @param draggedColumnId - The column being dragged
- * @param draggedPinState - Pin state of the dragged column
- * @param tableElement - The table (or grid container) DOM element to query headers from
- * @param pinnedColumns - Pinned column configuration
+ * @param params - Options object containing mouseX, columnOrder, draggedColumnId,
+ *   draggedPinState, tableElement, and optional pinnedColumns.
  * @returns Drop target with insertion index and indicator X, or null if no valid target.
  */
-export function calculateDropTarget(mouseX, columnOrder, draggedColumnId, draggedPinState, tableElement, pinnedColumns) {
+export function calculateDropTarget(params) {
+    const { mouseX, columnOrder, draggedColumnId, draggedPinState, tableElement, pinnedColumns } = params;
     const headerCells = tableElement.querySelectorAll('[data-column-id]');
     if (headerCells.length === 0)
         return null;

package/dist/esm/utils/dataGridViewModel.js

@@ -5,11 +5,12 @@
  */
 import { getCellValue } from './cellValue';
 import { isInSelectionRange } from '../types/dataGridTypes';
+import { isFilterConfig } from './ogridHelpers';
 /**
  * Returns ColumnHeaderFilter props from column def and grid filter/sort state.
  */
 export function getHeaderFilterConfig(col, input) {
-    const filterable = col.filterable && typeof col.filterable === 'object' ? col.filterable : null;
+    const filterable = isFilterConfig(col.filterable) ? col.filterable : null;
     const filterType = (filterable?.type ?? 'none');
     const filterField = filterable?.filterField ?? col.columnId;
     const sortable = col.sortable !== false;
@@ -93,9 +94,10 @@ export function getCellRenderDescriptor(item, col, rowIndex, colIdx, input) {
         colIdx === input.selectionRange.endCol;
     const isPinned = col.pinned != null;
     const pinnedSide = col.pinned ?? undefined;
+    // Compute cell value once — used in editing and display branches
+    const cellValue = getCellValue(item, col);
     let mode = 'display';
     let editorType;
-    let value;
     if (isEditing && canEditInline) {
         mode = 'editing-inline';
         if (col.cellEditor === 'text' ||
@@ -114,19 +116,14 @@ export function getCellRenderDescriptor(item, col, rowIndex, colIdx, input) {
         else {
             editorType = 'text';
         }
-        value = getCellValue(item, col);
     }
     else if (isEditing && canEditPopup && typeof col.cellEditor === 'function') {
         mode = 'editing-popover';
-        value = getCellValue(item, col);
-    }
-    else {
-        value = getCellValue(item, col);
     }
     return {
         mode,
         editorType,
-        value,
+        value: cellValue,
         isActive,
         isInRange,
         isInCutRange,
@@ -138,7 +135,7 @@ export function getCellRenderDescriptor(item, col, rowIndex, colIdx, input) {
         globalColIndex,
         rowId,
         rowIndex,
-        displayValue: value,
+        displayValue: cellValue,
     };
 }
 /**

package/dist/esm/utils/exportToCsv.js

@@ -20,20 +20,31 @@ export function exportToCsv(items, columns, getValue, filename) {
     const csv = [header, ...rows].join('\n');
     triggerCsvDownload(csv, filename ?? `export_${new Date().toISOString().slice(0, 10)}.csv`);
 }
+/**
+ * Triggers a browser CSV file download.
+ *
+ * NOTE: This function uses DOM APIs (document.createElement, document.body) and therefore
+ * requires a browser environment. It is intentionally kept in the core package because all
+ * framework packages (React, Angular, Vue, JS) need CSV export, and duplicating it would be
+ * worse than the DOM dependency. In server-side rendering (SSR) contexts, call exportToCsv
+ * only from browser-side code (e.g. event handlers), not during server rendering.
+ */
 export function triggerCsvDownload(csvContent, filename) {
     const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
-    const link = document.createElement('a');
     const url = URL.createObjectURL(blob);
-    link.setAttribute('href', url);
-    link.setAttribute('download', filename);
-    link.style.visibility = 'hidden';
-    document.body.appendChild(link);
-    link.click();
+    const link = document.createElement('a');
     try {
-        document.body.removeChild(link);
+        link.setAttribute('href', url);
+        link.setAttribute('download', filename);
+        link.style.visibility = 'hidden';
+        document.body.appendChild(link);
+        link.click();
     }
-    catch {
-        // Ignore if removeChild fails (e.g. link was not actually appended in test env)
+    finally {
+        try {
+            document.body.removeChild(link);
+        }
+        catch { /* noop */ }
+        URL.revokeObjectURL(url);
     }
-    URL.revokeObjectURL(url);
 }

package/dist/esm/utils/fillHelpers.js

@@ -0,0 +1,47 @@
+import { getCellValue } from './cellValue';
+import { parseValue } from './valueParsers';
+/**
+ * Apply fill values from a source cell across a normalized selection range.
+ * Copies the value from the start cell of the range to every other editable cell.
+ *
+ * @param range           The normalized fill range (startRow/startCol is the source).
+ * @param sourceRow       The original source row index (skipped during fill).
+ * @param sourceCol       The original source col index (skipped during fill).
+ * @param items           Array of all row data objects.
+ * @param visibleCols     Visible column definitions.
+ * @returns Array of cell value changed events to apply. Empty if source cell is out of bounds.
+ */
+export function applyFillValues(range, sourceRow, sourceCol, items, visibleCols) {
+    const events = [];
+    const startItem = items[range.startRow];
+    const startColDef = visibleCols[range.startCol];
+    if (!startItem || !startColDef)
+        return events;
+    const startValue = getCellValue(startItem, startColDef);
+    for (let row = range.startRow; row <= range.endRow; row++) {
+        for (let col = range.startCol; col <= range.endCol; col++) {
+            if (row === sourceRow && col === sourceCol)
+                continue;
+            if (row >= items.length || col >= visibleCols.length)
+                continue;
+            const item = items[row];
+            const colDef = visibleCols[col];
+            const colEditable = colDef.editable === true ||
+                (typeof colDef.editable === 'function' && colDef.editable(item));
+            if (!colEditable)
+                continue;
+            const oldValue = getCellValue(item, colDef);
+            const result = parseValue(startValue, oldValue, item, colDef);
+            if (!result.valid)
+                continue;
+            events.push({
+                item,
+                columnId: colDef.columnId,
+                oldValue,
+                newValue: result.value,
+                rowIndex: row,
+            });
+        }
+    }
+    return events;
+}

package/dist/esm/utils/gridRowComparator.js

@@ -46,7 +46,7 @@ export function areGridRowPropsEqual(prev, next) {
     const nextActive = next.activeCell?.rowIndex === ri;
     if (prevActive !== nextActive)
         return false;
-    if (prevActive && nextActive && prev.activeCell.columnIndex !== next.activeCell.columnIndex)
+    if (prevActive && nextActive && prev.activeCell?.columnIndex !== next.activeCell?.columnIndex)
         return false;
     // Selection range touches this row?
     const prevInSel = isRowInRange(prev.selectionRange, ri);
@@ -54,8 +54,8 @@ export function areGridRowPropsEqual(prev, next) {
     if (prevInSel !== nextInSel)
         return false;
     if (prevInSel && nextInSel) {
-        if (prev.selectionRange.startCol !== next.selectionRange.startCol ||
-            prev.selectionRange.endCol !== next.selectionRange.endCol)
+        if (prev.selectionRange?.startCol !== next.selectionRange?.startCol ||
+            prev.selectionRange?.endCol !== next.selectionRange?.endCol)
             return false;
     }
     // Fill handle (selection end row) + isDragging

package/dist/esm/utils/index.js

@@ -1,7 +1,7 @@
 export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './exportToCsv';
 export { getCellValue } from './cellValue';
 export { flattenColumns, buildHeaderRows } from './columnUtils';
-export { getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './ogridHelpers';
+export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './ogridHelpers';
 export { getStatusBarParts } from './statusBarHelpers';
 export { getDataGridStatusBarConfig } from './dataGridStatusBar';
 export { getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, } from './paginationHelpers';
@@ -17,7 +17,9 @@ 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 { findCtrlArrowTarget, computeTabNavigation, computeArrowNavigation, applyCellDeletion } from './keyboardNavigation';
+export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, applyRangeRowSelection, computeRowSelectionState } from './selectionHelpers';
+export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, } from './clipboardHelpers';
+export { applyFillValues } from './fillHelpers';
 export { UndoRedoStack } from './undoRedoStack';
+export { validateColumns, validateRowIds } from './validation';

package/dist/esm/utils/keyboardNavigation.js

@@ -1,7 +1,6 @@
-/**
- * Pure keyboard navigation helpers shared across React, Vue, Angular, and JS.
- * No framework dependencies — takes plain values, returns plain values.
- */
+import { normalizeSelectionRange } from '../types/dataGridTypes';
+import { getCellValue } from './cellValue';
+import { parseValue } from './valueParsers';
 /**
  * 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.
@@ -41,11 +40,11 @@ export function findCtrlArrowTarget(pos, edge, step, isEmpty) {
  *
  * @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 maxRowIndex   Maximum row index (items.length - 1). Must be >= 0.
+ * @param maxColIndex   Maximum absolute column index. Must be >= 0.
  * @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.
+ * @returns New { rowIndex, columnIndex } after tab. Caller must ensure maxRowIndex and maxColIndex are non-negative.
  */
 export function computeTabNavigation(rowIndex, columnIndex, maxRowIndex, maxColIndex, colOffset, shiftKey) {
     let newRow = rowIndex;
@@ -70,3 +69,113 @@ export function computeTabNavigation(rowIndex, columnIndex, maxRowIndex, maxColI
     }
     return { rowIndex: newRow, columnIndex: newCol };
 }
+/**
+ * Computes the next active cell position and selection range for a single arrow key press.
+ * Handles Ctrl+Arrow (jump to edge), Shift+Arrow (extend selection), and plain Arrow (move).
+ *
+ * Pure function — no framework dependencies.
+ *
+ * @param ctx  Arrow navigation context with current position, direction, modifiers, and grid bounds.
+ * @returns The new row/column indices and selection range.
+ */
+export function computeArrowNavigation(ctx) {
+    const { direction, rowIndex, columnIndex, dataColIndex, colOffset, maxRowIndex, maxColIndex, visibleColCount, isCtrl, isShift, selectionRange, isEmptyAt, } = ctx;
+    let newRowIndex = rowIndex;
+    let newColumnIndex = columnIndex;
+    if (direction === 'ArrowDown') {
+        newRowIndex = isCtrl
+            ? findCtrlArrowTarget(rowIndex, maxRowIndex, 1, (r) => isEmptyAt(r, Math.max(0, dataColIndex)))
+            : Math.min(rowIndex + 1, maxRowIndex);
+    }
+    else if (direction === 'ArrowUp') {
+        newRowIndex = isCtrl
+            ? findCtrlArrowTarget(rowIndex, 0, -1, (r) => isEmptyAt(r, Math.max(0, dataColIndex)))
+            : Math.max(rowIndex - 1, 0);
+    }
+    else if (direction === 'ArrowRight') {
+        if (isCtrl && dataColIndex >= 0) {
+            newColumnIndex = findCtrlArrowTarget(dataColIndex, visibleColCount - 1, 1, (c) => isEmptyAt(rowIndex, c)) + colOffset;
+        }
+        else {
+            newColumnIndex = Math.min(columnIndex + 1, maxColIndex);
+        }
+    }
+    else { // ArrowLeft
+        if (isCtrl && dataColIndex >= 0) {
+            newColumnIndex = findCtrlArrowTarget(dataColIndex, 0, -1, (c) => isEmptyAt(rowIndex, c)) + colOffset;
+        }
+        else {
+            newColumnIndex = Math.max(columnIndex - 1, colOffset);
+        }
+    }
+    const newDataColIndex = newColumnIndex - colOffset;
+    const isVertical = direction === 'ArrowDown' || direction === 'ArrowUp';
+    let newRange;
+    if (isShift) {
+        if (isVertical) {
+            newRange = normalizeSelectionRange({
+                startRow: selectionRange?.startRow ?? rowIndex,
+                startCol: selectionRange?.startCol ?? dataColIndex,
+                endRow: newRowIndex,
+                endCol: selectionRange?.endCol ?? dataColIndex,
+            });
+        }
+        else {
+            newRange = normalizeSelectionRange({
+                startRow: selectionRange?.startRow ?? rowIndex,
+                startCol: selectionRange?.startCol ?? dataColIndex,
+                endRow: selectionRange?.endRow ?? rowIndex,
+                endCol: newDataColIndex,
+            });
+        }
+    }
+    else {
+        newRange = {
+            startRow: newRowIndex,
+            startCol: newDataColIndex,
+            endRow: newRowIndex,
+            endCol: newDataColIndex,
+        };
+    }
+    return { newRowIndex, newColumnIndex, newDataColIndex, newRange };
+}
+/**
+ * Apply cell deletion (Delete/Backspace key) across a selection range.
+ * For each editable cell in the range, parses an empty string as the new value
+ * and emits a cell value changed event.
+ *
+ * Pure function — no framework dependencies.
+ *
+ * @param range       The normalized selection range to clear.
+ * @param items       Array of all row data objects.
+ * @param visibleCols Visible column definitions.
+ * @returns Array of cell value changed events to apply.
+ */
+export function applyCellDeletion(range, items, visibleCols) {
+    const norm = normalizeSelectionRange(range);
+    const events = [];
+    for (let r = norm.startRow; r <= norm.endRow; r++) {
+        for (let c = norm.startCol; c <= norm.endCol; c++) {
+            if (r >= items.length || c >= visibleCols.length)
+                continue;
+            const item = items[r];
+            const col = visibleCols[c];
+            const colEditable = col.editable === true ||
+                (typeof col.editable === 'function' && col.editable(item));
+            if (!colEditable)
+                continue;
+            const oldValue = getCellValue(item, col);
+            const result = parseValue('', oldValue, item, col);
+            if (!result.valid)
+                continue;
+            events.push({
+                item,
+                columnId: col.columnId,
+                oldValue,
+                newValue: result.value,
+                rowIndex: r,
+            });
+        }
+    }
+    return events;
+}