@opencorestack/opengridx 0.1.9 → 1.0.1

package/lib/hooks/core/useGridColumns.tsx

@@ -0,0 +1,228 @@
+import { useState, useMemo, useCallback, useEffect } from 'react';
+import { useColumnReorder } from '../useColumnReorder';
+import { ExpandIcon } from '../../components/ui/ExpandIcon';
+import type {
+    GridColDef,
+    GridRowModel,
+    GridRowId,
+    GridColumnOrderChangeParams,
+    GridRenderCellParams,
+} from '../../types';
+import type { GridInitialState } from '../../state/types';
+
+interface HierarchyHandlers {
+    toggleExpansion: (id: GridRowId) => void;
+}
+
+export interface UseGridColumnsParams<R extends GridRowModel> {
+    activeColumns: GridColDef<R>[];
+    isHierarchyEnabled: boolean;
+    isRowGrouping: boolean;
+    isTreeData: boolean;
+    activeHierarchyHandlers: HierarchyHandlers | null;
+    columnVisibilityModel: Record<string, boolean>;
+    columnOrder?: string[];
+    onColumnOrderChange?: (params: GridColumnOrderChangeParams) => void;
+    disableColumnReorder: boolean;
+    pivotMode: boolean;
+    checkboxSelection: boolean;
+    hasDetailPanel: boolean;
+    rowReordering: boolean;
+    initialState?: GridInitialState;
+    setColumns: (cols: GridColDef[]) => void;
+}
+
+export interface UseGridColumnsResult<R extends GridRowModel> {
+    effectiveColumns: GridColDef<R>[];
+    orderedColumns: GridColDef<R>[];
+    visibleOrderedColumns: GridColDef<R>[];
+    navigationColumns: Array<GridColDef<R> | { field: string }>;
+    columnWidths: Record<string, number>;
+    effectiveColumnOrder: string[];
+    setInternalColumnOrder: React.Dispatch<React.SetStateAction<string[]>>;
+    columnReorderHandlers: ReturnType<typeof useColumnReorder>;
+    handleColumnResize: (field: string, newWidth: number) => void;
+}
+
+export function useGridColumns<R extends GridRowModel>(
+    params: UseGridColumnsParams<R>
+): UseGridColumnsResult<R> {
+    const {
+        activeColumns,
+        isHierarchyEnabled,
+        isRowGrouping,
+        isTreeData,
+        activeHierarchyHandlers,
+        columnVisibilityModel,
+        columnOrder,
+        onColumnOrderChange,
+        disableColumnReorder,
+        pivotMode,
+        checkboxSelection,
+        hasDetailPanel,
+        rowReordering,
+        initialState,
+        setColumns,
+    } = params;
+
+    // ── Effective columns (hierarchy cell renderer injection) ─────────────────
+    const effectiveColumns = useMemo<GridColDef<R>[]>(() => {
+        if (!isHierarchyEnabled) return activeColumns;
+
+        return activeColumns.map((col, index) => {
+            if (index === 0) {
+                return {
+                    ...col,
+                    renderCell: (cellParams: GridRenderCellParams<R>) => {
+                        const r = cellParams.row as Record<string, unknown>;
+                        const depth = typeof r._treeDepth === 'number' ? r._treeDepth : 0;
+                        const hasChildren = Boolean(r._hasChildren);
+                        const isExpanded = Boolean(r._isExpanded);
+                        const groupingField = typeof r._groupingField === 'string' ? r._groupingField : undefined;
+                        const groupingValue = r._groupingValue;
+                        const descendantCount = typeof r._descendantCount === 'number' ? r._descendantCount : undefined;
+                        const isGroupRow = Boolean(r._isGroupRow);
+
+                        let content: React.ReactNode = col.renderCell ? col.renderCell(cellParams) : cellParams.value as React.ReactNode;
+
+                        if (isTreeData && hasChildren && isGroupRow) {
+                            content = (
+                                <div className="ogx__group-cell-content">
+                                    {cellParams.value as React.ReactNode}
+                                    {descendantCount !== undefined && descendantCount > 0 ? ` (${descendantCount})` : ''}
+                                </div>
+                            );
+                        }
+
+                        if (isRowGrouping && hasChildren && groupingField) {
+                            content = (
+                                <div className="ogx__group-cell-content">
+                                    {col.field === groupingField ? '' : `${groupingField}: `}
+                                    {String(groupingValue)}
+                                    {descendantCount !== undefined ? ` (${descendantCount})` : ''}
+                                </div>
+                            );
+                        }
+
+                        return (
+                            <div style={{ display: 'flex', alignItems: 'center', paddingLeft: depth * 24, width: '100%', height: '100%' }}>
+                                <div style={{ marginRight: 4, width: 24, height: 24, display: 'flex', alignItems: 'center', justifyContent: 'center', cursor: hasChildren ? 'pointer' : 'default', flexShrink: 0 }}>
+                                    {hasChildren ? (
+                                        <div
+                                            onClick={(e) => { e.stopPropagation(); e.preventDefault(); activeHierarchyHandlers?.toggleExpansion(cellParams.row.id); }}
+                                            onMouseDown={(e) => { e.stopPropagation(); }}
+                                            style={{ cursor: 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'center', pointerEvents: 'auto', zIndex: 10, position: 'relative' }}
+                                        >
+                                            <ExpandIcon
+                                                isExpanded={isExpanded}
+                                                onClick={(e) => { e.stopPropagation(); e.preventDefault(); activeHierarchyHandlers?.toggleExpansion(cellParams.row.id); }}
+                                            />
+                                        </div>
+                                    ) : null}
+                                </div>
+                                <div style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{content}</div>
+                            </div>
+                        );
+                    }
+                };
+            }
+
+            return {
+                ...col,
+                renderCell: (cellParams: GridRenderCellParams<R>) => {
+                    const r = cellParams.row as Record<string, unknown>;
+                    const hasChildren = Boolean(r._hasChildren);
+                    const groupingField = typeof r._groupingField === 'string' ? r._groupingField : undefined;
+
+                    if (isRowGrouping && hasChildren) {
+                        if (col.field === groupingField) return null;
+                        if (cellParams.value !== undefined && cellParams.value !== null) {
+                            return col.renderCell ? col.renderCell(cellParams) : cellParams.value;
+                        }
+                        return null;
+                    }
+
+                    return col.renderCell ? col.renderCell(cellParams) : cellParams.value;
+                }
+            };
+        }) as GridColDef<R>[];
+    }, [activeColumns, isHierarchyEnabled, isRowGrouping, isTreeData, activeHierarchyHandlers]);
+
+    // ── Column widths ─────────────────────────────────────────────────────────
+    const [columnWidths, setColumnWidths] = useState<Record<string, number>>(
+        () => initialState?.columns?.columnWidths ?? {}
+    );
+
+    const handleColumnResize = useCallback((field: string, newWidth: number) => {
+        setColumnWidths(prev => ({ ...prev, [field]: newWidth }));
+    }, []);
+
+    // ── Column order ──────────────────────────────────────────────────────────
+    const [internalColumnOrder, setInternalColumnOrder] = useState<string[]>(
+        () => initialState?.columns?.columnOrder ?? activeColumns.map(col => col.field)
+    );
+
+    const effectiveColumnOrder = columnOrder ?? internalColumnOrder;
+
+    useEffect(() => {
+        setColumns(activeColumns as unknown as GridColDef[]);
+    }, [activeColumns, setColumns]);
+
+    useEffect(() => {
+        if (pivotMode) {
+            setInternalColumnOrder(activeColumns.map(col => col.field));
+        }
+    }, [pivotMode, activeColumns]);
+
+    // ── Ordered / visible columns ─────────────────────────────────────────────
+    const orderedColumns = useMemo<GridColDef<R>[]>(() => {
+        if (disableColumnReorder) return effectiveColumns;
+
+        const orderMap = new Map(effectiveColumnOrder.map((field, idx) => [field, idx]));
+        return [...effectiveColumns].sort((a, b) => {
+            const ai = orderMap.get(a.field) ?? effectiveColumns.indexOf(a);
+            const bi = orderMap.get(b.field) ?? effectiveColumns.indexOf(b);
+            return ai - bi;
+        });
+    }, [effectiveColumns, effectiveColumnOrder, disableColumnReorder]);
+
+    const visibleOrderedColumns = useMemo<GridColDef<R>[]>(
+        () => orderedColumns.filter(col => columnVisibilityModel[col.field] !== false),
+        [orderedColumns, columnVisibilityModel]
+    );
+
+    // ── Column reorder handlers ───────────────────────────────────────────────
+    const columnReorderHandlers = useColumnReorder({
+        columns: orderedColumns,
+        onColumnOrderChange: useCallback((reorderParams: GridColumnOrderChangeParams) => {
+            const { oldIndex, targetIndex } = reorderParams;
+            const newOrder = [...effectiveColumnOrder];
+            const [movedField] = newOrder.splice(oldIndex, 1);
+            newOrder.splice(targetIndex, 0, movedField);
+            if (!columnOrder) setInternalColumnOrder(newOrder);
+            onColumnOrderChange?.(reorderParams);
+        }, [effectiveColumnOrder, columnOrder, onColumnOrderChange]),
+        disableColumnReorder,
+    });
+
+    // ── Navigation columns (system cols + data cols for keyboard nav) ─────────
+    const navigationColumns = useMemo(() => {
+        const specials: { field: string }[] = [];
+        if (rowReordering)    specials.push({ field: '__reorder_col__' });
+        if (hasDetailPanel)   specials.push({ field: '__expand_col__' });
+        if (checkboxSelection) specials.push({ field: '__checkbox_col__' });
+        return [...specials, ...orderedColumns] as Array<GridColDef<R> | { field: string }>;
+    }, [orderedColumns, checkboxSelection, hasDetailPanel, rowReordering]);
+
+    return {
+        effectiveColumns,
+        orderedColumns,
+        visibleOrderedColumns,
+        navigationColumns,
+        columnWidths,
+        effectiveColumnOrder,
+        setInternalColumnOrder,
+        columnReorderHandlers,
+        handleColumnResize,
+    };
+}

package/lib/hooks/core/useGridControlledState.ts

@@ -0,0 +1,192 @@
+import { useState, useCallback, useMemo } from 'react';
+import type {
+    GridRowId,
+    GridSortItem,
+    GridColumnPinning,
+    GridPaginationModel,
+    GridAggregationModel,
+    GridPivotModel,
+} from '../../types';
+import type { GridInitialState } from '../../state/types';
+
+export interface UseGridControlledStateParams {
+    initialState?: GridInitialState;
+
+    sortModel?: GridSortItem[];
+    onSortModelChange?: (model: GridSortItem[]) => void;
+
+    aggregationModel?: GridAggregationModel;
+    onAggregationModelChange?: (model: GridAggregationModel) => void;
+
+    columnVisibilityModel?: Record<string, boolean>;
+    onColumnVisibilityModelChange?: (model: Record<string, boolean>) => void;
+
+    pinnedColumns?: GridColumnPinning;
+    onPinnedColumnsChange?: (model: GridColumnPinning) => void;
+
+    pivotModel?: GridPivotModel;
+    onPivotModelChange?: (model: GridPivotModel) => void;
+
+    paginationModel?: GridPaginationModel;
+    onPaginationModelChange?: (model: GridPaginationModel) => void;
+
+    rowSelectionModel?: GridRowId[];
+    onRowSelectionModelChange?: (model: GridRowId[]) => void;
+}
+
+export interface UseGridControlledStateReturn {
+    // sort
+    sortModel: GridSortItem[];
+    isSortControlled: boolean;
+    setInternalSortModel: React.Dispatch<React.SetStateAction<GridSortItem[]>>;
+
+    // aggregation
+    aggregationModel: GridAggregationModel;
+    handleAggregationModelChange: (model: GridAggregationModel) => void;
+
+    // column visibility
+    columnVisibilityModel: Record<string, boolean>;
+    handleColumnVisibilityModelChange: (model: Record<string, boolean>) => void;
+
+    // pinned columns
+    pinnedColumns: GridColumnPinning;
+    handlePinnedColumnsChange: (model: GridColumnPinning) => void;
+
+    // pivot
+    currentPivotModel: GridPivotModel;
+    handlePivotModelChange: (model: GridPivotModel) => void;
+
+    // pagination
+    effectivePaginationModel: GridPaginationModel;
+    handlePaginationModelChange: (model: GridPaginationModel) => void;
+
+    // selection
+    rowSelectionModel: GridRowId[];
+    selectedRowIds: Set<GridRowId>;
+    isSelectionControlled: boolean;
+    setInternalRowSelectionModel: React.Dispatch<React.SetStateAction<GridRowId[]>>;
+}
+
+const EMPTY_PIVOT_MODEL: GridPivotModel = { rowFields: [], columnFields: [], valueFields: [] };
+
+export function useGridControlledState(params: UseGridControlledStateParams): UseGridControlledStateReturn {
+    const {
+        initialState,
+        sortModel: propSortModel,
+        aggregationModel: propAggregationModel,
+        onAggregationModelChange,
+        columnVisibilityModel: propColumnVisibilityModel,
+        onColumnVisibilityModelChange,
+        pinnedColumns: propPinnedColumns,
+        onPinnedColumnsChange,
+        pivotModel: propPivotModel,
+        onPivotModelChange,
+        paginationModel: propPaginationModel = { page: 0, pageSize: 100 },
+        onPaginationModelChange,
+        rowSelectionModel: propRowSelectionModel,
+        onRowSelectionModelChange,
+    } = params;
+
+    // ── Sort ─────────────────────────────────────────────────────────────────
+    const [internalSortModel, setInternalSortModel] = useState<GridSortItem[]>(
+        () => initialState?.sorting?.sortModel ?? []
+    );
+    const isSortControlled = propSortModel !== undefined;
+    const sortModel = isSortControlled ? propSortModel! : internalSortModel;
+
+    // ── Aggregation ──────────────────────────────────────────────────────────
+    const isAggregationControlled = propAggregationModel !== undefined;
+    const [internalAggregationModel, setInternalAggregationModel] = useState<GridAggregationModel>(
+        () => propAggregationModel ?? {}
+    );
+    const aggregationModel = isAggregationControlled ? propAggregationModel! : internalAggregationModel;
+
+    const handleAggregationModelChange = useCallback((model: GridAggregationModel) => {
+        if (!isAggregationControlled) setInternalAggregationModel(model);
+        onAggregationModelChange?.(model);
+    }, [isAggregationControlled, onAggregationModelChange]);
+
+    // ── Column visibility ────────────────────────────────────────────────────
+    const isColumnVisibilityControlled = propColumnVisibilityModel !== undefined;
+    const [internalColumnVisibilityModel, setInternalColumnVisibilityModel] = useState<Record<string, boolean>>(
+        () => initialState?.columns?.columnVisibilityModel ?? {}
+    );
+    const columnVisibilityModel = isColumnVisibilityControlled
+        ? propColumnVisibilityModel!
+        : internalColumnVisibilityModel;
+
+    const handleColumnVisibilityModelChange = useCallback((model: Record<string, boolean>) => {
+        if (!isColumnVisibilityControlled) setInternalColumnVisibilityModel(model);
+        onColumnVisibilityModelChange?.(model);
+    }, [isColumnVisibilityControlled, onColumnVisibilityModelChange]);
+
+    // ── Pinned columns ───────────────────────────────────────────────────────
+    const isPinnedColumnsControlled = propPinnedColumns !== undefined;
+    const [internalPinnedColumns, setInternalPinnedColumns] = useState<GridColumnPinning>(
+        () => initialState?.columns?.pinnedColumns ?? {}
+    );
+    const pinnedColumns = isPinnedColumnsControlled ? propPinnedColumns! : internalPinnedColumns;
+
+    const handlePinnedColumnsChange = useCallback((model: GridColumnPinning) => {
+        if (!isPinnedColumnsControlled) setInternalPinnedColumns(model);
+        onPinnedColumnsChange?.(model);
+    }, [isPinnedColumnsControlled, onPinnedColumnsChange]);
+
+    // ── Pivot ────────────────────────────────────────────────────────────────
+    const [internalPivotModel, setInternalPivotModel] = useState<GridPivotModel>(
+        () => propPivotModel ?? EMPTY_PIVOT_MODEL
+    );
+    const currentPivotModel = propPivotModel ?? internalPivotModel;
+
+    const handlePivotModelChange = useCallback((model: GridPivotModel) => {
+        setInternalPivotModel(model);
+        onPivotModelChange?.(model);
+    }, [onPivotModelChange]);
+
+    // ── Pagination ───────────────────────────────────────────────────────────
+    const isPaginationControlled = propPaginationModel !== undefined && params.paginationModel !== undefined;
+    const [internalPaginationModel, setInternalPaginationModel] = useState<GridPaginationModel>(
+        () => initialState?.pagination?.paginationModel ?? propPaginationModel
+    );
+    const effectivePaginationModel = isPaginationControlled ? propPaginationModel : internalPaginationModel;
+
+    const handlePaginationModelChange = useCallback((newModel: GridPaginationModel) => {
+        if (!isPaginationControlled) setInternalPaginationModel(newModel);
+        onPaginationModelChange?.(newModel);
+    }, [isPaginationControlled, onPaginationModelChange]);
+
+    // ── Row selection ────────────────────────────────────────────────────────
+    const isSelectionControlled = propRowSelectionModel !== undefined;
+    const [internalRowSelectionModel, setInternalRowSelectionModel] = useState<GridRowId[]>([]);
+    const rowSelectionModel = isSelectionControlled ? propRowSelectionModel! : internalRowSelectionModel;
+    const selectedRowIds = useMemo(() => new Set(rowSelectionModel), [rowSelectionModel]);
+
+    // onRowSelectionModelChange is consumed by the caller directly (they call it when selection changes)
+    void onRowSelectionModelChange;
+
+    return {
+        sortModel: sortModel as GridSortItem[],
+        isSortControlled,
+        setInternalSortModel: setInternalSortModel as React.Dispatch<React.SetStateAction<GridSortItem[]>>,
+
+        aggregationModel,
+        handleAggregationModelChange,
+
+        columnVisibilityModel,
+        handleColumnVisibilityModelChange,
+
+        pinnedColumns,
+        handlePinnedColumnsChange,
+
+        currentPivotModel,
+        handlePivotModelChange,
+
+        effectivePaginationModel,
+        handlePaginationModelChange,
+
+        rowSelectionModel,
+        selectedRowIds,
+        isSelectionControlled,
+        setInternalRowSelectionModel,
+    };
+}

package/lib/hooks/core/useGridRowPipeline.ts

@@ -0,0 +1,109 @@
+import { useMemo } from 'react';
+import { filterRows } from '../../utils/filtering';
+import { sortRows } from '../../utils/sorting';
+import { getPinnedRowGroups } from '../../utils/pinning';
+import type { GridRowModel, GridFilterModel, GridSortItem, GridPaginationModel, GridRowPinning, GridDataSource } from '../../types';
+
+interface HierarchyHandlers<R extends GridRowModel> {
+    getVisibleRows: () => R[];
+}
+
+export interface UseGridRowPipelineParams<R extends GridRowModel> {
+    effectiveRows: R[];
+    activeHierarchyHandlers: HierarchyHandlers<R> | null;
+    filterMode: string;
+    filterModel: GridFilterModel;
+    dataSource?: GridDataSource<R>;
+    sortModel: GridSortItem[];
+    sortingMode: string;
+    pagination: boolean;
+    paginationMode: string;
+    effectivePaginationModel: GridPaginationModel;
+    pinnedRows?: GridRowPinning;
+    isLoading: boolean;
+    pageSize: number;
+}
+
+export interface GridRowPipelineResult<R extends GridRowModel> {
+    filteredRows: R[];
+    pinnedTopRows: R[];
+    unpinnedRows: R[];
+    pinnedBottomRows: R[];
+    sortedUnpinnedRows: R[];
+    paginatedUnpinnedRows: R[];
+    allRenderableRows: R[];
+}
+
+export function useGridRowPipeline<R extends GridRowModel>(
+    params: UseGridRowPipelineParams<R>
+): GridRowPipelineResult<R> {
+    const {
+        effectiveRows,
+        activeHierarchyHandlers,
+        filterMode,
+        filterModel,
+        dataSource,
+        sortModel,
+        sortingMode,
+        pagination,
+        paginationMode,
+        effectivePaginationModel,
+        pinnedRows,
+        isLoading,
+        pageSize,
+    } = params;
+
+    const filteredRows = useMemo<R[]>(() => {
+        if (activeHierarchyHandlers) return (activeHierarchyHandlers.getVisibleRows() || []) as R[];
+        if (filterMode === 'server' && dataSource) return effectiveRows;
+        return filterRows(effectiveRows, filterModel) as R[];
+    }, [effectiveRows, filterModel, activeHierarchyHandlers, filterMode, dataSource]);
+
+    const { top: pinnedTopRows, center: unpinnedRows, bottom: pinnedBottomRows } = useMemo(() => {
+        if (activeHierarchyHandlers) return { top: [] as R[], center: filteredRows, bottom: [] as R[] };
+        return getPinnedRowGroups(filteredRows, pinnedRows);
+    }, [filteredRows, pinnedRows, activeHierarchyHandlers]);
+
+    const sortedUnpinnedRows = useMemo<R[]>(() => {
+        if (activeHierarchyHandlers) return unpinnedRows;
+        if (sortingMode === 'server' && dataSource) return unpinnedRows;
+        return sortRows(unpinnedRows, sortModel) as R[];
+    }, [unpinnedRows, sortModel, activeHierarchyHandlers, sortingMode, dataSource]);
+
+    const paginatedUnpinnedRows = useMemo<R[]>(() => {
+        if (!pagination) return sortedUnpinnedRows;
+        if (paginationMode === 'server' && dataSource) return sortedUnpinnedRows;
+        const start = effectivePaginationModel.page * effectivePaginationModel.pageSize;
+        return sortedUnpinnedRows.slice(start, start + effectivePaginationModel.pageSize);
+    }, [sortedUnpinnedRows, pagination, effectivePaginationModel.page, effectivePaginationModel.pageSize, paginationMode, dataSource]);
+
+    const allRenderableRows = useMemo<R[]>(() => {
+        if (activeHierarchyHandlers) return unpinnedRows;
+        const centerRows = pagination ? paginatedUnpinnedRows : sortedUnpinnedRows;
+        const base = [...pinnedTopRows, ...centerRows, ...pinnedBottomRows];
+
+        if (paginationMode === 'infinite' && isLoading && base.length > 0) {
+            const skeletonCount = Math.min(pageSize, 20);
+            const skeletons = Array.from({ length: skeletonCount }, (_, i) => ({
+                id: `__skeleton_${i}__`,
+                _isSkeleton: true,
+            }));
+            return [...base, ...skeletons] as R[];
+        }
+
+        return base;
+    }, [
+        pinnedTopRows, paginatedUnpinnedRows, sortedUnpinnedRows, pinnedBottomRows,
+        pagination, activeHierarchyHandlers, unpinnedRows, paginationMode, isLoading, pageSize,
+    ]);
+
+    return {
+        filteredRows,
+        pinnedTopRows,
+        unpinnedRows,
+        pinnedBottomRows,
+        sortedUnpinnedRows,
+        paginatedUnpinnedRows,
+        allRenderableRows,
+    };
+}

package/lib/hooks/core/useGridScrollSync.ts

@@ -0,0 +1,52 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+import type { GridRowScrollEndParams } from '../../types';
+
+export interface UseGridScrollSyncParams {
+    onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
+}
+
+export interface UseGridScrollSyncResult {
+    scrollTop: number;
+    scrollLeft: number;
+    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+}
+
+export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrollSyncResult {
+    const { onRowsScrollEnd } = params;
+
+    const pendingScrollRef = useRef({ scrollTop: 0, scrollLeft: 0 });
+    const scrollRafRef = useRef<number | null>(null);
+    const [scrollPos, setScrollPos] = useState({ scrollTop: 0, scrollLeft: 0 });
+
+    useEffect(() => {
+        return () => {
+            if (scrollRafRef.current !== null) cancelAnimationFrame(scrollRafRef.current);
+        };
+    }, []);
+
+    const handleScroll = useCallback((event: React.UIEvent<HTMLDivElement>) => {
+        const target = event.currentTarget;
+        pendingScrollRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft };
+
+        if (scrollRafRef.current !== null) cancelAnimationFrame(scrollRafRef.current);
+        scrollRafRef.current = requestAnimationFrame(() => {
+            scrollRafRef.current = null;
+            setScrollPos(pendingScrollRef.current);
+        });
+
+        if (onRowsScrollEnd) {
+            const { scrollTop, scrollHeight, clientHeight } = target;
+            const scrollThreshold = 100;
+
+            if (scrollHeight - scrollTop - clientHeight < scrollThreshold) {
+                onRowsScrollEnd({
+                    visibleTop: scrollTop,
+                    visibleBottom: scrollTop + clientHeight,
+                    viewportHeight: clientHeight,
+                });
+            }
+        }
+    }, [onRowsScrollEnd]);
+
+    return { scrollTop: scrollPos.scrollTop, scrollLeft: scrollPos.scrollLeft, handleScroll };
+}

package/lib/hooks/core/useGridStateSnapshot.ts

@@ -0,0 +1,63 @@
+import { useRef, useEffect, useLayoutEffect } from 'react';
+import type { GridState } from '../../state/types';
+import type {
+    GridSortItem,
+    GridFilterModel,
+    GridPaginationModel,
+    GridColumnPinning,
+} from '../../types';
+
+export interface UseGridStateSnapshotParams {
+    onStateChange?: (state: GridState) => void;
+    sortModel: GridSortItem[];
+    filterModel: GridFilterModel;
+    effectivePaginationModel: GridPaginationModel;
+    columnWidths: Record<string, number>;
+    effectiveColumnOrder: string[];
+    columnVisibilityModel: Record<string, boolean>;
+    pinnedColumns: GridColumnPinning;
+}
+
+export function useGridStateSnapshot(params: UseGridStateSnapshotParams): void {
+    const {
+        onStateChange,
+        sortModel,
+        filterModel,
+        effectivePaginationModel,
+        columnWidths,
+        effectiveColumnOrder,
+        columnVisibilityModel,
+        pinnedColumns,
+    } = params;
+
+    const onStateChangeRef = useRef(onStateChange);
+    useLayoutEffect(() => {
+        onStateChangeRef.current = onStateChange;
+    });
+
+    useEffect(() => {
+        if (!onStateChangeRef.current) return;
+
+        const snapshot: GridState = {
+            sorting: { sortModel: sortModel as { field: string; sort: 'asc' | 'desc' }[] },
+            filter: { filterModel },
+            pagination: { paginationModel: effectivePaginationModel },
+            columns: {
+                columnWidths,
+                columnOrder: effectiveColumnOrder,
+                columnVisibilityModel,
+                pinnedColumns,
+            },
+        };
+
+        onStateChangeRef.current(snapshot);
+    }, [
+        sortModel,
+        filterModel,
+        effectivePaginationModel,
+        columnWidths,
+        effectiveColumnOrder,
+        columnVisibilityModel,
+        pinnedColumns,
+    ]);
+}