@alaarab/ogrid-core 2.1.15 → 2.2.0

package/dist/esm/index.js

@@ -738,6 +738,66 @@ function calculateDropTarget(params) {
 }
 
 // src/utils/virtualScroll.ts
+function computeVisibleColumnRange(scrollLeft, columnWidths, containerWidth, overscan = 2) {
+  if (columnWidths.length === 0 || containerWidth <= 0) {
+    return { startIndex: 0, endIndex: -1, leftOffset: 0, rightOffset: 0 };
+  }
+  let cumWidth = 0;
+  let rawStart = columnWidths.length;
+  let rawEnd = -1;
+  for (let i = 0; i < columnWidths.length; i++) {
+    const colStart = cumWidth;
+    cumWidth += columnWidths[i];
+    if (cumWidth > scrollLeft && rawStart === columnWidths.length) {
+      rawStart = i;
+    }
+    if (colStart < scrollLeft + containerWidth) {
+      rawEnd = i;
+    }
+  }
+  if (rawStart > rawEnd) {
+    return { startIndex: 0, endIndex: -1, leftOffset: 0, rightOffset: 0 };
+  }
+  const startIndex = Math.max(0, rawStart - overscan);
+  const endIndex = Math.min(columnWidths.length - 1, rawEnd + overscan);
+  let leftOffset = 0;
+  for (let i = 0; i < startIndex; i++) {
+    leftOffset += columnWidths[i];
+  }
+  let rightOffset = 0;
+  for (let i = endIndex + 1; i < columnWidths.length; i++) {
+    rightOffset += columnWidths[i];
+  }
+  return { startIndex, endIndex, leftOffset, rightOffset };
+}
+function partitionColumnsForVirtualization(visibleCols, columnRange, pinnedColumns) {
+  const pinnedLeft = [];
+  const pinnedRight = [];
+  const unpinned = [];
+  for (const col of visibleCols) {
+    const pin = pinnedColumns?.[col.columnId];
+    if (pin === "left") pinnedLeft.push(col);
+    else if (pin === "right") pinnedRight.push(col);
+    else unpinned.push(col);
+  }
+  if (!columnRange || columnRange.endIndex < 0) {
+    return {
+      pinnedLeft,
+      virtualizedUnpinned: unpinned,
+      pinnedRight,
+      leftSpacerWidth: 0,
+      rightSpacerWidth: 0
+    };
+  }
+  const virtualizedUnpinned = unpinned.slice(columnRange.startIndex, columnRange.endIndex + 1);
+  return {
+    pinnedLeft,
+    virtualizedUnpinned,
+    pinnedRight,
+    leftSpacerWidth: columnRange.leftOffset,
+    rightSpacerWidth: columnRange.rightOffset
+  };
+}
 function computeVisibleRange(scrollTop, rowHeight, containerHeight, totalRows, overscan = 5) {
   if (totalRows <= 0 || rowHeight <= 0 || containerHeight <= 0) {
     return { startIndex: 0, endIndex: 0, offsetTop: 0, offsetBottom: 0 };
@@ -766,6 +826,239 @@ function getScrollTopForRow(rowIndex, rowHeight, containerHeight, align = "start
   }
 }
 
+// src/workers/sortFilterWorker.ts
+function workerBody() {
+  const ctx = self;
+  ctx.onmessage = (e) => {
+    const msg = e.data;
+    if (msg.type !== "sort-filter") return;
+    const { requestId, values, filters, sort } = msg;
+    const rowCount = values.length;
+    let indices = [];
+    const filterEntries = Object.entries(filters);
+    if (filterEntries.length === 0) {
+      indices = new Array(rowCount);
+      for (let i = 0; i < rowCount; i++) indices[i] = i;
+    } else {
+      for (let r = 0; r < rowCount; r++) {
+        let pass = true;
+        for (let f = 0; f < filterEntries.length; f++) {
+          const colIdx = Number(filterEntries[f][0]);
+          const filter = filterEntries[f][1];
+          const cellVal = values[r][colIdx];
+          switch (filter.type) {
+            case "text": {
+              const trimmed = filter.value.trim().toLowerCase();
+              if (trimmed && !String(cellVal ?? "").toLowerCase().includes(trimmed)) {
+                pass = false;
+              }
+              break;
+            }
+            case "multiSelect": {
+              if (filter.value.length > 0) {
+                const set = new Set(filter.value);
+                if (!set.has(String(cellVal ?? ""))) {
+                  pass = false;
+                }
+              }
+              break;
+            }
+            case "date": {
+              if (cellVal == null) {
+                pass = false;
+                break;
+              }
+              const ts = new Date(String(cellVal)).getTime();
+              if (isNaN(ts)) {
+                pass = false;
+                break;
+              }
+              if (filter.value.from) {
+                const fromTs = (/* @__PURE__ */ new Date(filter.value.from + "T00:00:00")).getTime();
+                if (ts < fromTs) {
+                  pass = false;
+                  break;
+                }
+              }
+              if (filter.value.to) {
+                const toTs = (/* @__PURE__ */ new Date(filter.value.to + "T23:59:59.999")).getTime();
+                if (ts > toTs) {
+                  pass = false;
+                  break;
+                }
+              }
+              break;
+            }
+          }
+          if (!pass) break;
+        }
+        if (pass) indices.push(r);
+      }
+    }
+    if (sort) {
+      const { columnIndex, direction } = sort;
+      const dir = direction === "asc" ? 1 : -1;
+      indices.sort((a, b) => {
+        const av = values[a][columnIndex];
+        const bv = values[b][columnIndex];
+        if (av == null && bv == null) return 0;
+        if (av == null) return -1 * dir;
+        if (bv == null) return 1 * dir;
+        if (typeof av === "number" && typeof bv === "number") {
+          return av === bv ? 0 : av > bv ? dir : -dir;
+        }
+        const sa = String(av).toLowerCase();
+        const sb = String(bv).toLowerCase();
+        return sa === sb ? 0 : sa > sb ? dir : -dir;
+      });
+    }
+    const response = {
+      type: "sort-filter-result",
+      requestId,
+      indices
+    };
+    ctx.postMessage(response);
+  };
+}
+
+// src/utils/workerSortFilter.ts
+var workerInstance = null;
+var requestCounter = 0;
+var pendingRequests = /* @__PURE__ */ new Map();
+function createSortFilterWorker() {
+  if (workerInstance) return workerInstance;
+  if (typeof Worker === "undefined" || typeof Blob === "undefined" || typeof URL === "undefined") {
+    return null;
+  }
+  try {
+    const fnStr = workerBody.toString();
+    const blob = new Blob(
+      [`(${fnStr})()`],
+      { type: "application/javascript" }
+    );
+    const url = URL.createObjectURL(blob);
+    workerInstance = new Worker(url);
+    URL.revokeObjectURL(url);
+    workerInstance.onmessage = (e) => {
+      const { requestId, indices } = e.data;
+      const pending = pendingRequests.get(requestId);
+      if (pending) {
+        pendingRequests.delete(requestId);
+        pending.resolve(indices);
+      }
+    };
+    workerInstance.onerror = (err) => {
+      for (const [id, pending] of pendingRequests) {
+        pending.reject(new Error(err.message || "Worker error"));
+        pendingRequests.delete(id);
+      }
+    };
+    return workerInstance;
+  } catch {
+    return null;
+  }
+}
+function terminateSortFilterWorker() {
+  if (workerInstance) {
+    workerInstance.terminate();
+    workerInstance = null;
+  }
+  for (const [id, pending] of pendingRequests) {
+    pending.reject(new Error("Worker terminated"));
+    pendingRequests.delete(id);
+  }
+}
+function extractValueMatrix(data, columns) {
+  const matrix = new Array(data.length);
+  for (let r = 0; r < data.length; r++) {
+    const row = new Array(columns.length);
+    for (let c = 0; c < columns.length; c++) {
+      const val = getCellValue(data[r], columns[c]);
+      if (val == null) {
+        row[c] = null;
+      } else if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+        row[c] = val;
+      } else {
+        row[c] = String(val);
+      }
+    }
+    matrix[r] = row;
+  }
+  return matrix;
+}
+function processClientSideDataAsync(data, columns, filters, sortBy, sortDirection) {
+  if (sortBy) {
+    const sortCol = columns.find((c) => c.columnId === sortBy);
+    if (sortCol?.compare) {
+      return Promise.resolve(processClientSideData(data, columns, filters, sortBy, sortDirection));
+    }
+  }
+  const worker = createSortFilterWorker();
+  if (!worker) {
+    return Promise.resolve(processClientSideData(data, columns, filters, sortBy, sortDirection));
+  }
+  const columnIndexMap = /* @__PURE__ */ new Map();
+  for (let i = 0; i < columns.length; i++) {
+    columnIndexMap.set(columns[i].columnId, i);
+  }
+  const values = extractValueMatrix(data, columns);
+  const columnMeta = columns.map((col, idx) => ({
+    type: col.type ?? "text",
+    index: idx
+  }));
+  const workerFilters = {};
+  for (const col of columns) {
+    const filterKey = getFilterField(col);
+    const val = filters[filterKey];
+    if (!val) continue;
+    const colIdx = columnIndexMap.get(col.columnId);
+    if (colIdx === void 0) continue;
+    switch (val.type) {
+      case "text":
+        workerFilters[colIdx] = { type: "text", value: val.value };
+        break;
+      case "multiSelect":
+        workerFilters[colIdx] = { type: "multiSelect", value: val.value };
+        break;
+      case "date":
+        workerFilters[colIdx] = { type: "date", value: { from: val.value.from, to: val.value.to } };
+        break;
+      // 'people' filter has a UserLike object — fall back to sync
+      case "people":
+        return Promise.resolve(processClientSideData(data, columns, filters, sortBy, sortDirection));
+    }
+  }
+  let sort;
+  if (sortBy) {
+    const sortColIdx = columnIndexMap.get(sortBy);
+    if (sortColIdx !== void 0) {
+      sort = { columnIndex: sortColIdx, direction: sortDirection ?? "asc" };
+    }
+  }
+  const requestId = ++requestCounter;
+  return new Promise((resolve, reject) => {
+    pendingRequests.set(requestId, {
+      resolve: (indices) => {
+        const result = new Array(indices.length);
+        for (let i = 0; i < indices.length; i++) {
+          result[i] = data[indices[i]];
+        }
+        resolve(result);
+      },
+      reject
+    });
+    const request = {
+      type: "sort-filter",
+      requestId,
+      values,
+      columnMeta,
+      filters: workerFilters,
+      sort
+    };
+    worker.postMessage(request);
+  });
+}
+
 // src/utils/dataGridViewModel.ts
 function getHeaderFilterConfig(col, input) {
   const filterable = isFilterConfig(col.filterable) ? col.filterable : null;
@@ -1652,4 +1945,4 @@ var Z_INDEX = {
   CONTEXT_MENU: 1e4
 };
 
-export { AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX, CELL_PADDING, CHECKBOX_COLUMN_WIDTH, COLUMN_HEADER_MENU_ITEMS, CellDescriptorCache, DEFAULT_DEBOUNCE_MS, DEFAULT_MIN_COLUMN_WIDTH, GRID_BORDER_RADIUS, GRID_CONTEXT_MENU_ITEMS, MAX_PAGE_BUTTONS, PAGE_SIZE_OPTIONS, PEOPLE_SEARCH_DEBOUNCE_MS, ROW_NUMBER_COLUMN_WIDTH, SIDEBAR_TRANSITION_MS, UndoRedoStack, Z_INDEX, applyCellDeletion, applyCutClear, applyFillValues, applyPastedValues, applyRangeRowSelection, areGridRowPropsEqual, booleanParser, buildCellIndex, buildCsvHeader, buildCsvRows, buildHeaderRows, buildInlineEditorProps, buildPopoverEditorProps, calculateDropTarget, clampSelectionToBounds, computeAggregations, computeArrowNavigation, computeAutoScrollSpeed, computeNextSortState, computeRowSelectionState, computeTabNavigation, computeTotalHeight, computeVisibleRange, currencyParser, dateParser, debounce, deriveFilterOptionsFromData, emailParser, escapeCsvValue, exportToCsv, findCtrlArrowTarget, flattenColumns, formatCellValueForTsv, formatSelectionAsTsv, formatShortcut, getCellRenderDescriptor, getCellValue, getColumnHeaderMenuItems, getContextMenuHandlers, getDataGridStatusBarConfig, getFilterField, getHeaderFilterConfig, getMultiSelectFilterFields, getPaginationViewModel, getPinStateForColumn, getScrollTopForRow, getStatusBarParts, injectGlobalStyles, isColumnEditable, isFilterConfig, isInSelectionRange, isRowInRange, measureColumnContentWidth, measureRange, mergeFilter, normalizeSelectionRange, numberParser, parseTsvClipboard, parseValue, processClientSideData, rangesEqual, reorderColumnArray, resolveCellDisplayContent, resolveCellStyle, toUserLike, triggerCsvDownload, validateColumns, validateRowIds, validateVirtualScrollConfig };
+export { AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX, CELL_PADDING, CHECKBOX_COLUMN_WIDTH, COLUMN_HEADER_MENU_ITEMS, CellDescriptorCache, DEFAULT_DEBOUNCE_MS, DEFAULT_MIN_COLUMN_WIDTH, GRID_BORDER_RADIUS, GRID_CONTEXT_MENU_ITEMS, MAX_PAGE_BUTTONS, PAGE_SIZE_OPTIONS, PEOPLE_SEARCH_DEBOUNCE_MS, ROW_NUMBER_COLUMN_WIDTH, SIDEBAR_TRANSITION_MS, UndoRedoStack, Z_INDEX, applyCellDeletion, applyCutClear, applyFillValues, applyPastedValues, applyRangeRowSelection, areGridRowPropsEqual, booleanParser, buildCellIndex, buildCsvHeader, buildCsvRows, buildHeaderRows, buildInlineEditorProps, buildPopoverEditorProps, calculateDropTarget, clampSelectionToBounds, computeAggregations, computeArrowNavigation, computeAutoScrollSpeed, computeNextSortState, computeRowSelectionState, computeTabNavigation, computeTotalHeight, computeVisibleColumnRange, computeVisibleRange, createSortFilterWorker, currencyParser, dateParser, debounce, deriveFilterOptionsFromData, emailParser, escapeCsvValue, exportToCsv, extractValueMatrix, findCtrlArrowTarget, flattenColumns, formatCellValueForTsv, formatSelectionAsTsv, formatShortcut, getCellRenderDescriptor, getCellValue, getColumnHeaderMenuItems, getContextMenuHandlers, getDataGridStatusBarConfig, getFilterField, getHeaderFilterConfig, getMultiSelectFilterFields, getPaginationViewModel, getPinStateForColumn, getScrollTopForRow, getStatusBarParts, injectGlobalStyles, isColumnEditable, isFilterConfig, isInSelectionRange, isRowInRange, measureColumnContentWidth, measureRange, mergeFilter, normalizeSelectionRange, numberParser, parseTsvClipboard, parseValue, partitionColumnsForVirtualization, processClientSideData, processClientSideDataAsync, rangesEqual, reorderColumnArray, resolveCellDisplayContent, resolveCellStyle, terminateSortFilterWorker, toUserLike, triggerCsvDownload, validateColumns, validateRowIds, validateVirtualScrollConfig };

package/dist/types/index.d.ts

@@ -22,8 +22,10 @@ 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 { computeVisibleRange, computeTotalHeight, getScrollTopForRow, computeVisibleColumnRange, partitionColumnsForVirtualization, } from './utils';
+export type { IVisibleRange, IVisibleColumnRange } from './utils';
+export { createSortFilterWorker, terminateSortFilterWorker, extractValueMatrix, processClientSideDataAsync, } from './utils';
+export type { SortFilterRequest, SortFilterResponse } from './utils';
 export { getHeaderFilterConfig, getCellRenderDescriptor, CellDescriptorCache, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './utils';
 export type { HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, } from './utils';
 export { debounce } from './utils';

package/dist/types/types/dataGridTypes.d.ts

@@ -143,6 +143,10 @@ export interface IVirtualScrollConfig {
      * higher values keep small grids fully rendered (no scroll offset artifacts).
      */
     threshold?: number;
+    /** Enable column virtualization — only render visible columns (default: false). */
+    columns?: boolean;
+    /** Number of extra columns to render outside the visible area (default: 2). */
+    columnOverscan?: number;
 }
 /** Configuration for column reordering via drag-and-drop. */
 export interface IColumnReorderConfig {

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

@@ -19,8 +19,10 @@ export { areGridRowPropsEqual, isRowInRange } from './gridRowComparator';
 export type { GridRowComparatorProps } from './gridRowComparator';
 export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './columnReorder';
 export type { ColumnPinState, IDropTarget, ICalculateDropTargetParams } from './columnReorder';
-export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './virtualScroll';
-export type { IVisibleRange } from './virtualScroll';
+export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, computeVisibleColumnRange, partitionColumnsForVirtualization, } from './virtualScroll';
+export type { IVisibleRange, IVisibleColumnRange } from './virtualScroll';
+export { createSortFilterWorker, terminateSortFilterWorker, extractValueMatrix, processClientSideDataAsync, } from './workerSortFilter';
+export type { SortFilterRequest, SortFilterResponse } from '../workers/sortFilterWorker';
 export { getHeaderFilterConfig, getCellRenderDescriptor, CellDescriptorCache, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './dataGridViewModel';
 export type { HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, } from './dataGridViewModel';
 export { debounce } from './debounce';

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

@@ -1,3 +1,37 @@
+import type { IColumnDef } from '../types';
+/** The visible column range for horizontal virtualization. */
+export interface IVisibleColumnRange {
+    /** First visible unpinned column index (inclusive, accounting for overscan). */
+    startIndex: number;
+    /** Last visible unpinned column index (inclusive, accounting for overscan). */
+    endIndex: number;
+    /** Pixel width of the left spacer (for columns before the visible range). */
+    leftOffset: number;
+    /** Pixel width of the right spacer (for columns after the visible range). */
+    rightOffset: number;
+}
+/**
+ * Compute the range of columns visible in the horizontal viewport.
+ * Linear scan over cumulative widths to find first/last visible column.
+ *
+ * @param scrollLeft - Current horizontal scroll offset (px)
+ * @param columnWidths - Array of widths for each unpinned column (px)
+ * @param containerWidth - Visible width of the scroll container (px)
+ * @param overscan - Number of extra columns to render on each side (default: 2)
+ * @returns The visible column range with start/end indices and left/right spacer widths
+ */
+export declare function computeVisibleColumnRange(scrollLeft: number, columnWidths: number[], containerWidth: number, overscan?: number): IVisibleColumnRange;
+/**
+ * Partition visible columns into pinned-left, virtualized-unpinned, and pinned-right.
+ * Pinned columns always render. Only unpinned columns in the visible range render.
+ */
+export declare function partitionColumnsForVirtualization<T>(visibleCols: IColumnDef<T>[], columnRange: IVisibleColumnRange | null, pinnedColumns?: Record<string, 'left' | 'right'>): {
+    pinnedLeft: IColumnDef<T>[];
+    virtualizedUnpinned: IColumnDef<T>[];
+    pinnedRight: IColumnDef<T>[];
+    leftSpacerWidth: number;
+    rightSpacerWidth: number;
+};
 /** The visible row range and spacer offsets for virtual scrolling. */
 export interface IVisibleRange {
     /** First visible row index (inclusive, accounting for overscan). */

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

@@ -0,0 +1,29 @@
+/**
+ * Main-thread wrapper for the sort/filter Web Worker.
+ * Falls back to synchronous processClientSideData when:
+ *   - Worker API is unavailable (SSR, jsdom)
+ *   - Sort column has a custom `compare` function
+ */
+import type { IColumnDef, IFilters } from '../types';
+/**
+ * Create (or reuse) the sort/filter Web Worker from an inline Blob URL.
+ * Returns null if the Worker API is unavailable.
+ */
+export declare function createSortFilterWorker(): Worker | null;
+/**
+ * Terminate the sort/filter worker and clean up.
+ */
+export declare function terminateSortFilterWorker(): void;
+/**
+ * Build a flat value matrix from data and columns.
+ * Each cell is extracted via getCellValue and coerced to a primitive.
+ */
+export declare function extractValueMatrix<T>(data: T[], columns: IColumnDef<T>[]): (string | number | boolean | null)[][];
+/**
+ * Async version of processClientSideData that offloads to a Web Worker.
+ *
+ * Falls back to synchronous processing when:
+ *   - Worker API is unavailable
+ *   - Sort column has a custom `compare` function (not serializable)
+ */
+export declare function processClientSideDataAsync<T>(data: T[], columns: IColumnDef<T>[], filters: IFilters, sortBy?: string, sortDirection?: 'asc' | 'desc'): Promise<T[]>;

package/dist/types/workers/sortFilterWorker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Web Worker script for offloading sort/filter to a background thread.
+ *
+ * Operates on flat primitives (no IColumnDef references) so it can be
+ * serialized into an inline Blob URL. The main thread sends a value matrix
+ * and column metadata; the worker applies filters + sort and returns row indices.
+ */
+export interface SortFilterRequest {
+    type: 'sort-filter';
+    requestId: number;
+    /** Flat value matrix: values[row][col] */
+    values: (string | number | boolean | null)[][];
+    /** Column metadata (only columns that participate in filter/sort). */
+    columnMeta: {
+        type: 'text' | 'numeric' | 'date' | 'boolean';
+        index: number;
+    }[];
+    /** Active filters keyed by column index in the values matrix. */
+    filters: Record<number, {
+        type: 'text';
+        value: string;
+    } | {
+        type: 'multiSelect';
+        value: string[];
+    } | {
+        type: 'date';
+        value: {
+            from?: string;
+            to?: string;
+        };
+    }>;
+    /** Sort spec (optional). */
+    sort?: {
+        columnIndex: number;
+        direction: 'asc' | 'desc';
+    };
+}
+export interface SortFilterResponse {
+    type: 'sort-filter-result';
+    requestId: number;
+    /** Sorted/filtered row indices into the original data array. */
+    indices: number[];
+}
+/**
+ * The worker function body. This is stringified into an inline Blob URL
+ * by the main-thread wrapper, so it must be fully self-contained.
+ */
+export declare function workerBody(): void;

package/package.json

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