@alaarab/ogrid-core 2.0.6 → 2.0.8

package/dist/esm/constants/index.js

@@ -0,0 +1,3 @@
+export * from './layout';
+export * from './timing';
+export * from './zIndex';

package/dist/esm/{constants.js → constants/layout.js}

@@ -1,5 +1,5 @@
 /**
- * Core OGrid constants — magic numbers centralized for consistency and maintainability.
+ * Layout and sizing constants for OGrid components.
  */
 /** Width of the row selection checkbox column in pixels. */
 export const CHECKBOX_COLUMN_WIDTH = 48;

package/dist/esm/constants/timing.js

@@ -0,0 +1,10 @@
+/**
+ * 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;
+/** Sidebar panel transition duration (milliseconds) */
+export const SIDEBAR_TRANSITION_MS = 300;

package/dist/esm/constants/zIndex.js

@@ -0,0 +1,16 @@
+/**
+ * Z-index constants for layering OGrid UI elements.
+ * Ensures consistent stacking order across all packages.
+ */
+export const Z_INDEX = {
+    /** Selection range overlay (marching ants) */
+    SELECTION_OVERLAY: 4,
+    /** Clipboard overlay (copy/cut animation) */
+    CLIPBOARD_OVERLAY: 5,
+    /** Dropdown menus (column chooser, pagination size select) */
+    DROPDOWN: 1000,
+    /** Modal dialogs */
+    MODAL: 2000,
+    /** Context menus (right-click grid menu) */
+    CONTEXT_MENU: 9999,
+};

package/dist/esm/utils/clientSideData.js

@@ -1,5 +1,10 @@
 import { getCellValue } from './cellValue';
 import { getFilterField } from './ogridHelpers';
+/**
+ * Cached column map to avoid rebuilding on every call.
+ * WeakMap keyed by columns array reference.
+ */
+const columnMapCache = new WeakMap();
 /**
  * Apply client-side filtering and sorting to data.
  * Extracted from useOGrid for testability and reuse.
@@ -12,10 +17,14 @@ import { getFilterField } from './ogridHelpers';
  * @returns Filtered and sorted array
  */
 export function processClientSideData(data, columns, filters, sortBy, sortDirection) {
-    // Build column lookup map for O(1) access by columnId
-    const columnMap = new Map();
-    for (let i = 0; i < columns.length; i++) {
-        columnMap.set(columns[i].columnId, columns[i]);
+    // Get or build column lookup map (cached via WeakMap)
+    let columnMap = columnMapCache.get(columns);
+    if (!columnMap) {
+        columnMap = new Map();
+        for (let i = 0; i < columns.length; i++) {
+            columnMap.set(columns[i].columnId, columns[i]);
+        }
+        columnMapCache.set(columns, columnMap);
     }
     // --- Filtering (single-pass: build predicates, then one .filter()) ---
     const predicates = [];

package/dist/esm/utils/dataGridViewModel.js

@@ -0,0 +1,208 @@
+/**
+ * View model helpers for DataGridTable.
+ * Pure TypeScript — no framework dependencies (React, Angular, Vue).
+ * Framework packages re-export these and may add thin framework-specific wrappers.
+ */
+import { getCellValue } from './cellValue';
+import { isInSelectionRange } from '../types/dataGridTypes';
+/**
+ * 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 filterType = (filterable?.type ?? 'none');
+    const filterField = filterable?.filterField ?? col.columnId;
+    const sortable = col.sortable !== false;
+    const filterValue = input.filters[filterField];
+    const base = {
+        columnKey: col.columnId,
+        columnName: col.name,
+        filterType,
+        isSorted: input.sortBy === col.columnId,
+        isSortedDescending: input.sortBy === col.columnId && input.sortDirection === 'desc',
+        onSort: sortable ? () => input.onColumnSort(col.columnId) : undefined,
+    };
+    if (filterType === 'text') {
+        return {
+            ...base,
+            textValue: filterValue?.type === 'text' ? filterValue.value : '',
+            onTextChange: (v) => input.onFilterChange(filterField, v.trim() ? { type: 'text', value: v } : undefined),
+        };
+    }
+    if (filterType === 'people') {
+        return {
+            ...base,
+            selectedUser: filterValue?.type === 'people' ? filterValue.value : undefined,
+            onUserChange: (u) => input.onFilterChange(filterField, u ? { type: 'people', value: u } : undefined),
+            peopleSearch: input.peopleSearch,
+        };
+    }
+    if (filterType === 'multiSelect') {
+        return {
+            ...base,
+            options: input.filterOptions[filterField] ?? [],
+            isLoadingOptions: input.loadingFilterOptions[filterField] ?? false,
+            selectedValues: filterValue?.type === 'multiSelect' ? filterValue.value : [],
+            onFilterChange: (values) => input.onFilterChange(filterField, values.length ? { type: 'multiSelect', value: values } : undefined),
+        };
+    }
+    if (filterType === 'date') {
+        return {
+            ...base,
+            dateValue: filterValue?.type === 'date' ? filterValue.value : undefined,
+            onDateChange: (v) => input.onFilterChange(filterField, v ? { type: 'date', value: v } : undefined),
+        };
+    }
+    return base;
+}
+/**
+ * Returns a descriptor for rendering a cell. UI uses this to decide editing-inline vs editing-popover vs display
+ * and to apply isActive, isInRange, etc. without duplicating the boolean logic.
+ */
+export function getCellRenderDescriptor(item, col, rowIndex, colIdx, input) {
+    const rowId = input.getRowId(item);
+    const globalColIndex = colIdx + input.colOffset;
+    const colEditable = col.editable === true ||
+        (typeof col.editable === 'function' && col.editable(item));
+    const canEditInline = input.editable !== false &&
+        !!colEditable &&
+        !!input.onCellValueChanged &&
+        typeof col.cellEditor !== 'function';
+    const canEditPopup = input.editable !== false &&
+        !!colEditable &&
+        !!input.onCellValueChanged &&
+        typeof col.cellEditor === 'function' &&
+        col.cellEditorPopup !== false;
+    const canEditAny = canEditInline || canEditPopup;
+    const isEditing = input.editingCell?.rowId === rowId &&
+        input.editingCell?.columnId === col.columnId;
+    const isActive = input.activeCell?.rowIndex === rowIndex &&
+        input.activeCell?.columnIndex === globalColIndex;
+    const isInRange = input.selectionRange != null &&
+        isInSelectionRange(input.selectionRange, rowIndex, colIdx);
+    const isInCutRange = input.cutRange != null &&
+        isInSelectionRange(input.cutRange, rowIndex, colIdx);
+    const isInCopyRange = input.copyRange != null &&
+        isInSelectionRange(input.copyRange, rowIndex, colIdx);
+    const isSelectionEndCell = !input.isDragging &&
+        input.copyRange == null &&
+        input.cutRange == null &&
+        input.selectionRange != null &&
+        rowIndex === input.selectionRange.endRow &&
+        colIdx === input.selectionRange.endCol;
+    const isPinned = col.pinned != null;
+    const pinnedSide = col.pinned ?? undefined;
+    let mode = 'display';
+    let editorType;
+    let value;
+    if (isEditing && canEditInline) {
+        mode = 'editing-inline';
+        if (col.cellEditor === 'text' ||
+            col.cellEditor === 'select' ||
+            col.cellEditor === 'checkbox' ||
+            col.cellEditor === 'richSelect' ||
+            col.cellEditor === 'date') {
+            editorType = col.cellEditor;
+        }
+        else if (col.type === 'date') {
+            editorType = 'date';
+        }
+        else if (col.type === 'boolean') {
+            editorType = 'checkbox';
+        }
+        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,
+        isActive,
+        isInRange,
+        isInCutRange,
+        isInCopyRange,
+        isSelectionEndCell,
+        canEditAny,
+        isPinned,
+        pinnedSide,
+        globalColIndex,
+        rowId,
+        rowIndex,
+        displayValue: value,
+    };
+}
+/**
+ * Resolves display content for a cell in display mode.
+ * Handles the renderCell -> valueFormatter -> String() fallback chain.
+ * Returns `unknown` — framework packages may narrow to their own node type.
+ */
+export function resolveCellDisplayContent(col, item, displayValue) {
+    const c = col;
+    if (c.renderCell && typeof c.renderCell === 'function') {
+        return c.renderCell(item);
+    }
+    if (col.valueFormatter)
+        return col.valueFormatter(displayValue, item);
+    if (displayValue == null)
+        return null;
+    if (col.type === 'date') {
+        const d = new Date(String(displayValue));
+        if (!Number.isNaN(d.getTime()))
+            return d.toLocaleDateString();
+    }
+    if (col.type === 'boolean') {
+        return displayValue ? 'True' : 'False';
+    }
+    return String(displayValue);
+}
+/**
+ * Resolves the cellStyle from a column def, handling both function and static values.
+ */
+export function resolveCellStyle(col, item) {
+    const c = col;
+    if (!c.cellStyle)
+        return undefined;
+    return typeof c.cellStyle === 'function' ? c.cellStyle(item) : c.cellStyle;
+}
+/**
+ * Builds props for InlineCellEditor. Shared across all UI packages.
+ */
+export function buildInlineEditorProps(item, col, descriptor, callbacks) {
+    return {
+        value: descriptor.value,
+        item,
+        column: col,
+        rowIndex: descriptor.rowIndex,
+        editorType: (descriptor.editorType ?? 'text'),
+        onCommit: (newValue) => callbacks.commitCellEdit(item, col.columnId, descriptor.value, newValue, descriptor.rowIndex, descriptor.globalColIndex),
+        onCancel: () => callbacks.setEditingCell(null),
+    };
+}
+/**
+ * Builds ICellEditorProps for custom popover editors. Shared across all UI packages.
+ */
+export function buildPopoverEditorProps(item, col, descriptor, pendingEditorValue, callbacks) {
+    const oldValue = descriptor.value;
+    const displayValue = pendingEditorValue !== undefined ? pendingEditorValue : oldValue;
+    return {
+        value: displayValue,
+        onValueChange: callbacks.setPendingEditorValue,
+        onCommit: () => {
+            const newValue = pendingEditorValue !== undefined ? pendingEditorValue : oldValue;
+            callbacks.commitCellEdit(item, col.columnId, oldValue, newValue, descriptor.rowIndex, descriptor.globalColIndex);
+        },
+        onCancel: callbacks.cancelPopoverEdit,
+        item,
+        column: col,
+        cellEditorParams: col.cellEditorParams,
+    };
+}

package/dist/esm/utils/debounce.js

@@ -0,0 +1,40 @@
+/**
+ * Debounces a function call, delaying execution until after `delayMs` milliseconds
+ * have elapsed since the last invocation.
+ *
+ * @param fn - The function to debounce
+ * @param delayMs - Delay in milliseconds
+ * @returns Debounced function with a `cancel` method
+ *
+ * @example
+ * ```typescript
+ * const search = debounce((query: string) => {
+ *   console.log('Searching:', query);
+ * }, 300);
+ *
+ * search('a');
+ * search('ab');
+ * search('abc'); // Only this will execute after 300ms
+ *
+ * search.cancel(); // Cancel pending execution
+ * ```
+ */
+export function debounce(fn, delayMs) {
+    let timeoutId = null;
+    const debounced = ((...args) => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn(...args);
+            timeoutId = null;
+        }, delayMs);
+    });
+    debounced.cancel = () => {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
+    };
+    return debounced;
+}

package/dist/esm/utils/index.js

@@ -12,3 +12,5 @@ export { processClientSideData } from './clientSideData';
 export { areGridRowPropsEqual, isRowInRange } from './gridRowComparator';
 export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './columnReorder';
 export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './virtualScroll';
+export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './dataGridViewModel';
+export { debounce } from './debounce';

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

@@ -0,0 +1,3 @@
+export * from './layout';
+export * from './timing';
+export * from './zIndex';

package/dist/types/{constants.d.ts → constants/layout.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Core OGrid constants — magic numbers centralized for consistency and maintainability.
+ * Layout and sizing constants for OGrid components.
  */
 /** Width of the row selection checkbox column in pixels. */
 export declare const CHECKBOX_COLUMN_WIDTH = 48;

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

@@ -0,0 +1,10 @@
+/**
+ * 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;
+/** Sidebar panel transition duration (milliseconds) */
+export declare const SIDEBAR_TRANSITION_MS = 300;

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

@@ -0,0 +1,18 @@
+/**
+ * Z-index constants for layering OGrid UI elements.
+ * Ensures consistent stacking order across all packages.
+ */
+export declare const Z_INDEX: {
+    /** Selection range overlay (marching ants) */
+    readonly SELECTION_OVERLAY: 4;
+    /** Clipboard overlay (copy/cut animation) */
+    readonly CLIPBOARD_OVERLAY: 5;
+    /** Dropdown menus (column chooser, pagination size select) */
+    readonly DROPDOWN: 1000;
+    /** Modal dialogs */
+    readonly MODAL: 2000;
+    /** Context menus (right-click grid menu) */
+    readonly CONTEXT_MENU: 9999;
+};
+/** Type helper for z-index keys */
+export type ZIndexKey = keyof typeof Z_INDEX;

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

@@ -0,0 +1,134 @@
+/**
+ * View model helpers for DataGridTable.
+ * Pure TypeScript — no framework dependencies (React, Angular, Vue).
+ * Framework packages re-export these and may add thin framework-specific wrappers.
+ */
+import type { ColumnFilterType, IDateFilterValue, ICellEditorProps } from '../types/columnTypes';
+import type { IColumnDef } from '../types/columnTypes';
+import type { RowId, UserLike, IFilters, FilterValue } from '../types/dataGridTypes';
+export interface HeaderFilterConfigInput {
+    sortBy?: string;
+    sortDirection: 'asc' | 'desc';
+    onColumnSort: (columnKey: string) => void;
+    filters: IFilters;
+    onFilterChange: (key: string, value: FilterValue | undefined) => void;
+    filterOptions: Record<string, string[]>;
+    loadingFilterOptions: Record<string, boolean>;
+    peopleSearch?: (query: string) => Promise<UserLike[]>;
+}
+/** Props to pass to ColumnHeaderFilter. Matches IColumnHeaderFilterProps. */
+export interface HeaderFilterConfig {
+    columnKey: string;
+    columnName: string;
+    filterType: ColumnFilterType;
+    isSorted?: boolean;
+    isSortedDescending?: boolean;
+    onSort?: () => void;
+    selectedValues?: string[];
+    onFilterChange?: (values: string[]) => void;
+    options?: string[];
+    isLoadingOptions?: boolean;
+    textValue?: string;
+    onTextChange?: (value: string) => void;
+    selectedUser?: UserLike;
+    onUserChange?: (user: UserLike | undefined) => void;
+    peopleSearch?: (query: string) => Promise<UserLike[]>;
+    dateValue?: IDateFilterValue;
+    onDateChange?: (value: IDateFilterValue | undefined) => void;
+}
+/**
+ * Returns ColumnHeaderFilter props from column def and grid filter/sort state.
+ */
+export declare function getHeaderFilterConfig<T>(col: IColumnDef<T>, input: HeaderFilterConfigInput): HeaderFilterConfig;
+export type CellRenderMode = 'editing-inline' | 'editing-popover' | 'display';
+export interface CellRenderDescriptorInput<T> {
+    editingCell: {
+        rowId: RowId;
+        columnId: string;
+    } | null;
+    activeCell: {
+        rowIndex: number;
+        columnIndex: number;
+    } | null;
+    selectionRange: {
+        startRow: number;
+        startCol: number;
+        endRow: number;
+        endCol: number;
+    } | null;
+    cutRange: {
+        startRow: number;
+        startCol: number;
+        endRow: number;
+        endCol: number;
+    } | null;
+    copyRange: {
+        startRow: number;
+        startCol: number;
+        endRow: number;
+        endCol: number;
+    } | null;
+    colOffset: number;
+    itemsLength?: number;
+    getRowId: (item: T) => RowId;
+    editable?: boolean;
+    onCellValueChanged?: unknown;
+    /** True while user is drag-selecting cells — hides fill handle during drag. */
+    isDragging?: boolean;
+}
+export interface CellRenderDescriptor {
+    mode: CellRenderMode;
+    editorType?: 'text' | 'select' | 'checkbox' | 'richSelect' | 'date';
+    value?: unknown;
+    isActive: boolean;
+    isInRange: boolean;
+    isInCutRange: boolean;
+    isInCopyRange: boolean;
+    isSelectionEndCell: boolean;
+    canEditAny: boolean;
+    isPinned: boolean;
+    pinnedSide?: 'left' | 'right';
+    globalColIndex: number;
+    rowId: RowId;
+    rowIndex: number;
+    /** Raw value for display (when mode === 'display'). UI uses col.renderCell or col.valueFormatter. */
+    displayValue?: unknown;
+}
+/**
+ * Returns a descriptor for rendering a cell. UI uses this to decide editing-inline vs editing-popover vs display
+ * and to apply isActive, isInRange, etc. without duplicating the boolean logic.
+ */
+export declare function getCellRenderDescriptor<T>(item: T, col: IColumnDef<T>, rowIndex: number, colIdx: number, input: CellRenderDescriptorInput<T>): CellRenderDescriptor;
+/**
+ * Resolves display content for a cell in display mode.
+ * Handles the renderCell -> valueFormatter -> String() fallback chain.
+ * Returns `unknown` — framework packages may narrow to their own node type.
+ */
+export declare function resolveCellDisplayContent<T>(col: IColumnDef<T>, item: T, displayValue: unknown): unknown;
+/**
+ * Resolves the cellStyle from a column def, handling both function and static values.
+ */
+export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T): Record<string, string> | undefined;
+/**
+ * Builds props for InlineCellEditor. Shared across all UI packages.
+ */
+export declare function buildInlineEditorProps<T>(item: T, col: IColumnDef<T>, descriptor: CellRenderDescriptor, callbacks: {
+    commitCellEdit: (item: T, columnId: string, oldValue: unknown, newValue: unknown, rowIndex: number, globalColIndex: number) => void;
+    setEditingCell: (cell: null) => void;
+}): {
+    value: unknown;
+    item: T;
+    column: IColumnDef<T>;
+    rowIndex: number;
+    editorType: "text" | "select" | "checkbox" | "richSelect" | "date";
+    onCommit: (newValue: unknown) => void;
+    onCancel: () => void;
+};
+/**
+ * Builds ICellEditorProps for custom popover editors. Shared across all UI packages.
+ */
+export declare function buildPopoverEditorProps<T>(item: T, col: IColumnDef<T>, descriptor: CellRenderDescriptor, pendingEditorValue: unknown, callbacks: {
+    setPendingEditorValue: (value: unknown) => void;
+    commitCellEdit: (item: T, columnId: string, oldValue: unknown, newValue: unknown, rowIndex: number, globalColIndex: number) => void;
+    cancelPopoverEdit: () => void;
+}): ICellEditorProps<T>;

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

@@ -0,0 +1,24 @@
+/**
+ * Debounces a function call, delaying execution until after `delayMs` milliseconds
+ * have elapsed since the last invocation.
+ *
+ * @param fn - The function to debounce
+ * @param delayMs - Delay in milliseconds
+ * @returns Debounced function with a `cancel` method
+ *
+ * @example
+ * ```typescript
+ * const search = debounce((query: string) => {
+ *   console.log('Searching:', query);
+ * }, 300);
+ *
+ * search('a');
+ * search('ab');
+ * search('abc'); // Only this will execute after 300ms
+ *
+ * search.cancel(); // Cancel pending execution
+ * ```
+ */
+export declare function debounce<T extends (...args: unknown[]) => void>(fn: T, delayMs: number): T & {
+    cancel: () => void;
+};

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

@@ -21,3 +21,6 @@ export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from '
 export type { ColumnPinState, IDropTarget } from './columnReorder';
 export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './virtualScroll';
 export type { IVisibleRange } from './virtualScroll';
+export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, } from './dataGridViewModel';
+export type { HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, } from './dataGridViewModel';
+export { debounce } from './debounce';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "OGrid core – framework-agnostic types, algorithms, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
@@ -16,11 +16,25 @@
     "build": "rimraf dist && tsc -p tsconfig.build.json",
     "test": "jest"
   },
-  "keywords": ["ogrid", "datatable", "typescript", "grid", "core"],
+  "keywords": [
+    "ogrid",
+    "datatable",
+    "typescript",
+    "grid",
+    "core"
+  ],
   "author": "Ala Arab",
   "license": "MIT",
-  "files": ["dist", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "sideEffects": false,
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }