@opencorestack/opengridx 3.5.1 → 3.7.0

package/lib/hooks/core/useGridScrollSync.ts

@@ -1,4 +1,5 @@
 import { useRef, useState, useCallback, useEffect } from 'react';
+import { getScrollStart, setScrollStart } from '../../utils/direction';
 import type { GridRowScrollEndParams } from '../../types';
 import { getRowsScrollEndParams } from '../../utils/scroll/scrollEnd';
 
@@ -82,16 +83,18 @@ export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrol
     const handleScroll = useCallback((event: React.UIEvent<HTMLDivElement>) => {
         const target = event.currentTarget;
         const now = performance.now();
+        // Counted from the inline start, so the column window is the same in a right-to-left grid.
+        const scrollLeft = getScrollStart(target);
 
         // Velocity: total positional delta / elapsed time (px/ms)
         const deltaPos = Math.abs(target.scrollTop  - prevRef.current.scrollTop)
-                       + Math.abs(target.scrollLeft - prevRef.current.scrollLeft);
+                       + Math.abs(scrollLeft - prevRef.current.scrollLeft);
         const deltaTime = now - prevRef.current.time;
         const velocity = deltaTime > 0 ? deltaPos / deltaTime : 0;
         const movedVertically = target.scrollTop !== prevRef.current.scrollTop;
 
-        prevRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, time: now };
-        pendingRef.current = { scrollTop: target.scrollTop, scrollLeft: target.scrollLeft, velocity };
+        prevRef.current = { scrollTop: target.scrollTop, scrollLeft, time: now };
+        pendingRef.current = { scrollTop: target.scrollTop, scrollLeft, velocity };
 
         if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
         rafRef.current = requestAnimationFrame(() => {
@@ -120,16 +123,36 @@ export function useGridScrollSync(params: UseGridScrollSyncParams): UseGridScrol
         checkRowsScrollEnd(el);
     }, [rowCount, autoHeight, checkRowsScrollEnd]);
 
+    // Switching `dir` on the grid or an ancestor moves the content to the other side, and browsers
+    // reset (Firefox without a scroll event) or keep the scroll position as they please. Re-read it
+    // so the column window matches what the viewport shows.
+    useEffect(() => {
+        const doc = elementRef.current?.ownerDocument ?? (typeof document === 'undefined' ? null : document);
+        if (!doc || typeof MutationObserver === 'undefined') return;
+        const observer = new MutationObserver(() => {
+            const target = elementRef.current;
+            if (!target) return;
+            const actual = { scrollTop: target.scrollTop, scrollLeft: getScrollStart(target) };
+            const pending = pendingRef.current;
+            if (actual.scrollTop === pending.scrollTop && actual.scrollLeft === pending.scrollLeft) return;
+            pendingRef.current = { ...pending, ...actual };
+            prevRef.current = { ...prevRef.current, ...actual };
+            setScrollState(prev => ({ ...prev, ...actual }));
+        });
+        observer.observe(doc.documentElement, { attributes: true, attributeFilter: ['dir'], subtree: true });
+        return () => observer.disconnect();
+    }, []);
+
     const attachViewport = useCallback((element: HTMLDivElement | null) => {
         elementRef.current = element;
         if (!element) return;
         const { scrollTop, scrollLeft } = pendingRef.current;
         if (scrollTop === 0 && scrollLeft === 0) return;
         element.scrollTop = scrollTop;
-        element.scrollLeft = scrollLeft;
+        setScrollStart(element, scrollLeft);
         // The browser clamps to the new content. If it did, sync the state to what the element
         // shows (no scroll event fires when the position ends up unchanged).
-        const actual = { scrollTop: element.scrollTop, scrollLeft: element.scrollLeft };
+        const actual = { scrollTop: element.scrollTop, scrollLeft: getScrollStart(element) };
         if (actual.scrollTop !== scrollTop || actual.scrollLeft !== scrollLeft) {
             pendingRef.current = { ...pendingRef.current, ...actual };
             prevRef.current = { ...prevRef.current, ...actual };

package/lib/hooks/core/useGridScrollViewport.ts

@@ -0,0 +1,42 @@
+import type { MutableRefObject, RefObject } from 'react';
+import type { GridRowModel } from '../../types';
+import { useGridViewport, type UseGridViewportParams } from './useGridViewport';
+import { useGridMaxContentHeight } from './useGridMaxContentHeight';
+import { useGridVirtualization, type UseGridVirtualizationParams } from './useGridVirtualization';
+import type { LayoutResult } from './useLayout';
+
+export interface UseGridScrollViewportParams<R extends GridRowModel> {
+    viewport: Omit<UseGridViewportParams, 'viewportRef' | 'rowCount'>;
+    viewportRef: MutableRefObject<HTMLDivElement | null>;
+    containerRef: RefObject<HTMLDivElement | null>;
+    layout: LayoutResult<R>;
+    viewportWidth: number;
+    viewportHeight: number;
+    /** The virtualization inputs that do not come from the viewport. */
+    virtualization: Pick<UseGridVirtualizationParams<R>,
+        'autoHeight' | 'rowReordering' | 'hasDetailPanel' | 'checkboxSelection' | 'pinCheckboxColumn' | 'pinExpandColumn'>;
+}
+
+/**
+ * Steps 32–33 of `DataGrid` (docs/architecture/datagrid-orchestration.md), in their call order: scroll sync
+ * and viewport measurement, the tallest element this browser lays out (32a), and the render window.
+ */
+export function useGridScrollViewport<R extends GridRowModel>(params: UseGridScrollViewportParams<R>) {
+    const { viewport, viewportRef, containerRef, layout, viewportWidth, viewportHeight, virtualization: options } = params;
+
+    const { scrollTop, scrollLeft, overscanRows, handleScroll, setViewportElement } = useGridViewport({
+        ...viewport, rowCount: layout.unpinnedRowsLength, viewportRef,
+    });
+
+    const maxContentHeight = useGridMaxContentHeight(containerRef);
+    const virtualization = useGridVirtualization({
+        layout, scrollTop, scrollLeft,
+        viewportWidth,
+        viewportHeight,
+        ...options,
+        overscanRows,
+        maxContentHeight: maxContentHeight ?? Infinity,
+    });
+
+    return { handleScroll, setViewportElement, maxContentHeight, virtualization };
+}

package/lib/hooks/core/useGridSelectionAndStateApi.ts

@@ -0,0 +1,61 @@
+import type { GridRowModel } from '../../types';
+import { useGridRowInteractions, type UseGridRowInteractionsParams, type UseGridRowInteractionsResult } from './useGridRowInteractions';
+import { useGridApiMethods, type UseGridApiMethodsParams } from './useGridApiMethods';
+import type { UseGridControlledStateReturn } from './useGridControlledState';
+
+/** The state API inputs that do not come from `useGridControlledState`. */
+export type GridStateApiParams = Pick<UseGridApiMethodsParams,
+    'apiRef' | 'multiSort' | 'selectedRowIds' | 'disableMultipleRowSelection' | 'isSyntheticRowId' | 'getVisibleRows' |
+    'getAllFilteredRows' | 'visibleColumns'>;
+
+export interface UseGridSelectionAndStateApiParams<R extends GridRowModel> {
+    controlledState: UseGridControlledStateReturn;
+    interactions: Omit<UseGridRowInteractionsParams<R>, 'selectedRowIds' | 'onSelectionModelChange' | 'disableMultipleRowSelection'>;
+    api: GridStateApiParams;
+}
+
+/**
+ * Steps 23–24 of `DataGrid` (docs/architecture/datagrid-orchestration.md), in their call order: row
+ * selection and the row click / checkbox handlers, then the state API methods (sort, filter, pagination,
+ * selection, row grouping, aggregation, visibility and pivot setters, `getGridAiState`) installed on `apiRef`.
+ */
+export function useGridSelectionAndStateApi<R extends GridRowModel>(
+    params: UseGridSelectionAndStateApiParams<R>
+): UseGridRowInteractionsResult<R> {
+    const { controlledState, interactions, api } = params;
+    const {
+        sortModel, handleSortModelChange, filterModel, handleFilterModelChange, effectivePaginationModel,
+        handlePaginationModelChange, handleRowSelectionModelChange, rowGroupingModel, handleRowGroupingModelChange,
+        aggregationModel, handleAggregationModelChange, columnVisibilityModel, handleColumnVisibilityModelChange,
+        currentPivotModel, handlePivotModelChange,
+    } = controlledState;
+
+    const result = useGridRowInteractions<R>({
+        ...interactions,
+        selectedRowIds: api.selectedRowIds,
+        onSelectionModelChange: handleRowSelectionModelChange,
+        disableMultipleRowSelection: api.disableMultipleRowSelection,
+    });
+
+    useGridApiMethods({
+        ...api,
+        onSortModelChange: handleSortModelChange,
+        sortModel,
+        filterModel,
+        onFilterModelChange: handleFilterModelChange,
+        paginationModel: effectivePaginationModel,
+        onPaginationModelChange: handlePaginationModelChange,
+        getPendingRowSelectionModel: controlledState.getPendingRowSelectionModel,
+        onRowSelectionModelChange: handleRowSelectionModelChange,
+        rowGroupingModel,
+        onRowGroupingModelChange: handleRowGroupingModelChange,
+        aggregationModel,
+        onAggregationModelChange: handleAggregationModelChange,
+        columnVisibilityModel,
+        onColumnVisibilityModelChange: handleColumnVisibilityModelChange,
+        pivotModel: currentPivotModel,
+        onPivotModelChange: handlePivotModelChange,
+    });
+
+    return result;
+}

package/lib/hooks/core/useGridToolbarStack.ts

@@ -0,0 +1,49 @@
+import type { MutableRefObject, RefObject } from 'react';
+import type { GridApi, GridLocaleText, GridRowModel } from '../../types';
+import { useGridColumnsPanel } from './useGridColumnsPanel';
+import { useGridStylesheetWarning } from './useGridDevWarnings';
+import { useGridAiAssistant, type UseGridAiAssistantParams } from '../features/useGridAiAssistant';
+import { useGridToolbarProps, type UseGridToolbarPropsParams } from './useGridToolbarProps';
+
+/** What `useGridToolbarProps` needs besides the columns panel and the AI assistant built here. */
+export type GridToolbarStackToolbarParams<R extends GridRowModel> = Omit<UseGridToolbarPropsParams<R>,
+    'forceColumnsOpen' | 'onColumnsPanelClose' | 'aiAssistantEnabled' | 'aiAssistantOpen' | 'onAiAssistantToggle' |
+    'aiAssistantLabel' | 'forceFiltersOpen' | 'onFiltersPanelClose' | 'apiRef'>;
+
+export interface UseGridToolbarStackParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    containerRef: RefObject<HTMLDivElement | null>;
+    aiAssistant: Omit<UseGridAiAssistantParams, 'apiRef'>;
+    toolbar: GridToolbarStackToolbarParams<R>;
+    localeText: GridLocaleText | undefined;
+}
+
+/**
+ * Steps 44–46 of `DataGrid` (docs/architecture/datagrid-orchestration.md), in their call order: the columns
+ * panel (toolbar or standalone), the missing-stylesheet warning, the `aiAssistant` panel, and the props for
+ * `slots.toolbar` (which gets its Ask AI button from the assistant).
+ */
+export function useGridToolbarStack<R extends GridRowModel>(params: UseGridToolbarStackParams<R>) {
+    const { apiRef, containerRef, aiAssistant, toolbar, localeText } = params;
+
+    const columnsPanel = useGridColumnsPanel();
+    useGridStylesheetWarning(containerRef);
+
+    // The aiAssistant prompt panel (v3.5): applies validated replies through apiRef; apiRef.openAiAssistant.
+    const aiAssistantPanel = useGridAiAssistant({ apiRef, ...aiAssistant });
+
+    const toolbarProps = useGridToolbarProps<R>({
+        ...toolbar,
+        apiRef,
+        forceColumnsOpen: columnsPanel.toolbarPanelRequested,
+        onColumnsPanelClose: columnsPanel.closeToolbarPanel,
+        aiAssistantEnabled: aiAssistantPanel.enabled,
+        aiAssistantOpen: aiAssistantPanel.open,
+        onAiAssistantToggle: aiAssistantPanel.togglePanel,
+        aiAssistantLabel: localeText?.aiAssistantButton,
+        forceFiltersOpen: columnsPanel.toolbarFiltersRequested,
+        onFiltersPanelClose: columnsPanel.closeToolbarFiltersPanel,
+    });
+
+    return { columnsPanel, aiAssistantPanel, toolbarProps };
+}

package/lib/hooks/core/useGridViewApis.ts

@@ -0,0 +1,46 @@
+import type { MutableRefObject, RefObject } from 'react';
+import type { GridApi, GridColDef, GridRowId, GridRowModel } from '../../types';
+import { useGridClipboardApi } from './useGridClipboardApi';
+import { useGridScrollToIndexesApi } from './useGridScrollToIndexesApi';
+import { useGridColumnAutosize } from './useGridColumnAutosize';
+import type { LayoutResult } from './useLayout';
+
+export interface UseGridViewApisParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    containerRef: RefObject<HTMLDivElement | null>;
+    viewportRef: RefObject<HTMLDivElement | null>;
+    /** Rendered data columns with their layout-resolved widths, in render order (what Ctrl/Cmd+C copies). */
+    copyColumns: GridColDef[];
+    getRowId: (row: GridRowModel) => GridRowId;
+    disableClipboardCopy: boolean;
+    /** The cell range's copy text while `cellSelection` is on. */
+    getCellRangeCopyText: (() => string | null) | undefined;
+    layout: LayoutResult<R>;
+    rowHeight: number;
+    /** Every column in display order (what auto-size measures). */
+    orderedColumns: GridColDef<R>[];
+    onColumnResize: (field: string, width: number) => void;
+}
+
+/**
+ * Steps 30–31a of `DataGrid` (docs/architecture/datagrid-orchestration.md), in their call order: the
+ * `apiRef` installers that need the laid-out view — copy, `scrollToIndexes` and column auto-size.
+ * Returns the resize handle's auto-size handler.
+ */
+export function useGridViewApis<R extends GridRowModel>(params: UseGridViewApisParams<R>): (field: string) => void {
+    const {
+        apiRef, containerRef, viewportRef, copyColumns, getRowId, disableClipboardCopy, getCellRangeCopyText, layout, rowHeight,
+        orderedColumns, onColumnResize,
+    } = params;
+
+    useGridClipboardApi({
+        apiRef,
+        columns: copyColumns,
+        getRowId,
+        containerRef,
+        disableKeyboardShortcut: disableClipboardCopy,
+        getCellRangeCopyText,
+    });
+    useGridScrollToIndexesApi<R>({ apiRef, viewportRef, layout, rowHeight });
+    return useGridColumnAutosize<R>({ apiRef, containerRef, columns: orderedColumns, onColumnResize });
+}

package/lib/hooks/core/useLayout.ts

@@ -255,12 +255,19 @@ export function useLayout<R extends GridRowModel>(params: UseLayoutParams<R>): L
             return rowHeight + getDetailPanelLayoutHeight(panelHeight, detailPanelHeights?.get(id));
         };
 
-        const rowHeights = unpinnedRows.map((row, index) => heightOf(row, pinnedTopRowsLength + index));
-
-        const cumulativeHeights = rowHeights.reduce((acc, height, index) => {
-            acc.push((acc[index - 1] || 0) + height);
-            return acc;
-        }, [] as number[]);
+        // One pass with preallocated arrays: this runs for every row after each sort or filter. With
+        // no detail panel open every row has the plain height, so row ids are not looked up.
+        const rowCount = unpinnedRows.length;
+        const rowHeights = new Array<number>(rowCount);
+        const cumulativeHeights = new Array<number>(rowCount);
+        const anyPanelOpen = expandedRowIds.size > 0;
+        let runningHeight = 0;
+        for (let index = 0; index < rowCount; index++) {
+            const height = anyPanelOpen ? heightOf(unpinnedRows[index], pinnedTopRowsLength + index) : rowHeight;
+            rowHeights[index] = height;
+            runningHeight = (runningHeight || 0) + height; // as before: a NaN total restarts from 0
+            cumulativeHeights[index] = runningHeight;
+        }
 
         const skeletonCount = (paginationMode === 'infinite' && isLoading && unpinnedRows.length > 0)
             ? Math.min(pageSize, 20)

package/lib/hooks/useRowGrouping.ts

@@ -307,13 +307,15 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
     ), [defaultGroupingExpansionDepth]);
 
     const expandedGroupIds = useMemo<Set<GridRowId>>(() => {
+        // Only group nodes have children, so walk the groups rather than every leaf, in tree order.
         const ids = new Set<GridRowId>();
-        treeNodes.forEach((node, id) => {
-            if (!node.children || node.children.length === 0) return;
+        for (const id of groupIds) {
+            const node = treeNodes.get(id);
+            if (!node?.children || node.children.length === 0) continue;
             if (overrides.get(id) ?? isDefaultExpanded(node)) ids.add(id);
-        });
+        }
         return ids;
-    }, [treeNodes, overrides, isDefaultExpanded]);
+    }, [groupIds, treeNodes, overrides, isDefaultExpanded]);
 
     const toggleExpansion = useCallback((id: GridRowId) => {
         setExpansionState(prev => {
@@ -439,11 +441,9 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
         treeNodes.forEach((node, id) => {
             const variants = groupRowVariants.get(id);
             if (!variants) {
-                map.set(id, {
-                    hasChildren: false,
-                    treeDepth: node.depth,
-                    isGroupRow: false,
-                });
+                // One object per row (not shared per depth): `params.rowMeta` is public, and a consumer that
+                // writes to it must not change other rows.
+                map.set(id, { hasChildren: false, treeDepth: node.depth, isGroupRow: false });
                 return;
             }
             const groupMeta: GridRowMeta = {

package/lib/styles/base/variables.css

@@ -81,6 +81,18 @@
   --ogx-grid-cell-font-size: 13px;
   --ogx-grid-header-font-size: 13px;
   --ogx-grid-line-height: var(--ogx-line-height-normal);
+  /* Outer border and divider widths (v3.7). 0 hides a divider. Their colours,
+     --ogx-grid-column-divider-color and --ogx-grid-row-divider-color, are unset here and fall back
+     to --ogx-grid-border-color where they are used. So do the other theme-builder variables:
+     --ogx-grid-border-radius (--ogx-border-radius-lg), --ogx-grid-header-padding-x
+     (--ogx-grid-cell-padding-x), --ogx-grid-header-font-family / -font-weight and
+     --ogx-grid-cell-font-family / -font-weight (inherited; header weight 600), and
+     --ogx-overlay-font-family / -font-weight / -font-size (the grid font, each item's own weight,
+     --ogx-font-size-xs for menu and panel items). */
+  --ogx-grid-border-width: 1px;
+  --ogx-grid-column-divider-width: 1px;
+  --ogx-grid-header-column-divider-width: 1px;
+  --ogx-grid-row-divider-width: 1px;
   --ogx-grid-background: var(--ogx-color-white);
   --ogx-grid-border-color: var(--ogx-color-gray-200);
   --ogx-grid-header-background: var(--ogx-color-gray-50);

package/lib/theme/DataGridThemeProvider.tsx

@@ -272,6 +272,18 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-grid-cell-padding-y', g.cellPaddingY);
         set('--ogx-grid-cell-font-size', g.cellFontSize);
         set('--ogx-grid-header-font-size', g.headerFontSize);
+        set('--ogx-grid-header-font-family', g.headerFontFamily);
+        set('--ogx-grid-header-font-weight', g.headerFontWeight);
+        set('--ogx-grid-cell-font-family', g.cellFontFamily);
+        set('--ogx-grid-cell-font-weight', g.cellFontWeight);
+        set('--ogx-grid-header-padding-x', g.headerPaddingX);
+        set('--ogx-grid-border-width', g.borderWidth);
+        set('--ogx-grid-border-radius', g.borderRadius);
+        set('--ogx-grid-column-divider-width', g.columnDividerWidth);
+        set('--ogx-grid-header-column-divider-width', g.headerColumnDividerWidth);
+        set('--ogx-grid-row-divider-width', g.rowDividerWidth);
+        set('--ogx-grid-column-divider-color', g.columnDividerColor);
+        set('--ogx-grid-row-divider-color', g.rowDividerColor);
         set('--ogx-grid-background', g.background);
         set('--ogx-grid-border-color', g.borderColor);
         set('--ogx-grid-header-background', g.headerBackground);
@@ -338,6 +350,9 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-overlay-item-selected-text', o.itemSelectedText);
         set('--ogx-overlay-item-danger-bg', o.itemDangerBackground);
         set('--ogx-overlay-item-danger-text', o.itemDangerText);
+        set('--ogx-overlay-font-family', o.fontFamily);
+        set('--ogx-overlay-font-weight', o.fontWeight);
+        set('--ogx-overlay-font-size', o.fontSize);
     }
 
     if (theme.scrollbar) {