@alaarab/ogrid-core 1.4.0 → 1.5.0

package/dist/esm/components/OGridLayout.js

@@ -35,6 +35,7 @@ const footerStripStyle = {
 const gridAreaFlexStyle = {
     width: '100%',
     minWidth: 0,
+    minHeight: 0,
     flex: 1,
     display: 'flex',
 };

package/dist/esm/hooks/useActiveCell.js

@@ -17,6 +17,11 @@ export function useActiveCell(wrapperRef, editingCell) {
         const cell = wrapperRef.current.querySelector(selector);
         if (cell) {
             if (typeof cell.scrollIntoView === 'function') {
+                // Account for sticky <thead> so scrollIntoView doesn't leave
+                // the cell hidden behind the header.
+                const thead = wrapperRef.current.querySelector('thead');
+                const headerHeight = thead ? thead.getBoundingClientRect().height : 0;
+                cell.style.scrollMarginTop = `${headerHeight}px`;
                 cell.scrollIntoView({ block: 'nearest', inline: 'nearest' });
             }
             if (document.activeElement !== cell && typeof cell.focus === 'function') {

package/dist/esm/hooks/useColumnResize.js

@@ -1,50 +1,58 @@
-import { useCallback, useRef, useEffect } from 'react';
+import { useCallback, useRef } from 'react';
 export function useColumnResize({ columnSizingOverrides, setColumnSizingOverrides, minWidth = 80, defaultWidth = 120, onColumnResized, }) {
-    const resizingRef = useRef(null);
+    const rafRef = useRef(0);
+    const onColumnResizedRef = useRef(onColumnResized);
+    onColumnResizedRef.current = onColumnResized;
     const handleResizeStart = useCallback((e, col) => {
         e.preventDefault();
         e.stopPropagation();
-        const currentWidth = columnSizingOverrides[col.columnId]?.widthPx
+        const startX = e.clientX;
+        const columnId = col.columnId;
+        const startWidth = columnSizingOverrides[columnId]?.widthPx
             ?? col.idealWidth
             ?? col.defaultWidth
             ?? defaultWidth;
-        resizingRef.current = {
-            columnId: col.columnId,
-            startX: e.clientX,
-            startWidth: currentWidth,
+        let latestWidth = startWidth;
+        // Lock cursor and prevent text selection during drag
+        const prevCursor = document.body.style.cursor;
+        const prevUserSelect = document.body.style.userSelect;
+        document.body.style.cursor = 'col-resize';
+        document.body.style.userSelect = 'none';
+        const flushWidth = () => {
+            setColumnSizingOverrides((prev) => ({
+                ...prev,
+                [columnId]: { widthPx: latestWidth },
+            }));
         };
-    }, [columnSizingOverrides, defaultWidth]);
-    const handleResizeMove = useCallback((e) => {
-        if (!resizingRef.current)
-            return;
-        const { columnId, startX, startWidth } = resizingRef.current;
-        const deltaX = e.clientX - startX;
-        const newWidth = Math.max(minWidth, startWidth + deltaX);
-        setColumnSizingOverrides((prev) => ({
-            ...prev,
-            [columnId]: { widthPx: newWidth },
-        }));
-    }, [setColumnSizingOverrides, minWidth]);
-    const handleResizeEnd = useCallback(() => {
-        if (resizingRef.current && onColumnResized) {
-            const { columnId } = resizingRef.current;
-            const width = columnSizingOverrides[columnId]?.widthPx;
-            if (width != null) {
-                onColumnResized(columnId, width);
+        const onMove = (moveEvent) => {
+            const deltaX = moveEvent.clientX - startX;
+            latestWidth = Math.max(minWidth, startWidth + deltaX);
+            if (!rafRef.current) {
+                rafRef.current = requestAnimationFrame(() => {
+                    rafRef.current = 0;
+                    flushWidth();
+                });
+            }
+        };
+        const onUp = () => {
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+            // Restore cursor and user-select
+            document.body.style.cursor = prevCursor;
+            document.body.style.userSelect = prevUserSelect;
+            // Cancel pending RAF and flush final width synchronously
+            if (rafRef.current) {
+                cancelAnimationFrame(rafRef.current);
+                rafRef.current = 0;
+            }
+            flushWidth();
+            if (onColumnResizedRef.current) {
+                onColumnResizedRef.current(columnId, latestWidth);
             }
-        }
-        resizingRef.current = null;
-    }, [onColumnResized, columnSizingOverrides]);
-    useEffect(() => {
-        const handleMouseMove = (e) => handleResizeMove(e);
-        const handleMouseUp = () => handleResizeEnd();
-        document.addEventListener('mousemove', handleMouseMove);
-        document.addEventListener('mouseup', handleMouseUp);
-        return () => {
-            document.removeEventListener('mousemove', handleMouseMove);
-            document.removeEventListener('mouseup', handleMouseUp);
         };
-    }, [handleResizeMove, handleResizeEnd]);
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+    }, [columnSizingOverrides, defaultWidth, minWidth, setColumnSizingOverrides]);
     const getColumnWidth = useCallback((col) => {
         return columnSizingOverrides[col.columnId]?.widthPx
             ?? col.idealWidth

package/dist/esm/hooks/useDataGridState.js

@@ -23,12 +23,25 @@ const NOOP_CTX = (_e) => { };
  */
 export function useDataGridState(params) {
     const { props, wrapperRef } = params;
-    const { items, columns, getRowId, visibleColumns, columnOrder, rowSelection = 'none', selectedRows: controlledSelectedRows, onSelectionChange, statusBar, emptyState, editable, cellSelection: cellSelectionProp, onCellValueChanged: onCellValueChangedProp, initialColumnWidths, onColumnResized, } = props;
+    const { items, columns, getRowId, visibleColumns, columnOrder, rowSelection = 'none', selectedRows: controlledSelectedRows, onSelectionChange, statusBar, emptyState, editable, cellSelection: cellSelectionProp, onCellValueChanged: onCellValueChangedProp, initialColumnWidths, onColumnResized, pinnedColumns, } = props;
     const cellSelection = cellSelectionProp !== false;
     // Wrap onCellValueChanged with undo/redo tracking — all edits are recorded automatically
     const undoRedo = useUndoRedo({ onCellValueChanged: onCellValueChangedProp });
     const onCellValueChanged = undoRedo.onCellValueChanged;
-    const flatColumns = useMemo(() => flattenColumns(columns), [columns]);
+    const flatColumnsRaw = useMemo(() => flattenColumns(columns), [columns]);
+    // Apply runtime pin overrides (from applyColumnState or programmatic changes)
+    const flatColumns = useMemo(() => {
+        if (!pinnedColumns || Object.keys(pinnedColumns).length === 0)
+            return flatColumnsRaw;
+        return flatColumnsRaw.map((col) => {
+            const override = pinnedColumns[col.columnId];
+            if (override && col.pinned !== override) {
+                return { ...col, pinned: override };
+            }
+            // If col was pinned by definition but not in overrides, keep original
+            return col;
+        });
+    }, [flatColumnsRaw, pinnedColumns]);
     const visibleCols = useMemo(() => {
         const filtered = visibleColumns
             ? flatColumns.filter((c) => visibleColumns.has(c.columnId))
@@ -159,13 +172,8 @@ export function useDataGridState(params) {
     const minTableWidth = useMemo(() => {
         const PADDING = 16;
         const checkboxW = hasCheckboxCol ? 48 : 0;
-        return visibleCols.reduce((sum, c) => {
-            // Use the widest explicit width: resize override > idealWidth > defaultWidth > minWidth > 80
-            const override = columnSizingOverrides[c.columnId];
-            const w = override?.widthPx ?? c.idealWidth ?? c.defaultWidth ?? c.minWidth ?? 80;
-            return sum + w + PADDING;
-        }, checkboxW);
-    }, [visibleCols, hasCheckboxCol, columnSizingOverrides]);
+        return visibleCols.reduce((sum, c) => sum + (c.minWidth ?? 80) + PADDING, checkboxW);
+    }, [visibleCols, hasCheckboxCol]);
     useEffect(() => {
         const colIds = new Set(flatColumns.map((c) => c.columnId));
         setColumnSizingOverrides((prev) => {

package/dist/esm/hooks/useOGrid.js

@@ -6,7 +6,7 @@ import { useFilterOptions } from './useFilterOptions';
 import { useSideBarState } from './useSideBarState';
 const DEFAULT_PAGE_SIZE = 25;
 export function useOGrid(props, ref) {
-    const { columns: columnsProp, getRowId, data, dataSource, page: controlledPage, pageSize: controlledPageSize, sort: controlledSort, filters: controlledFilters, visibleColumns: controlledVisibleColumns, isLoading: controlledLoading, onPageChange, onPageSizeChange, onSortChange, onFiltersChange, onVisibleColumnsChange, columnOrder, onColumnOrderChange, onColumnResized, freezeRows, freezeCols, defaultPageSize = DEFAULT_PAGE_SIZE, defaultSortBy, defaultSortDirection = 'asc', toolbar, emptyState, entityLabelPlural = 'items', className, title, layoutMode = 'fill', suppressHorizontalScroll, editable, cellSelection, onCellValueChanged, onUndo, onRedo, canUndo, canRedo, rowSelection = 'none', selectedRows, onSelectionChange, statusBar, pageSizeOptions, sideBar, onError, columnChooser: columnChooserProp, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, } = props;
+    const { columns: columnsProp, getRowId, data, dataSource, page: controlledPage, pageSize: controlledPageSize, sort: controlledSort, filters: controlledFilters, visibleColumns: controlledVisibleColumns, isLoading: controlledLoading, onPageChange, onPageSizeChange, onSortChange, onFiltersChange, onVisibleColumnsChange, columnOrder, onColumnOrderChange, onColumnResized, onColumnPinned, freezeRows, freezeCols, defaultPageSize = DEFAULT_PAGE_SIZE, defaultSortBy, defaultSortDirection = 'asc', toolbar, emptyState, entityLabelPlural = 'items', className, title, layoutMode = 'fill', suppressHorizontalScroll, editable, cellSelection, onCellValueChanged, onUndo, onRedo, canUndo, canRedo, rowSelection = 'none', selectedRows, onSelectionChange, statusBar, pageSizeOptions, sideBar, onFirstDataRendered, onError, columnChooser: columnChooserProp, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, } = props;
     // Resolve column chooser placement
     const columnChooserPlacement = columnChooserProp === false ? 'none'
         : columnChooserProp === 'sidebar' ? 'sidebar'
@@ -36,6 +36,7 @@ export function useOGrid(props, ref) {
         return new Set(visible.length > 0 ? visible : columns.map((c) => c.columnId));
     });
     const [columnWidthOverrides, setColumnWidthOverrides] = useState({});
+    const [pinnedOverrides, setPinnedOverrides] = useState({});
     const page = controlledPage ?? internalPage;
     const pageSize = controlledPageSize ?? internalPageSize;
     const sort = controlledSort ?? internalSort;
@@ -260,6 +261,14 @@ export function useOGrid(props, ref) {
     const displayTotalCount = isClientSide && clientItemsAndTotal
         ? clientItemsAndTotal.totalCount
         : serverTotalCount;
+    // Fire onFirstDataRendered once when the grid first has data
+    const firstDataRenderedRef = useRef(false);
+    useEffect(() => {
+        if (!firstDataRenderedRef.current && displayItems.length > 0) {
+            firstDataRenderedRef.current = true;
+            onFirstDataRendered?.();
+        }
+    }, [displayItems.length, onFirstDataRendered]);
     useImperativeHandle(ref, () => ({
         setRowData: (d) => {
             if (!isServerSide)
@@ -272,6 +281,7 @@ export function useOGrid(props, ref) {
             columnOrder: columnOrder ?? undefined,
             columnWidths: Object.keys(columnWidthOverrides).length > 0 ? columnWidthOverrides : undefined,
             filters: Object.keys(filters).length > 0 ? filters : undefined,
+            pinnedColumns: Object.keys(pinnedOverrides).length > 0 ? pinnedOverrides : undefined,
         }),
         applyColumnState: (state) => {
             if (state.visibleColumns) {
@@ -289,6 +299,9 @@ export function useOGrid(props, ref) {
             if (state.filters) {
                 setFilters(state.filters);
             }
+            if (state.pinnedColumns) {
+                setPinnedOverrides(state.pinnedColumns);
+            }
         },
         setFilterModel: setFilters,
         getSelectedRows: () => Array.from(effectiveSelectedRows),
@@ -318,6 +331,7 @@ export function useOGrid(props, ref) {
         sort,
         columnOrder,
         columnWidthOverrides,
+        pinnedOverrides,
         filters,
         setFilters,
         setSort,
@@ -350,6 +364,7 @@ export function useOGrid(props, ref) {
             totalCount: totalData,
             filteredCount: hasActiveFilters ? filteredData : undefined,
             selectedCount: effectiveSelectedRows.size,
+            suppressRowCount: true, // OGrid always has pagination which shows the total
         };
     }, [
         statusBar,
@@ -364,6 +379,17 @@ export function useOGrid(props, ref) {
         setColumnWidthOverrides((prev) => ({ ...prev, [columnId]: width }));
         onColumnResized?.(columnId, width);
     }, [onColumnResized]);
+    const handleColumnPinned = useCallback((columnId, pinned) => {
+        setPinnedOverrides((prev) => {
+            if (pinned === null) {
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { [columnId]: _, ...rest } = prev;
+                return rest;
+            }
+            return { ...prev, [columnId]: pinned };
+        });
+        onColumnPinned?.(columnId, pinned);
+    }, [onColumnPinned]);
     // --- Side bar ---
     const sideBarState = useSideBarState({ config: sideBar });
     const filterableColumns = useMemo(() => columns
@@ -425,6 +451,8 @@ export function useOGrid(props, ref) {
         columnOrder,
         onColumnOrderChange,
         onColumnResized: handleColumnResized,
+        onColumnPinned: handleColumnPinned,
+        pinnedColumns: pinnedOverrides,
         initialColumnWidths: columnWidthOverrides,
         freezeRows,
         freezeCols,

package/dist/esm/utils/aggregationUtils.js

@@ -19,7 +19,9 @@ export function computeAggregations(items, visibleCols, selectionRange) {
             const item = items[r];
             const col = visibleCols[c];
             const raw = getCellValue(item, col);
-            const num = typeof raw === 'number' ? raw : parseFloat(String(raw));
+            // Use Number() instead of parseFloat() so date strings like "2020-08-22"
+            // return NaN instead of partially parsing to 2020
+            const num = typeof raw === 'number' ? raw : Number(raw);
             if (!isNaN(num) && isFinite(num)) {
                 numericValues.push(num);
             }

package/dist/esm/utils/statusBarHelpers.js

@@ -2,9 +2,11 @@
  * Returns an array of status bar parts (Rows, Filtered, Selected) for consistent rendering across packages.
  */
 export function getStatusBarParts(input) {
-    const { totalCount, filteredCount, selectedCount, selectedCellCount, aggregation } = input;
+    const { totalCount, filteredCount, selectedCount, selectedCellCount, aggregation, suppressRowCount } = input;
     const parts = [];
-    parts.push({ key: 'total', label: 'Rows:', value: totalCount });
+    if (!suppressRowCount) {
+        parts.push({ key: 'total', label: 'Rows:', value: totalCount });
+    }
     if (filteredCount !== undefined && filteredCount !== totalCount) {
         parts.push({ key: 'filtered', label: 'Filtered:', value: filteredCount });
     }

package/dist/types/components/StatusBar.d.ts

@@ -18,6 +18,7 @@ export interface StatusBarProps {
         max: number;
         count: number;
     } | null;
+    suppressRowCount?: boolean;
     classNames?: StatusBarClassNames;
 }
 export declare function StatusBar({ classNames, ...rest }: StatusBarProps): React.ReactElement;

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

@@ -64,6 +64,8 @@ export interface IGridColumnState {
     columnWidths?: Record<string, number>;
     /** Active filters. */
     filters?: IFilters;
+    /** Pinned columns (column id -> 'left' | 'right'). */
+    pinnedColumns?: Record<string, 'left' | 'right'>;
 }
 /** Row selection mode. */
 export type RowSelectionMode = 'none' | 'single' | 'multiple';
@@ -92,6 +94,8 @@ export interface IStatusBarProps {
         max: number;
         count: number;
     } | null;
+    /** When true, hides the "Rows: X" label (e.g. when pagination already shows it). */
+    suppressRowCount?: boolean;
 }
 /** Identifies a cell for keyboard navigation. */
 export interface IActiveCell {
@@ -168,6 +172,8 @@ export interface IOGridProps<T> {
     onColumnOrderChange?: (order: string[]) => void;
     /** Called when a column is resized by the user. */
     onColumnResized?: (columnId: string, width: number) => void;
+    /** Called when a column is pinned or unpinned. */
+    onColumnPinned?: (columnId: string, pinned: 'left' | 'right' | null) => void;
     freezeRows?: number;
     freezeCols?: number;
     editable?: boolean;
@@ -206,6 +212,8 @@ export interface IOGridProps<T> {
     sideBar?: boolean | ISideBarDef;
     /** Page size options shown in the pagination dropdown. Default: [10, 20, 50, 100]. */
     pageSizeOptions?: number[];
+    /** Fires once when the grid first renders with data (useful for restoring column state). */
+    onFirstDataRendered?: () => void;
     /** Called when server-side fetchPage fails. */
     onError?: (error: unknown) => void;
     'aria-label'?: string;
@@ -225,6 +233,10 @@ export interface IOGridDataGridProps<T> {
     onColumnOrderChange?: (order: string[]) => void;
     /** Called when a column is resized by the user. */
     onColumnResized?: (columnId: string, width: number) => void;
+    /** Called when a column is pinned or unpinned. */
+    onColumnPinned?: (columnId: string, pinned: 'left' | 'right' | null) => void;
+    /** Runtime pin overrides (from restored state or programmatic changes). */
+    pinnedColumns?: Record<string, 'left' | 'right'>;
     /** Initial column width overrides (from restored state). */
     initialColumnWidths?: Record<string, number>;
     /** Number of rows to freeze (sticky), e.g. 1 = header row. */

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

@@ -19,6 +19,8 @@ export interface StatusBarPartsInput {
         max: number;
         count: number;
     } | null;
+    /** When true, hides the "Rows: X" label (e.g. when pagination already shows it). */
+    suppressRowCount?: boolean;
 }
 /**
  * Returns an array of status bar parts (Rows, Filtered, Selected) for consistent rendering across packages.

package/package.json

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