@opencorestack/opengridx 2.1.0 → 3.0.1

package/lib/hooks/core/useGridColumnsPanel.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+import type { GridToolbarHost } from './gridToolbarHostContext';
+
+export interface UseGridColumnsPanelResult {
+    /** Provide through `GridToolbarHostContext` around the toolbar slot. */
+    toolbarHost: GridToolbarHost;
+    /** Passed to the toolbar as `forceColumnsOpen`. */
+    toolbarPanelRequested: boolean;
+    /** Passed to the toolbar as `onColumnsPanelClose`. */
+    closeToolbarPanel: () => void;
+    /** Whether the standalone Columns panel (used when no toolbar can show one) is open. */
+    standalonePanelOpen: boolean;
+    closeStandalonePanel: () => void;
+    /** Attach to the standalone panel; a mousedown outside it closes it. */
+    standalonePanelRef: RefObject<HTMLDivElement | null>;
+    /** The column menu's **Manage columns** action. */
+    openColumnsPanel: () => void;
+}
+
+/**
+ * Opens the Columns panel for the column menu: in the toolbar when a `GridToolbar` has registered
+ * through `GridToolbarHostContext`, otherwise as the standalone panel, which closes on Escape or a
+ * mousedown outside it.
+ */
+export function useGridColumnsPanel(): UseGridColumnsPanelResult {
+    const [toolbarPanelRequested, setToolbarPanelRequested] = useState(false);
+    const [standalonePanelOpen, setStandalonePanelOpen] = useState(false);
+    const standalonePanelRef = useRef<HTMLDivElement>(null);
+    const toolbarHostCountRef = useRef(0);
+
+    const toolbarHost = useMemo<GridToolbarHost>(() => ({
+        registerColumnsPanel: () => {
+            toolbarHostCountRef.current += 1;
+            return () => { toolbarHostCountRef.current -= 1; };
+        },
+    }), []);
+
+    const openColumnsPanel = useCallback(() => {
+        if (toolbarHostCountRef.current > 0) {
+            setToolbarPanelRequested(true);
+        } else {
+            setStandalonePanelOpen(true);
+        }
+    }, []);
+
+    const closeToolbarPanel = useCallback(() => setToolbarPanelRequested(false), []);
+    const closeStandalonePanel = useCallback(() => setStandalonePanelOpen(false), []);
+
+    useEffect(() => {
+        if (!standalonePanelOpen) return;
+        function handleMouseDown(e: MouseEvent) {
+            if (standalonePanelRef.current && !standalonePanelRef.current.contains(e.target as Node)) {
+                setStandalonePanelOpen(false);
+            }
+        }
+        function handleKeyDown(e: KeyboardEvent) {
+            if (e.key === 'Escape') setStandalonePanelOpen(false);
+        }
+        document.addEventListener('mousedown', handleMouseDown);
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('mousedown', handleMouseDown);
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [standalonePanelOpen]);
+
+    return {
+        toolbarHost,
+        toolbarPanelRequested,
+        closeToolbarPanel,
+        standalonePanelOpen,
+        closeStandalonePanel,
+        standalonePanelRef,
+        openColumnsPanel,
+    };
+}

package/lib/hooks/core/useGridControlledState.ts

@@ -1,13 +1,16 @@
-import { useState, useCallback, useMemo } from 'react';
+import { useState, useCallback, useMemo, useLayoutEffect, useRef } from 'react';
 import type {
     GridRowId,
     GridSortItem,
+    GridFilterModel,
     GridColumnPinning,
     GridPaginationModel,
     GridAggregationModel,
     GridPivotModel,
 } from '../../types';
-import type { GridInitialState } from '../../state/types';
+import type { GridInitialState, GridDensityState } from '../../state/types';
+
+export type GridDensity = GridDensityState['density'];
 
 export interface UseGridControlledStateParams {
     initialState?: GridInitialState;
@@ -15,6 +18,9 @@ export interface UseGridControlledStateParams {
     sortModel?: GridSortItem[];
     onSortModelChange?: (model: GridSortItem[]) => void;
 
+    filterModel?: GridFilterModel;
+    onFilterModelChange?: (model: GridFilterModel) => void;
+
     aggregationModel?: GridAggregationModel;
     onAggregationModelChange?: (model: GridAggregationModel) => void;
 
@@ -29,9 +35,13 @@ export interface UseGridControlledStateParams {
 
     paginationModel?: GridPaginationModel;
     onPaginationModelChange?: (model: GridPaginationModel) => void;
+    /** Used to pick the uncontrolled default page size: 100 when offered, else the first option. */
+    pageSizeOptions?: number[];
 
     rowSelectionModel?: GridRowId[];
     onRowSelectionModelChange?: (model: GridRowId[]) => void;
+
+    density?: GridDensity;
 }
 
 export interface UseGridControlledStateReturn {
@@ -39,6 +49,14 @@ export interface UseGridControlledStateReturn {
     sortModel: GridSortItem[];
     isSortControlled: boolean;
     setInternalSortModel: React.Dispatch<React.SetStateAction<GridSortItem[]>>;
+    /** Sets the internal model when uncontrolled and fires onSortModelChange. */
+    handleSortModelChange: (model: GridSortItem[]) => void;
+
+    // filter
+    filterModel: GridFilterModel;
+    isFilterControlled: boolean;
+    /** Sets the internal model when uncontrolled and fires onFilterModelChange. */
+    handleFilterModelChange: (model: GridFilterModel) => void;
 
     // aggregation
     aggregationModel: GridAggregationModel;
@@ -65,14 +83,37 @@ export interface UseGridControlledStateReturn {
     selectedRowIds: Set<GridRowId>;
     isSelectionControlled: boolean;
     setInternalRowSelectionModel: React.Dispatch<React.SetStateAction<GridRowId[]>>;
+    /** Sets the internal model when uncontrolled and fires onRowSelectionModelChange. */
+    handleRowSelectionModelChange: (model: GridRowId[]) => void;
+    /**
+     * The model passed to `handleRowSelectionModelChange` since the last commit, or null when
+     * there is none: a change made in this tick that has not rendered yet (read from
+     * onRowSelectionModelChange or right after apiRef.selectRows). Stable identity.
+     */
+    getPendingRowSelectionModel: () => GridRowId[] | null;
+
+    // density (prop, else initialState.density, else 'standard')
+    density: GridDensity;
 }
 
 const EMPTY_PIVOT_MODEL: GridPivotModel = { rowFields: [], columnFields: [], valueFields: [] };
+const DEFAULT_PAGE_SIZE = 100;
+
+/** The uncontrolled page size must be one the page-size select can show. */
+export function getDefaultPageSize(pageSizeOptions?: number[]): number {
+    if (!pageSizeOptions || pageSizeOptions.length === 0 || pageSizeOptions.includes(DEFAULT_PAGE_SIZE)) {
+        return DEFAULT_PAGE_SIZE;
+    }
+    return pageSizeOptions[0];
+}
 
 export function useGridControlledState(params: UseGridControlledStateParams): UseGridControlledStateReturn {
     const {
         initialState,
         sortModel: propSortModel,
+        onSortModelChange,
+        filterModel: propFilterModel,
+        onFilterModelChange,
         aggregationModel: propAggregationModel,
         onAggregationModelChange,
         columnVisibilityModel: propColumnVisibilityModel,
@@ -83,8 +124,10 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         onPivotModelChange,
         paginationModel: propPaginationModel,
         onPaginationModelChange,
+        pageSizeOptions,
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange,
+        density: propDensity,
     } = params;
 
     // ── Sort ─────────────────────────────────────────────────────────────────
@@ -94,12 +137,36 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
     const isSortControlled = propSortModel !== undefined;
     const sortModel = isSortControlled ? propSortModel! : internalSortModel;
 
+    const handleSortModelChange = useCallback((model: GridSortItem[]) => {
+        if (!isSortControlled) setInternalSortModel(model);
+        onSortModelChange?.(model);
+    }, [isSortControlled, onSortModelChange]);
+
+    // ── Filter ───────────────────────────────────────────────────────────────
+    const [internalFilterModel, setInternalFilterModel] = useState<GridFilterModel>(
+        () => initialState?.filter?.filterModel ?? { items: [] }
+    );
+    // `!= null` so a JS consumer's `filterModel={null}` behaves like "not passed", as before.
+    const isFilterControlled = propFilterModel != null;
+    const filterModel = isFilterControlled ? propFilterModel : internalFilterModel;
+
+    const handleFilterModelChange = useCallback((model: GridFilterModel) => {
+        if (!isFilterControlled) setInternalFilterModel(model);
+        onFilterModelChange?.(model);
+    }, [isFilterControlled, onFilterModelChange]);
+
     // ── Aggregation ──────────────────────────────────────────────────────────
     const isAggregationControlled = propAggregationModel !== undefined;
     const [internalAggregationModel, setInternalAggregationModel] = useState<GridAggregationModel>(
         () => propAggregationModel ?? {}
     );
-    const aggregationModel = isAggregationControlled ? propAggregationModel! : internalAggregationModel;
+    // Identity follows content: `aggregationModel={{ salary: 'sum' }}` is a new object on every parent
+    // render, and the fetches and memos keyed on the model must not rerun for an unchanged model.
+    const aggregationModelKey = JSON.stringify(isAggregationControlled ? propAggregationModel! : internalAggregationModel);
+    const aggregationModel = useMemo<GridAggregationModel>(
+        () => JSON.parse(aggregationModelKey) as GridAggregationModel,
+        [aggregationModelKey],
+    );
 
     const handleAggregationModelChange = useCallback((model: GridAggregationModel) => {
         if (!isAggregationControlled) setInternalAggregationModel(model);
@@ -146,7 +213,7 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
     // ── Pagination ───────────────────────────────────────────────────────────
     const isPaginationControlled = propPaginationModel !== undefined;
     const [internalPaginationModel, setInternalPaginationModel] = useState<GridPaginationModel>(
-        () => initialState?.pagination?.paginationModel ?? propPaginationModel ?? { page: 0, pageSize: 100 }
+        () => initialState?.pagination?.paginationModel ?? propPaginationModel ?? { page: 0, pageSize: getDefaultPageSize(pageSizeOptions) }
     );
     const effectivePaginationModel = isPaginationControlled ? propPaginationModel : internalPaginationModel;
 
@@ -161,13 +228,35 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
     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;
+    // Cleared on every commit: the rendered model is current again (a controlled parent may
+    // also have rejected the change).
+    const pendingRowSelectionRef = useRef<GridRowId[] | null>(null);
+    useLayoutEffect(() => {
+        pendingRowSelectionRef.current = null;
+    });
+    const getPendingRowSelectionModel = useCallback(() => pendingRowSelectionRef.current, []);
+
+    const handleRowSelectionModelChange = useCallback((model: GridRowId[]) => {
+        pendingRowSelectionRef.current = model;
+        if (!isSelectionControlled) setInternalRowSelectionModel(model);
+        onRowSelectionModelChange?.(model);
+    }, [isSelectionControlled, onRowSelectionModelChange]);
+
+    // ── Density ──────────────────────────────────────────────────────────────
+    // No built-in density UI exists, so there is no internal setter: the prop wins,
+    // otherwise the persisted/initial density applies.
+    const [initialDensity] = useState<GridDensity>(() => initialState?.density?.density ?? 'standard');
+    const density = propDensity ?? initialDensity;
 
     return {
         sortModel: sortModel as GridSortItem[],
         isSortControlled,
         setInternalSortModel: setInternalSortModel as React.Dispatch<React.SetStateAction<GridSortItem[]>>,
+        handleSortModelChange,
+
+        filterModel,
+        isFilterControlled,
+        handleFilterModelChange,
 
         aggregationModel,
         handleAggregationModelChange,
@@ -188,5 +277,9 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         selectedRowIds,
         isSelectionControlled,
         setInternalRowSelectionModel,
+        handleRowSelectionModelChange,
+        getPendingRowSelectionModel,
+
+        density,
     };
 }

package/lib/hooks/core/useGridDetailPanel.ts

@@ -0,0 +1,51 @@
+import { useCallback, useMemo, useState } from 'react';
+import { useDetailPanelHeights } from '../features/useDetailPanelHeights';
+import { getDetailPanelRowIds } from '../../utils/detailPanel';
+import type { GridRowId, GridRowMeta } from '../../types';
+
+export interface UseGridDetailPanelParams {
+    /** Whether `getDetailPanelContent` was passed: the grid then has an expand column. */
+    hasDetailPanel: boolean;
+    /** `detailPanelExpandedRowIds` prop (controlled when defined). */
+    controlledExpandedRowIds: Set<GridRowId> | undefined;
+    onDetailPanelExpandedRowIdsChange: ((expandedRowIds: Set<GridRowId>) => void) | undefined;
+    rowMetaMap: Map<GridRowId, GridRowMeta>;
+}
+
+export interface UseGridDetailPanelResult {
+    hasDetailPanel: boolean;
+    /** What renders and is laid out: synthetic group rows never show a detail panel. */
+    expandedRowIds: Set<GridRowId>;
+    handleDetailPanelToggle: (rowId: GridRowId) => void;
+    /** Measured heights of `'auto'` panels. */
+    detailPanelHeights: Map<GridRowId, number>;
+    reportDetailPanelHeight: (rowId: GridRowId, height: number) => void;
+}
+
+/** Detail-panel expansion (controlled or uncontrolled) and the measured heights of `'auto'` panels. */
+export function useGridDetailPanel(params: UseGridDetailPanelParams): UseGridDetailPanelResult {
+    const { hasDetailPanel, controlledExpandedRowIds, onDetailPanelExpandedRowIdsChange, rowMetaMap } = params;
+
+    const [internalExpandedRowIds, setInternalExpandedRowIds] = useState<Set<GridRowId>>(new Set());
+    const requestedExpandedRowIds = controlledExpandedRowIds ?? internalExpandedRowIds;
+    const expandedRowIds = useMemo(() => getDetailPanelRowIds(requestedExpandedRowIds, rowMetaMap), [requestedExpandedRowIds, rowMetaMap]);
+
+    const handleDetailPanelToggle = useCallback((rowId: GridRowId) => {
+        // Synthetic group / subtotal rows have no detail panel (keyboard Space on the expand cell lands here too).
+        if (rowMetaMap.get(rowId)?.isGroupRow) return;
+        const newExpandedRowIds = new Set(requestedExpandedRowIds);
+        if (newExpandedRowIds.has(rowId)) {
+            newExpandedRowIds.delete(rowId);
+        } else {
+            newExpandedRowIds.add(rowId);
+        }
+        if (controlledExpandedRowIds === undefined) {
+            setInternalExpandedRowIds(newExpandedRowIds);
+        }
+        onDetailPanelExpandedRowIdsChange?.(newExpandedRowIds);
+    }, [requestedExpandedRowIds, rowMetaMap, controlledExpandedRowIds, onDetailPanelExpandedRowIdsChange]);
+
+    const { detailPanelHeights, reportDetailPanelHeight } = useDetailPanelHeights();
+
+    return { hasDetailPanel, expandedRowIds, handleDetailPanelToggle, detailPanelHeights, reportDetailPanelHeight };
+}

package/lib/hooks/core/useGridDevWarnings.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef } from 'react';
+import type { RefObject } from 'react';
 
 export interface UseGridDevWarningsParams {
     paginationRequested: boolean;
@@ -7,15 +8,73 @@ export interface UseGridDevWarningsParams {
     viewportHeight: number;
     renderedRowCount: number;
     totalRowCount: number;
+    /** `pinnedRows` is set while tree data or row grouping is active, where it has no effect. */
+    pinnedRowsIgnored?: boolean;
+    /** Pixel height of the scrollable content. */
+    scrollHeight?: number;
+    /** `listView` is set but `listViewColumn` is not, so the grid view is shown. */
+    listViewWithoutColumn?: boolean;
+    /** Number of items the list view renders (0 when the list view is not shown). It does not virtualize. */
+    listViewRowCount?: number;
 }
 
 // Below this many rows, rendering everything is harmless, so an unbounded container is not worth a warning.
 const UNBOUNDED_WARN_THRESHOLD = 200;
 
+/** The list view renders every item; above this many the page slows down noticeably. */
+export const LIST_VIEW_WARN_THRESHOLD = 2000;
+
+/**
+ * Browsers cap element heights (Firefox at about 17.9M px, Chromium and Safari at about 33.5M px):
+ * rows laid out below the cap cannot be scrolled to.
+ */
+export const MAX_SCROLLABLE_HEIGHT = 17_800_000;
+
 export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
-    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount } = params;
+    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
     const warnedPaginationRef = useRef(false);
     const warnedUnboundedRef = useRef(false);
+    const warnedPinnedRowsRef = useRef(false);
+    const warnedHeightRef = useRef(false);
+    const warnedListViewRef = useRef(false);
+    const warnedListViewSizeRef = useRef(false);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedListViewSizeRef.current || listViewRowCount <= LIST_VIEW_WARN_THRESHOLD) return;
+        warnedListViewSizeRef.current = true;
+        console.warn(
+            `[OpenGridX] The list view is rendering all ${listViewRowCount} items: it does not virtualize. ` +
+            'Above a few thousand items use `pagination`, server-side loading, or the grid view. See docs/features/list-view.md.'
+        );
+    }, [listViewRowCount]);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedListViewRef.current || !listViewWithoutColumn) return;
+        warnedListViewRef.current = true;
+        console.warn(
+            '[OpenGridX] `listView` is set without a `listViewColumn`, so the grid view is shown instead. ' +
+            'Pass `listViewColumn` to render list items. See docs/features/list-view.md.'
+        );
+    }, [listViewWithoutColumn]);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedPinnedRowsRef.current || !pinnedRowsIgnored) return;
+        warnedPinnedRowsRef.current = true;
+        console.warn(
+            '[OpenGridX] `pinnedRows` is ignored while treeData or rowGroupingModel is active: the rows stay in their ' +
+            'place in the hierarchy. See docs/features/pinning.md.'
+        );
+    }, [pinnedRowsIgnored]);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedHeightRef.current || scrollHeight <= MAX_SCROLLABLE_HEIGHT) return;
+        warnedHeightRef.current = true;
+        console.warn(
+            `[OpenGridX] The grid content is ${Math.round(scrollHeight)}px tall. Browsers cap element heights ` +
+            '(about 17.9M px in Firefox, 33.5M px in Chrome and Safari), so the last rows may not be reachable by scrolling. ' +
+            'Use pagination, server-side or infinite loading, or a smaller rowHeight. See docs/features/virtualization.md.'
+        );
+    }, [scrollHeight]);
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedPaginationRef.current) return;
@@ -30,13 +89,53 @@ export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedUnboundedRef.current || autoHeight) return;
-        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount) {
+        // Really unbounded: every row is rendered and the viewport is at least as tall as the rows, so it never scrolls.
+        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount && viewportHeight >= scrollHeight) {
             warnedUnboundedRef.current = true;
             console.warn(
                 `[OpenGridX] The grid viewport is ${Math.round(viewportHeight)}px tall and is rendering all ${totalRowCount} rows, ` +
-                'so row virtualization is effectively off. The grid container has no bounded height: it grows to fit its ' +
-                'content. Give it a fixed height, or if it is a flex child add `min-height: 0`. See docs/features/virtualization.md.'
+                'so row virtualization is effectively off: the grid fills its container, and the container grows to fit every row. ' +
+                'Give the container a definite height (for example `height: 600px` or `100vh`). If the container, or any ancestor ' +
+                'up to the sized one, is a flex or grid item, add `min-height: 0` to it. Alternatively pass a `height` prop, ' +
+                'or `autoHeight` if rendering every row is intended. See docs/features/virtualization.md.'
             );
         }
-    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount]);
+    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount, scrollHeight]);
+}
+
+/**
+ * True when the grid's stylesheet does not reach `root` (the `.ogx` element). The stylesheet lays the
+ * root out as a flex column; without it the root is a plain block and the viewport does not scroll.
+ * jsdom applies no library CSS, so it is never reported there.
+ */
+export function isGridStylesheetMissing(root: HTMLElement): boolean {
+    if (typeof window === 'undefined' || typeof window.getComputedStyle !== 'function') return false;
+    if (typeof navigator !== 'undefined' && /jsdom/i.test(navigator.userAgent)) return false;
+    return window.getComputedStyle(root).display !== 'flex';
+}
+
+let warnedStylesheet = false;
+
+/**
+ * Dev-only: warns once per page when a grid renders without `@opencorestack/opengridx/styles`.
+ * The JS bundle does not load the stylesheet, and without it the viewport grows to fit every row,
+ * which silently turns virtualization off.
+ */
+export function useGridStylesheetWarning(rootRef: RefObject<HTMLElement | null>): void {
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedStylesheet) return;
+        const root = rootRef.current;
+        if (!root || !isGridStylesheetMissing(root)) return;
+        warnedStylesheet = true;
+        console.warn(
+            '[OpenGridX] The grid stylesheet is not loaded, so the grid is unstyled and renders every row ' +
+            "(its viewport does not scroll). Add `import '@opencorestack/opengridx/styles'` once in your app root. " +
+            'See README.md, Getting Started.'
+        );
+    }, [rootRef]);
+}
+
+/** Test helper: lets the stylesheet warning fire again. */
+export function resetGridStylesheetWarning(): void {
+    warnedStylesheet = false;
 }

package/lib/hooks/core/useGridFocusHandlers.ts

@@ -0,0 +1,50 @@
+import { useCallback } from 'react';
+import type { RefObject } from 'react';
+import type { FocusedCell } from '../../utils/focus';
+import type { GridCellParams, GridRowId, GridRowModel } from '../../types';
+
+/**
+ * Keyboard-mode flag: toggled via a DOM class name on the grid root, with no React state, so
+ * the focus ring appears instantly without a re-render cycle.
+ */
+export function useGridKeyboardMode(containerRef: RefObject<HTMLDivElement | null>): (on: boolean) => void {
+    return useCallback((on: boolean) => {
+        containerRef.current?.classList.toggle('ogx--kb', on);
+    }, [containerRef]);
+}
+
+export interface UseGridPointerFocusHandlersParams<R extends GridRowModel> {
+    ensureGridFocus: () => void;
+    setKeyboardMode: (on: boolean) => void;
+    setFocusedCell: React.Dispatch<React.SetStateAction<FocusedCell | null>>;
+    getRowId: (row: GridRowModel) => GridRowId;
+    onCellClick: ((params: GridCellParams<R>) => void) | undefined;
+}
+
+export interface UseGridPointerFocusHandlersResult<R extends GridRowModel> {
+    handleCellClick: (params: GridCellParams<R>) => void;
+    handleHeaderClick: (field: string) => void;
+}
+
+/** Cell and header clicks move grid focus there and leave keyboard mode. */
+export function useGridPointerFocusHandlers<R extends GridRowModel>(
+    params: UseGridPointerFocusHandlersParams<R>
+): UseGridPointerFocusHandlersResult<R> {
+    const { ensureGridFocus, setKeyboardMode, setFocusedCell, getRowId, onCellClick } = params;
+
+    const handleCellClick = useCallback((cellParams: GridCellParams<R>) => {
+        // Focus stays where the click put it (the cell, or a control rendered inside it).
+        ensureGridFocus();
+        setKeyboardMode(false);
+        setFocusedCell({ id: getRowId(cellParams.row), field: cellParams.field, rowIndex: cellParams.rowIndex });
+        onCellClick?.(cellParams);
+    }, [onCellClick, setKeyboardMode, setFocusedCell, ensureGridFocus, getRowId]);
+
+    const handleHeaderClick = useCallback((field: string) => {
+        ensureGridFocus();
+        setFocusedCell({ id: null, field });
+        setKeyboardMode(false);
+    }, [ensureGridFocus, setFocusedCell, setKeyboardMode]);
+
+    return { handleCellClick, handleHeaderClick };
+}

package/lib/hooks/core/useGridGroupingColumn.ts

@@ -0,0 +1,62 @@
+import { useMemo } from 'react';
+import type { GridColDef, GridColumnPinning, GridRowModel } from '../../types';
+
+export interface UseGridGroupingColumnParams<R extends GridRowModel> {
+    /** The columns before the grouping column is added (the pivot's columns in pivot mode). */
+    baseColumns: GridColDef<R>[];
+    pinnedColumns: GridColumnPinning;
+    /** Show the synthetic `__group__` column (see `resolveGridModes`). */
+    hasGroupingColumn: boolean;
+    groupingColDef: Partial<GridColDef<R>> | undefined;
+    isTreeData: boolean;
+    getTreeDataPath: ((row: R) => string[]) | undefined;
+}
+
+export interface UseGridGroupingColumnResult<R extends GridRowModel> {
+    /** `baseColumns`, with the `__group__` column first when it is shown. */
+    activeColumns: GridColDef<R>[];
+    /** `pinnedColumns`, with `__group__` pinned first on the left when it is shown. */
+    effectivePinnedColumns: GridColumnPinning;
+}
+
+/**
+ * The dedicated `__group__` column that `groupingColDef` asks for while row grouping or tree
+ * data is active: prepended at position 0 and auto-pinned left.
+ *
+ * Both results MUST be memoized: a new array/object reference every render cascades through
+ * useRowGrouping's memos and effects into an infinite setState loop (Maximum update depth exceeded).
+ */
+export function useGridGroupingColumn<R extends GridRowModel>(
+    params: UseGridGroupingColumnParams<R>
+): UseGridGroupingColumnResult<R> {
+    const { baseColumns, pinnedColumns, hasGroupingColumn, groupingColDef, isTreeData, getTreeDataPath } = params;
+
+    const effectivePinnedColumns = useMemo(() => (
+        hasGroupingColumn
+            ? { ...pinnedColumns, left: ['__group__', ...((pinnedColumns?.left ?? []).filter(f => f !== '__group__'))] }
+            : pinnedColumns
+    ), [hasGroupingColumn, pinnedColumns]);
+
+    const activeColumns = useMemo(() => (
+        hasGroupingColumn
+            ? [
+                {
+                    headerName: 'Group',
+                    width: 220,
+                    // Tree data: a row's own entry in the hierarchy is the last segment of its path.
+                    ...(isTreeData && getTreeDataPath ? { valueGetter: ({ row }: { row: R }) => { const path = getTreeDataPath(row); return path[path.length - 1]; } } : {}),
+                    ...groupingColDef,
+                    field: '__group__',
+                    hideable: false,
+                    sortable: false,
+                    filterable: false,
+                    pinnable: false,
+                    exportable: false,
+                } as unknown as GridColDef<R>,
+                ...baseColumns,
+              ]
+            : baseColumns
+    ), [groupingColDef, hasGroupingColumn, isTreeData, getTreeDataPath, baseColumns]);
+
+    return { activeColumns, effectivePinnedColumns };
+}