@alaarab/ogrid-core 2.0.22 → 2.1.0

package/dist/esm/utils/ogridHelpers.js

@@ -1,24 +1,25 @@
 import { getCellValue } from './cellValue';
+/** Type guard: returns true if val is an IColumnFilterDef (an object with a filter type). */
+export function isFilterConfig(val) {
+    return val != null && typeof val === 'object' && 'type' in val;
+}
 /** Resolve the filter field key for a column (filterField or columnId). */
 export function getFilterField(col) {
-    const f = col.filterable && typeof col.filterable === 'object' ? col.filterable : null;
+    const f = isFilterConfig(col.filterable) ? col.filterable : null;
     return (f?.filterField ?? col.columnId);
 }
 /** Merge a single filter change into a full IFilters object. Strips empty values automatically. */
 export function mergeFilter(prev, key, value) {
-    const next = { ...prev };
     const isEmpty = value === undefined ||
         (value.type === 'text' && value.value.trim() === '') ||
         (value.type === 'multiSelect' && value.value.length === 0) ||
         (value.type === 'date' && !value.value.from && !value.value.to) ||
         (value.type === 'people' && !value.value);
     if (isEmpty) {
-        delete next[key];
-    }
-    else {
-        next[key] = value;
+        const { [key]: _, ...rest } = prev;
+        return rest;
     }
-    return next;
+    return { ...prev, [key]: value };
 }
 /** Derive filter options for multiSelect columns from client-side data. */
 export function deriveFilterOptionsFromData(items, columns) {
@@ -26,7 +27,7 @@ export function deriveFilterOptionsFromData(items, columns) {
     const filterCols = [];
     for (let i = 0; i < columns.length; i++) {
         const col = columns[i];
-        const f = col.filterable && typeof col.filterable === 'object' ? col.filterable : null;
+        const f = isFilterConfig(col.filterable) ? col.filterable : null;
         if (f?.type === 'multiSelect') {
             filterCols.push({ col, field: getFilterField(col) });
         }
@@ -42,23 +43,25 @@ export function deriveFilterOptionsFromData(items, columns) {
         const item = items[i];
         for (let j = 0; j < filterCols.length; j++) {
             const v = getCellValue(item, filterCols[j].col);
-            if (v != null && v !== '')
-                valueSets.get(filterCols[j].field).add(String(v));
+            const set = valueSets.get(filterCols[j].field);
+            if (v != null && v !== '' && set)
+                set.add(String(v));
         }
     }
     const out = {};
     for (let i = 0; i < filterCols.length; i++) {
-        out[filterCols[i].field] = Array.from(valueSets.get(filterCols[i].field)).sort();
+        const set = valueSets.get(filterCols[i].field);
+        out[filterCols[i].field] = set ? Array.from(set).sort() : [];
     }
     return out;
 }
 /** Get list of filter fields that use multiSelect (for useFilterOptions). */
 export function getMultiSelectFilterFields(columns) {
     const fields = [];
-    columns.forEach((col) => {
-        const f = col.filterable && typeof col.filterable === 'object' ? col.filterable : null;
+    for (const col of columns) {
+        const f = isFilterConfig(col.filterable) ? col.filterable : null;
         if (f?.type === 'multiSelect')
             fields.push(getFilterField(col));
-    });
+    }
     return fields;
 }

package/dist/esm/utils/selectionHelpers.js

@@ -1,3 +1,7 @@
+// Re-export normalizeSelectionRange from its canonical location for convenience.
+// The original definition lives in dataGridTypes.ts and is preserved there
+// to avoid breaking existing imports.
+export { normalizeSelectionRange } from '../types/dataGridTypes';
 /**
  * Compare two selection ranges by value (deep equality).
  * Returns true if both ranges are equal, including when both are null.
@@ -44,3 +48,47 @@ export function computeAutoScrollSpeed(distance, edgePx = 40, minSpeed = 2, maxS
     const t = Math.min(distance / edgePx, 1);
     return minSpeed + t * (maxSpeed - minSpeed);
 }
+/**
+ * Apply a shift-click range selection to a set of row IDs.
+ * Used by React `useRowSelection`, Vue `useRowSelection`, and JS `RowSelectionState`.
+ *
+ * @param start       Start index of the range (inclusive).
+ * @param end         End index of the range (inclusive).
+ * @param checked     Whether to add (true) or remove (false) the rows.
+ * @param items       Array of all row data objects.
+ * @param getRowId    Function to extract a unique row ID from an item.
+ * @param currentSelection  Current set of selected row IDs (will be shallow-copied).
+ * @returns A new Set of selected row IDs after applying the range.
+ */
+export function applyRangeRowSelection(start, end, checked, items, getRowId, currentSelection) {
+    const next = new Set(currentSelection);
+    const lo = Math.min(start, end);
+    const hi = Math.max(start, end);
+    for (let i = lo; i <= hi; i++) {
+        if (i < items.length) {
+            const id = getRowId(items[i]);
+            if (checked)
+                next.add(id);
+            else
+                next.delete(id);
+        }
+    }
+    return next;
+}
+/**
+ * Compute the allSelected / someSelected state from a set of selected row IDs.
+ * Used by React `useRowSelection`, Vue `useRowSelection`, and JS `RowSelectionState`.
+ *
+ * @param selectedIds  Current set of selected row IDs.
+ * @param items        Array of all row data objects.
+ * @param getRowId     Function to extract a unique row ID from an item.
+ * @returns An object with `allSelected` and `someSelected` booleans.
+ */
+export function computeRowSelectionState(selectedIds, items, getRowId) {
+    if (selectedIds.size === 0 || items.length === 0) {
+        return { allSelected: false, someSelected: false };
+    }
+    const allSelected = items.every((item) => selectedIds.has(getRowId(item)));
+    const someSelected = !allSelected && selectedIds.size > 0;
+    return { allSelected, someSelected };
+}

package/dist/esm/utils/undoRedoStack.js

@@ -51,8 +51,12 @@ export class UndoRedoStack {
             this.batch.push(...events);
         }
         else {
-            this.history = [...this.history, events].slice(-this.maxDepth);
-            this.redoStack = [];
+            this.history.push(events);
+            if (this.history.length > this.maxDepth) {
+                this.history.splice(0, this.history.length - this.maxDepth);
+            }
+            // Clear redo stack in-place — avoids allocating a new array on every edit
+            this.redoStack.length = 0;
         }
     }
     /**
@@ -80,8 +84,11 @@ export class UndoRedoStack {
         this.batch = null;
         if (!b || b.length === 0)
             return;
-        this.history = [...this.history, b].slice(-this.maxDepth);
-        this.redoStack = [];
+        this.history.push(b);
+        if (this.history.length > this.maxDepth) {
+            this.history.splice(0, this.history.length - this.maxDepth);
+        }
+        this.redoStack.length = 0;
     }
     /**
      * Pop the most recent history entry for undo.
@@ -91,11 +98,10 @@ export class UndoRedoStack {
      * The caller is responsible for applying the events in reverse order.
      */
     undo() {
-        if (this.history.length === 0)
+        const lastBatch = this.history.pop();
+        if (!lastBatch)
             return null;
-        const lastBatch = this.history[this.history.length - 1];
-        this.history = this.history.slice(0, -1);
-        this.redoStack = [...this.redoStack, lastBatch];
+        this.redoStack.push(lastBatch);
         return lastBatch;
     }
     /**
@@ -104,11 +110,10 @@ export class UndoRedoStack {
      * or null if there is nothing to redo.
      */
     redo() {
-        if (this.redoStack.length === 0)
+        const nextBatch = this.redoStack.pop();
+        if (!nextBatch)
             return null;
-        const nextBatch = this.redoStack[this.redoStack.length - 1];
-        this.redoStack = this.redoStack.slice(0, -1);
-        this.history = [...this.history, nextBatch];
+        this.history.push(nextBatch);
         return nextBatch;
     }
     /**

package/dist/esm/utils/validation.js

@@ -0,0 +1,43 @@
+/**
+ * Validate column definitions at grid initialization.
+ * Called once (not per render). Warns on empty/missing/duplicate columnIds.
+ */
+export function validateColumns(columns) {
+    if (!Array.isArray(columns) || columns.length === 0) {
+        console.warn('[OGrid] columns prop is empty or not an array');
+        return;
+    }
+    const ids = new Set();
+    for (const col of columns) {
+        if (!col.columnId) {
+            console.warn('[OGrid] Column missing columnId:', col);
+        }
+        if (ids.has(col.columnId)) {
+            console.warn(`[OGrid] Duplicate columnId: "${col.columnId}"`);
+        }
+        ids.add(col.columnId);
+    }
+}
+/**
+ * Validate that getRowId returns unique, non-null values.
+ * Dev-only (skipped in production). Samples the first 100 rows.
+ * Called once on first data render via a hasValidated flag in the caller.
+ */
+export function validateRowIds(items, getRowId) {
+    if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
+        return;
+    const ids = new Set();
+    const limit = Math.min(items.length, 100);
+    for (let i = 0; i < limit; i++) {
+        const id = getRowId(items[i]);
+        if (id == null) {
+            console.warn(`[OGrid] getRowId returned null/undefined for row ${i}`);
+            return;
+        }
+        if (ids.has(id)) {
+            console.warn(`[OGrid] Duplicate row ID "${id}" at index ${i}. getRowId must return unique values.`);
+            return;
+        }
+        ids.add(id);
+    }
+}

package/dist/esm/utils/virtualScroll.js

@@ -9,8 +9,8 @@
  * @returns The visible range with start/end indices and top/bottom spacer offsets
  */
 export function computeVisibleRange(scrollTop, rowHeight, containerHeight, totalRows, overscan = 5) {
-    if (totalRows === 0 || rowHeight <= 0 || containerHeight <= 0) {
-        return { startIndex: 0, endIndex: -1, offsetTop: 0, offsetBottom: 0 };
+    if (totalRows <= 0 || rowHeight <= 0 || containerHeight <= 0) {
+        return { startIndex: 0, endIndex: 0, offsetTop: 0, offsetBottom: 0 };
     }
     const startIndex = Math.max(0, Math.floor(scrollTop / rowHeight) - overscan);
     const endIndex = Math.min(totalRows - 1, Math.ceil((scrollTop + containerHeight) / rowHeight) + overscan);

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

@@ -1,3 +1,4 @@
-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';
+export type { ZIndexKey } from './zIndex';

package/dist/types/constants/timing.d.ts

@@ -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 declare const PEOPLE_SEARCH_DEBOUNCE_MS = 300;
 /** Default debounce delay for generic inputs (milliseconds) */
 export declare const DEFAULT_DEBOUNCE_MS = 300;
+/** Debounce delay for people/user search inputs (milliseconds) */
+export declare const PEOPLE_SEARCH_DEBOUNCE_MS = 300;
 /** Sidebar panel transition duration (milliseconds) */
 export declare const SIDEBAR_TRANSITION_MS = 300;

package/dist/types/index.d.ts

@@ -1,6 +1,45 @@
-export * from './types';
-export * from './utils';
-export * from './constants';
-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 type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, IColumnDef, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } from './types';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './types';
+export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './types';
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';
+export type { CsvColumn } from './utils';
+export { getCellValue } from './utils';
+export { flattenColumns, buildHeaderRows } from './utils';
+export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './utils';
+export { getStatusBarParts } from './utils';
+export { getDataGridStatusBarConfig } from './utils';
+export type { StatusBarPart, StatusBarPartsInput } from './utils';
+export { getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, } from './utils';
+export type { PaginationViewModel } from './utils';
+export { GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut, } from './utils';
+export type { GridContextMenuItem, IColumnHeaderMenuItem, GridContextMenuHandlerProps, ColumnHeaderMenuInput, ColumnHeaderMenuHandlers, } from './utils';
+export { parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, } from './utils';
+export type { ParseValueResult } from './utils';
+export { computeAggregations } from './utils';
+export type { AggregationResult } from './utils';
+export { processClientSideData } from './utils';
+export { areGridRowPropsEqual, isRowInRange } from './utils';
+export type { GridRowComparatorProps } from './utils';
+export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './utils';
+export type { ColumnPinState, IDropTarget, ICalculateDropTargetParams } from './utils';
+export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './utils';
+export type { IVisibleRange } from './utils';
+export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './utils';
+export type { HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, } from './utils';
+export { debounce } from './utils';
+export { measureRange, injectGlobalStyles } from './utils';
+export type { OverlayRect } from './utils';
+export { computeNextSortState } from './utils';
+export type { ISortState } from './utils';
+export { measureColumnContentWidth, AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX } from './utils';
+export { findCtrlArrowTarget, computeTabNavigation, computeArrowNavigation, applyCellDeletion } from './utils';
+export type { ArrowNavigationContext, ArrowNavigationResult } from './utils';
+export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, applyRangeRowSelection, computeRowSelectionState } from './utils';
+export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, } from './utils';
+export { applyFillValues } from './utils';
+export { UndoRedoStack } from './utils';
+export { validateColumns, validateRowIds } from './utils';
+export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './constants';
+export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './constants';
+export { Z_INDEX } from './constants';
+export type { ZIndexKey } from './constants';

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

@@ -1,5 +1,11 @@
 import type { IColumnDef } from '../types/columnTypes';
 /**
  * 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 declare function getCellValue<T>(item: T, col: IColumnDef<T>): unknown;

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

@@ -2,7 +2,7 @@
  * 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 { IColumnDef, ICellValueChangedEvent } from '../types/columnTypes';
 import type { ISelectionRange } from '../types/dataGridTypes';
 /**
  * Format a single cell value for inclusion in a TSV clipboard string.
@@ -31,3 +31,26 @@ export declare function formatSelectionAsTsv<T>(items: T[], visibleCols: IColumn
  * @returns 2D array: rows of cells. Empty if text is blank.
  */
 export declare function parseTsvClipboard(text: string): string[][];
+/**
+ * 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 declare function applyPastedValues<T>(parsedRows: string[][], anchorRow: number, anchorCol: number, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];
+/**
+ * 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 declare function applyCutClear<T>(cutRange: ISelectionRange, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];

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

@@ -19,6 +19,24 @@ export declare function getPinStateForColumn(columnId: string, pinnedColumns?: {
  * Returns a new array (does not mutate the input).
  */
 export declare function reorderColumnArray(order: string[], columnId: string, targetIndex: number): string[];
+/** Parameters for {@link calculateDropTarget}. */
+export interface ICalculateDropTargetParams {
+    /** Current mouse X position (client coordinates). */
+    mouseX: number;
+    /** Current column display order (array of column ids). */
+    columnOrder: string[];
+    /** The column being dragged. */
+    draggedColumnId: string;
+    /** Pin state of the dragged column. */
+    draggedPinState: ColumnPinState;
+    /** The table (or grid container) DOM element to query headers from. */
+    tableElement: Element;
+    /** Pinned column configuration. */
+    pinnedColumns?: {
+        left?: string[];
+        right?: string[];
+    };
+}
 /**
  * Calculate the drop target for a dragged column based on mouse position.
  *
@@ -26,15 +44,8 @@ export declare function reorderColumnArray(order: string[], columnId: string, ta
  * 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 declare function calculateDropTarget(mouseX: number, columnOrder: string[], draggedColumnId: string, draggedPinState: ColumnPinState, tableElement: Element, pinnedColumns?: {
-    left?: string[];
-    right?: string[];
-}): IDropTarget | null;
+export declare function calculateDropTarget(params: ICalculateDropTargetParams): IDropTarget | null;

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

@@ -6,4 +6,13 @@ export declare function escapeCsvValue(value: unknown): string;
 export declare function buildCsvHeader(columns: CsvColumn[]): string;
 export declare function buildCsvRows<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string): string[];
 export declare function exportToCsv<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string, filename?: string): void;
+/**
+ * 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 declare function triggerCsvDownload(csvContent: string, filename: string): void;

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

@@ -0,0 +1,18 @@
+/**
+ * Pure fill handle helpers shared across React, Vue, Angular, and JS.
+ * No framework dependencies — operates on plain arrays and column definitions.
+ */
+import type { IColumnDef, ICellValueChangedEvent } from '../types/columnTypes';
+import type { ISelectionRange } from '../types/dataGridTypes';
+/**
+ * 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 declare function applyFillValues<T>(range: ISelectionRange, sourceRow: number, sourceCol: number, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];

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

@@ -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';
@@ -18,7 +18,7 @@ export { processClientSideData } from './clientSideData';
 export { areGridRowPropsEqual, isRowInRange } from './gridRowComparator';
 export type { GridRowComparatorProps } from './gridRowComparator';
 export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './columnReorder';
-export type { ColumnPinState, IDropTarget } from './columnReorder';
+export type { ColumnPinState, IDropTarget, ICalculateDropTargetParams } from './columnReorder';
 export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './virtualScroll';
 export type { IVisibleRange } from './virtualScroll';
 export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './dataGridViewModel';
@@ -29,7 +29,10 @@ 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 { findCtrlArrowTarget, computeTabNavigation, computeArrowNavigation, applyCellDeletion } from './keyboardNavigation';
+export type { ArrowNavigationContext, ArrowNavigationResult } 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/types/utils/keyboardNavigation.d.ts

@@ -2,6 +2,8 @@
  * Pure keyboard navigation helpers shared across React, Vue, Angular, and JS.
  * No framework dependencies — takes plain values, returns plain values.
  */
+import type { ISelectionRange } from '../types/dataGridTypes';
+import type { IColumnDef, ICellValueChangedEvent } from '../types/columnTypes';
 /**
  * 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.
@@ -19,13 +21,58 @@ export declare function findCtrlArrowTarget(pos: number, edge: number, step: num
  *
  * @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 declare function computeTabNavigation(rowIndex: number, columnIndex: number, maxRowIndex: number, maxColIndex: number, colOffset: number, shiftKey: boolean): {
     rowIndex: number;
     columnIndex: number;
 };
+/** Input parameters for arrow navigation computation. */
+export interface ArrowNavigationContext {
+    direction: 'ArrowDown' | 'ArrowUp' | 'ArrowLeft' | 'ArrowRight';
+    rowIndex: number;
+    columnIndex: number;
+    dataColIndex: number;
+    colOffset: number;
+    maxRowIndex: number;
+    maxColIndex: number;
+    visibleColCount: number;
+    isCtrl: boolean;
+    isShift: boolean;
+    selectionRange: ISelectionRange | null;
+    isEmptyAt: (r: number, c: number) => boolean;
+}
+/** Result of arrow navigation computation. */
+export interface ArrowNavigationResult {
+    newRowIndex: number;
+    newColumnIndex: number;
+    newDataColIndex: number;
+    newRange: ISelectionRange;
+}
+/**
+ * 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 declare function computeArrowNavigation(ctx: ArrowNavigationContext): ArrowNavigationResult;
+/**
+ * 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 declare function applyCellDeletion<T>(range: ISelectionRange, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];

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

@@ -1,4 +1,6 @@
-import type { IColumnDef, IFilters, FilterValue } from '../types';
+import type { IColumnDef, IColumnFilterDef, IFilters, FilterValue } from '../types';
+/** Type guard: returns true if val is an IColumnFilterDef (an object with a filter type). */
+export declare function isFilterConfig(val: unknown): val is IColumnFilterDef;
 /** Resolve the filter field key for a column (filterField or columnId). */
 export declare function getFilterField<T>(col: IColumnDef<T>): string;
 /** Merge a single filter change into a full IFilters object. Strips empty values automatically. */

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

@@ -3,6 +3,7 @@
  * No framework dependencies — operates only on plain ISelectionRange values.
  */
 import type { ISelectionRange } from '../types/dataGridTypes';
+export { normalizeSelectionRange } from '../types/dataGridTypes';
 /**
  * Compare two selection ranges by value (deep equality).
  * Returns true if both ranges are equal, including when both are null.
@@ -28,3 +29,29 @@ export declare function clampSelectionToBounds(range: ISelectionRange, maxRow: n
  * @returns Scroll speed in pixels per interval tick.
  */
 export declare function computeAutoScrollSpeed(distance: number, edgePx?: number, minSpeed?: number, maxSpeed?: number): number;
+/**
+ * Apply a shift-click range selection to a set of row IDs.
+ * Used by React `useRowSelection`, Vue `useRowSelection`, and JS `RowSelectionState`.
+ *
+ * @param start       Start index of the range (inclusive).
+ * @param end         End index of the range (inclusive).
+ * @param checked     Whether to add (true) or remove (false) the rows.
+ * @param items       Array of all row data objects.
+ * @param getRowId    Function to extract a unique row ID from an item.
+ * @param currentSelection  Current set of selected row IDs (will be shallow-copied).
+ * @returns A new Set of selected row IDs after applying the range.
+ */
+export declare function applyRangeRowSelection<T>(start: number, end: number, checked: boolean, items: T[], getRowId: (item: T) => string | number, currentSelection: Set<string | number>): Set<string | number>;
+/**
+ * Compute the allSelected / someSelected state from a set of selected row IDs.
+ * Used by React `useRowSelection`, Vue `useRowSelection`, and JS `RowSelectionState`.
+ *
+ * @param selectedIds  Current set of selected row IDs.
+ * @param items        Array of all row data objects.
+ * @param getRowId     Function to extract a unique row ID from an item.
+ * @returns An object with `allSelected` and `someSelected` booleans.
+ */
+export declare function computeRowSelectionState<T>(selectedIds: Set<string | number>, items: T[], getRowId: (item: T) => string | number): {
+    allSelected: boolean;
+    someSelected: boolean;
+};

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

@@ -0,0 +1,13 @@
+import type { IColumnDef } from '../types/columnTypes';
+import type { RowId } from '../types/dataGridTypes';
+/**
+ * Validate column definitions at grid initialization.
+ * Called once (not per render). Warns on empty/missing/duplicate columnIds.
+ */
+export declare function validateColumns<T>(columns: IColumnDef<T>[]): void;
+/**
+ * Validate that getRowId returns unique, non-null values.
+ * Dev-only (skipped in production). Samples the first 100 rows.
+ * Called once on first data render via a hasValidated flag in the caller.
+ */
+export declare function validateRowIds<T>(items: T[], getRowId: (item: T) => RowId): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "2.0.22",
+  "version": "2.1.0",
   "description": "OGrid core – framework-agnostic types, algorithms, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
@@ -36,5 +36,12 @@
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alaarab/ogrid.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://ogrid.dev",
+  "bugs": "https://github.com/alaarab/ogrid/issues"
 }