@opencorestack/opengridx 0.1.8 → 1.0.0

package/lib/hooks/core/useGridKeyboardNavigation.ts

@@ -0,0 +1,371 @@
+import { useState, useCallback } from 'react';
+import type { GridRowModel, GridRowId, GridColDef, GridCellParams, GridSortItem, GridSortDirection } from '../../types';
+import type { GridEditingState } from '../features/useGridEditing';
+
+interface ColumnMetrics {
+    leftPinnedWidth: number;
+    rightPinnedWidth: number;
+    unpinnedAccWidths: number[];
+    unpinnedCols: { field: string }[];
+    totalSpecialsWidth: number;
+    pinnedSpecialsWidth: number;
+}
+
+interface VirtualizationSnapshot {
+    cumulativeHeights: number[];
+    pinnedTopHeight: number;
+    columnMetrics: ColumnMetrics | null;
+}
+
+export interface UseGridKeyboardNavigationParams<R extends GridRowModel> {
+    allRenderableRows: R[];
+    navigationColumns: { field: string; editable?: boolean; sortable?: boolean }[];
+    checkboxSelection: boolean;
+    selectedRowIds: Set<GridRowId>;
+    handleSelectionChange: (id: GridRowId, selected: boolean) => void;
+    handleDetailPanelToggle: (id: GridRowId) => void;
+    editingHandlers: {
+        editingCell: GridEditingState['editingCell'];
+        startCellEdit: (params: { id: GridRowId; field: string; value: unknown }) => void;
+        stopCellEdit: (params?: { cancel?: boolean }) => void;
+    };
+    setKeyboardMode: (mode: boolean) => void;
+    sortModel: GridSortItem[];
+    handleSort: (field: string, direction: GridSortDirection) => void;
+    isCellEditable?: (params: GridCellParams<R>) => boolean;
+    pagination: boolean;
+    pageSize: number;
+    virtualization: VirtualizationSnapshot;
+    viewportRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export interface FocusedCell {
+    id: GridRowId;
+    field: string;
+}
+
+export interface UseGridKeyboardNavigationReturn {
+    focusedCell: FocusedCell | null;
+    setFocusedCell: React.Dispatch<React.SetStateAction<FocusedCell | null>>;
+    handleFocus: (event: React.FocusEvent<HTMLDivElement>) => void;
+    handleBlur: (event: React.FocusEvent<HTMLDivElement>) => void;
+    handleKeyDown: (event: React.KeyboardEvent) => void;
+}
+
+export function useGridKeyboardNavigation<R extends GridRowModel>(
+    params: UseGridKeyboardNavigationParams<R>
+): UseGridKeyboardNavigationReturn {
+    const {
+        allRenderableRows,
+        navigationColumns,
+        checkboxSelection,
+        selectedRowIds,
+        handleSelectionChange,
+        handleDetailPanelToggle,
+        editingHandlers,
+        setKeyboardMode,
+        sortModel,
+        handleSort,
+        isCellEditable,
+        pagination,
+        pageSize,
+        virtualization,
+        viewportRef,
+    } = params;
+
+    const [focusedCell, setFocusedCell] = useState<FocusedCell | null>(null);
+
+    const handleFocus = useCallback((event: React.FocusEvent<HTMLDivElement>) => {
+        if (event.target === event.currentTarget) {
+            setFocusedCell(prev => {
+                if (prev) return prev;
+                if (checkboxSelection) {
+                    return { id: 'HEADER', field: '__checkbox_col__' };
+                }
+                const firstRow = allRenderableRows[0];
+                const firstCol = navigationColumns[0];
+                if (firstRow && firstCol) {
+                    return { id: firstRow.id, field: firstCol.field };
+                }
+                return null;
+            });
+        }
+    }, [allRenderableRows, navigationColumns, checkboxSelection]);
+
+    const handleBlur = useCallback((event: React.FocusEvent<HTMLDivElement>) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node)) {
+            setFocusedCell(null);
+        }
+    }, []);
+
+    const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
+        setKeyboardMode(true);
+
+        if (!focusedCell) return;
+
+        const { id, field } = focusedCell;
+        const isEditing = Boolean(editingHandlers.editingCell);
+
+        if (id === 'HEADER' && (event.key === 'Enter' || event.key === ' ')) {
+            event.preventDefault();
+            const col = navigationColumns.find(c => c.field === field);
+            if (col && col.sortable !== false) {
+                const currentSort = sortModel.find(item => item.field === field);
+                let newDirection: GridSortDirection = 'asc';
+                if (currentSort) {
+                    newDirection = currentSort.sort === 'asc' ? 'desc' : null;
+                }
+                handleSort(field, newDirection);
+            }
+            return;
+        }
+
+        if (event.key === 'Enter') {
+            event.preventDefault();
+            if (isEditing) {
+                editingHandlers.stopCellEdit();
+            } else {
+                const col = navigationColumns.find(c => c.field === field);
+                if (col?.editable) {
+                    const row = allRenderableRows.find(r => r.id === id);
+                    if (row) {
+                        editingHandlers.startCellEdit({ id, field, value: (row as R & Record<string, unknown>)[field] });
+                    }
+                }
+            }
+            return;
+        }
+
+        if (event.key === ' ' || event.key === 'Spacebar') {
+            if (!isEditing) {
+                if (field === '__checkbox_col__') {
+                    event.preventDefault();
+                    handleSelectionChange(id, !selectedRowIds.has(id));
+                    return;
+                }
+                if (field === '__expand_col__') {
+                    event.preventDefault();
+                    handleDetailPanelToggle(id);
+                    return;
+                }
+            }
+        }
+
+        if (event.key === 'Escape') {
+            if (isEditing) {
+                event.preventDefault();
+                editingHandlers.stopCellEdit({ cancel: true });
+            }
+            return;
+        }
+
+        if (isEditing && event.key !== 'Tab') return;
+
+        const isHeader = id === 'HEADER';
+        const rowIndex = isHeader ? -1 : allRenderableRows.findIndex(r => r.id === id);
+        const colIndex = navigationColumns.findIndex(c => c.field === field);
+
+        if (!isHeader && rowIndex === -1) return;
+        if (colIndex === -1) return;
+
+        const findNextCell = (
+            startRow: number,
+            startCol: number,
+            deltaRow: number,
+            deltaCol: number,
+            wrapRow: boolean,
+            allowHeader = false
+        ) => {
+            let r = startRow + deltaRow;
+            let c = startCol + deltaCol;
+
+            if (wrapRow && deltaCol !== 0) {
+                if (deltaCol > 0 && c >= navigationColumns.length) { c = 0; r++; }
+                else if (deltaCol < 0 && c < 0) { c = navigationColumns.length - 1; r--; }
+            }
+
+            if (!wrapRow && (c < 0 || c >= navigationColumns.length)) return null;
+            if (r < (allowHeader ? -1 : 0) || r >= allRenderableRows.length) return null;
+
+            return { r, c };
+        };
+
+        const findNextEditable = (
+            startRow: number,
+            startCol: number,
+            deltaRow: number,
+            deltaCol: number,
+            wrapRow: boolean,
+            allowHeader = false
+        ) => {
+            let r = startRow;
+            let c = startCol;
+            let steps = 0;
+            const maxSteps = allRenderableRows.length * navigationColumns.length + navigationColumns.length;
+
+            while (steps < maxSteps) {
+                steps++;
+                r += deltaRow;
+                c += deltaCol;
+
+                if (wrapRow && deltaCol !== 0) {
+                    if (deltaCol > 0) {
+                        if (c >= navigationColumns.length) { c = 0; r++; }
+                    } else {
+                        if (c < 0) { c = navigationColumns.length - 1; r--; }
+                    }
+                } else {
+                    if (c < 0 || c >= navigationColumns.length) return null;
+                }
+
+                if (r < -1 || r >= allRenderableRows.length) return null;
+
+                if (r === -1) {
+                    if (!allowHeader) continue;
+                    const col = navigationColumns[c];
+                    const isSortable = col.sortable !== false;
+                    if (['__checkbox_col__'].includes(col.field) || isSortable) return { r, c };
+                    continue;
+                }
+
+                const row = allRenderableRows[r];
+                const col = navigationColumns[c];
+                const isInteractable = ['__checkbox_col__', '__expand_col__', '__reorder_col__'].includes(col.field);
+                let cellEditable = col.editable || isInteractable;
+
+                if (isCellEditable && !isInteractable) {
+                    try {
+                        cellEditable = isCellEditable({
+                            row,
+                            field: col.field,
+                            value: (row as R & Record<string, unknown>)[col.field],
+                            colDef: col as GridColDef<R>,
+                            rowIndex: r,
+                            colIndex: c
+                        });
+                    } catch {
+                        // isCellEditable threw — treat cell as non-editable
+                    }
+                }
+
+                if (cellEditable) return { r, c };
+            }
+            return null;
+        };
+
+        let nextRowIndex = rowIndex;
+        let nextColIndex = colIndex;
+        let handled = false;
+
+        if (event.key === 'Tab') {
+            const dir = event.shiftKey ? -1 : 1;
+            const res = findNextEditable(rowIndex, colIndex, 0, dir, true, false);
+            if (res) { nextRowIndex = res.r; nextColIndex = res.c; handled = true; }
+        } else if (event.key === 'ArrowRight') {
+            const res = findNextCell(rowIndex, colIndex, 0, 1, true, true);
+            if (res) { nextRowIndex = res.r; nextColIndex = res.c; handled = true; }
+        } else if (event.key === 'ArrowLeft') {
+            const res = findNextCell(rowIndex, colIndex, 0, -1, true, true);
+            if (res) { nextRowIndex = res.r; nextColIndex = res.c; handled = true; }
+        } else if (event.key === 'ArrowDown') {
+            const res = findNextCell(rowIndex, colIndex, 1, 0, false, true);
+            if (res) { nextRowIndex = res.r; nextColIndex = res.c; handled = true; }
+        } else if (event.key === 'ArrowUp') {
+            const res = findNextCell(rowIndex, colIndex, -1, 0, false, true);
+            if (res) { nextRowIndex = res.r; nextColIndex = res.c; handled = true; }
+        } else if (event.key === 'Home') {
+            nextColIndex = 0;
+            if (event.ctrlKey || event.metaKey) nextRowIndex = -1;
+            handled = true;
+        } else if (event.key === 'End') {
+            nextColIndex = navigationColumns.length - 1;
+            if (event.ctrlKey || event.metaKey) nextRowIndex = allRenderableRows.length - 1;
+            handled = true;
+        } else if (event.key === 'PageUp') {
+            const pg = pagination ? pageSize : 10;
+            nextRowIndex = Math.max(-1, nextRowIndex - pg);
+            handled = true;
+        } else if (event.key === 'PageDown') {
+            const pg = pagination ? pageSize : 10;
+            nextRowIndex = Math.min(allRenderableRows.length - 1, nextRowIndex + pg);
+            handled = true;
+        }
+
+        if (handled) {
+            event.preventDefault();
+
+            if (isEditing && event.key === 'Tab') {
+                editingHandlers.stopCellEdit();
+            }
+
+            if (nextRowIndex >= -1 && nextRowIndex < allRenderableRows.length &&
+                nextColIndex >= 0 && nextColIndex < navigationColumns.length) {
+
+                const nextCol = navigationColumns[nextColIndex];
+
+                if (nextRowIndex === -1) {
+                    setFocusedCell({ id: 'HEADER', field: nextCol.field });
+                } else {
+                    setFocusedCell({ id: allRenderableRows[nextRowIndex].id, field: nextCol.field });
+                }
+
+                const el = viewportRef.current;
+                if (el) {
+                    const { cumulativeHeights, pinnedTopHeight, columnMetrics } = virtualization;
+                    const { clientHeight, clientWidth, scrollTop, scrollLeft } = el;
+
+                    const rowTop = nextRowIndex <= 0 ? 0 : cumulativeHeights[nextRowIndex - 1];
+                    const rowBottom = cumulativeHeights[nextRowIndex];
+                    const visibleTop = scrollTop + pinnedTopHeight;
+                    const visibleBottom = scrollTop + clientHeight;
+
+                    let newScrollTop = scrollTop;
+                    if (rowTop < visibleTop) {
+                        newScrollTop = Math.max(0, rowTop - pinnedTopHeight);
+                    } else if (rowBottom > visibleBottom) {
+                        newScrollTop = rowBottom - clientHeight;
+                    }
+                    if (newScrollTop !== scrollTop) el.scrollTop = newScrollTop;
+
+                    if (columnMetrics) {
+                        const { leftPinnedWidth, rightPinnedWidth, unpinnedAccWidths, unpinnedCols, totalSpecialsWidth, pinnedSpecialsWidth } = columnMetrics;
+                        const unpinnedIndex = unpinnedCols.findIndex(c => c.field === nextCol.field);
+
+                        if (unpinnedIndex !== -1) {
+                            const colLeft = totalSpecialsWidth + leftPinnedWidth + (unpinnedIndex > 0 ? unpinnedAccWidths[unpinnedIndex - 1] : 0);
+                            const colRight = totalSpecialsWidth + leftPinnedWidth + unpinnedAccWidths[unpinnedIndex];
+                            const visibleStart = scrollLeft + pinnedSpecialsWidth + leftPinnedWidth;
+                            const visibleEnd = scrollLeft + clientWidth - rightPinnedWidth;
+
+                            let newScrollLeft = scrollLeft;
+                            if (colLeft < visibleStart) {
+                                newScrollLeft = Math.max(0, colLeft - pinnedSpecialsWidth - leftPinnedWidth);
+                            } else if (colRight > visibleEnd) {
+                                newScrollLeft = colRight - clientWidth + rightPinnedWidth;
+                            }
+                            if (newScrollLeft !== scrollLeft) el.scrollLeft = newScrollLeft;
+                        }
+                    }
+                }
+            }
+        }
+    }, [
+        focusedCell,
+        allRenderableRows,
+        navigationColumns,
+        editingHandlers,
+        virtualization,
+        selectedRowIds,
+        handleSelectionChange,
+        handleDetailPanelToggle,
+        setKeyboardMode,
+        sortModel,
+        handleSort,
+        isCellEditable,
+        pagination,
+        pageSize,
+        viewportRef,
+    ]);
+
+    return { focusedCell, setFocusedCell, handleFocus, handleBlur, handleKeyDown };
+}

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,
+    ]);
+}