@opencorestack/opengridx 2.1.0 → 3.0.1

package/lib/hooks/core/useGridAriaRows.ts

@@ -0,0 +1,38 @@
+import { useMemo } from 'react';
+import { getAriaRowLayout, type GridAriaRowLayout } from '../../utils/aria';
+import { getColumnGroupDepth } from '../../utils/columnGroups';
+import type { GridColumnGroupingModel, GridPaginationModel } from '../../types';
+
+export interface UseGridAriaRowsParams {
+    columnGroupingModel: GridColumnGroupingModel | undefined;
+    pinnedTopCount: number;
+    pinnedBottomCount: number;
+    pagination: boolean;
+    paginationMode: 'client' | 'server' | 'infinite';
+    paginationModel: GridPaginationModel;
+    /** What the pager pages through (see `getPaginationRowCount`). */
+    paginationRowCount: number;
+    paginatedUnpinnedRowCount: number;
+    sortedUnpinnedRowCount: number;
+}
+
+/** `aria-rowcount` and the `aria-rowindex` bases of the pinned and centre rows. */
+export function useGridAriaRows(params: UseGridAriaRowsParams): GridAriaRowLayout {
+    const {
+        columnGroupingModel, pinnedTopCount, pinnedBottomCount, pagination, paginationMode, paginationModel,
+        paginationRowCount, paginatedUnpinnedRowCount, sortedUnpinnedRowCount,
+    } = params;
+    const { page, pageSize } = paginationModel;
+
+    return useMemo(() => getAriaRowLayout({
+        headerRowCount: 1 + getColumnGroupDepth(columnGroupingModel),
+        pinnedTopCount,
+        pinnedBottomCount,
+        pageRowCount: pagination ? paginatedUnpinnedRowCount : sortedUnpinnedRowCount,
+        totalCenterRowCount: pagination && paginationMode === 'server'
+            ? Math.max(paginationRowCount, paginatedUnpinnedRowCount)
+            : sortedUnpinnedRowCount,
+        pageOffset: pagination ? page * pageSize : 0,
+    }), [columnGroupingModel, pinnedTopCount, pinnedBottomCount, pagination, paginatedUnpinnedRowCount,
+        sortedUnpinnedRowCount, paginationMode, paginationRowCount, page, pageSize]);
+}

package/lib/hooks/core/useGridClipboardApi.ts

@@ -0,0 +1,38 @@
+import { useCallback, useLayoutEffect } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import { useGridClipboard } from '../features/useGridClipboard';
+import type { GridApi, GridColDef, GridRowId, GridRowModel } from '../../types';
+
+export interface UseGridClipboardApiParams {
+    apiRef: MutableRefObject<GridApi>;
+    /** The rendered data columns, in screen order. */
+    columns: GridColDef[];
+    getRowId: (row: GridRowModel) => GridRowId;
+    /** The grid root: Ctrl/Cmd+C only copies while focus is inside it. */
+    containerRef: RefObject<HTMLDivElement | null>;
+    disableKeyboardShortcut: boolean;
+}
+
+/**
+ * Copies the selected rows (every page, collapsed groups, pinned rows) with the on-screen columns
+ * in screen order, on Ctrl/Cmd+C while focus is inside this grid, and installs `copySelectedRows`
+ * on the API for programmatic use.
+ */
+export function useGridClipboardApi(params: UseGridClipboardApiParams): void {
+    const { apiRef, columns, getRowId, containerRef, disableKeyboardShortcut } = params;
+
+    const getGridRootElement = useCallback(() => containerRef.current, [containerRef]);
+    const { copySelectedRows } = useGridClipboard({
+        getSelectedRowIds: () => apiRef.current.getSelectedRows(),
+        getColumns: () => columns,
+        getRows: () => apiRef.current.getAllFilteredRows(),
+        getRowId,
+        getRootElement: getGridRootElement,
+        disableKeyboardShortcut,
+    });
+
+    // Stable identity.
+    useLayoutEffect(() => {
+        apiRef.current.copySelectedRows = copySelectedRows;
+    }, [copySelectedRows, apiRef]);
+}

package/lib/hooks/core/useGridColumnLookup.ts

@@ -0,0 +1,30 @@
+import { useMemo } from 'react';
+import type { GridColDef, GridRowModel } from '../../types';
+import { buildColumnLookup, type GridColumnLookup } from '../../utils/columnLookup';
+
+const SEPARATOR = '\u0000';
+
+/**
+ * The column lookup used by client-side filtering, sorting and the quick filter.
+ *
+ * Its identity changes only when the columns change or the set of hidden columns changes, so an
+ * inline `columnVisibilityModel` object (a new reference on every parent render) does not re-run
+ * the filter and sort passes.
+ */
+export function useGridColumnLookup<R extends GridRowModel>(
+    columns: GridColDef<R>[],
+    columnVisibilityModel: Record<string, boolean>,
+): GridColumnLookup {
+    const hiddenFieldsKey = columns
+        .filter(col => columnVisibilityModel[col.field] === false)
+        .map(col => col.field)
+        .join(SEPARATOR);
+
+    return useMemo(() => {
+        const hidden: Record<string, boolean> = {};
+        if (hiddenFieldsKey) {
+            for (const field of hiddenFieldsKey.split(SEPARATOR)) hidden[field] = false;
+        }
+        return buildColumnLookup(columns as unknown as GridColDef[], hidden);
+    }, [columns, hiddenFieldsKey]);
+}

package/lib/hooks/core/useGridColumns.tsx

@@ -1,12 +1,18 @@
 import { useState, useMemo, useCallback, useEffect } from 'react';
 import { useColumnReorder } from '../useColumnReorder';
 import { ExpandIcon } from '../../components/ui/ExpandIcon';
+import { isColumnPinned } from '../../utils/pinning';
+import { formatAggregateForColumn } from '../../utils/aggregation';
+import { CellErrorBoundary } from '../../components/Cell/CellErrorBoundary';
+import { CHECKBOX_FIELD, EXPAND_FIELD, REORDER_FIELD } from '../../utils/focus';
 import type {
     GridColDef,
     GridRowModel,
     GridRowId,
     GridColumnOrderChangeParams,
+    GridColumnPinning,
     GridRenderCellParams,
+    GridAggregationModel,
 } from '../../types';
 import type { GridInitialState } from '../../state/types';
 
@@ -14,11 +20,119 @@ interface HierarchyHandlers {
     toggleExpansion: (id: GridRowId) => void;
 }
 
+// A group row carries each column's aggregate in the column's field. It is shown like the footer
+// shows totals: the stored aggregate (a valueGetter would recompute it from fields a group row does
+// not have), formatted with formatAggregateForColumn (so a count is never put in a currency format).
+function withGroupRowAggregates<R extends GridRowModel>(
+    col: GridColDef<R>,
+    fnName: string | undefined,
+    groupingRows: ReadonlyMap<GridRowId, unknown> | undefined,
+): Pick<GridColDef<R>, 'valueGetter' | 'valueFormatter'> {
+    if (!fnName || !groupingRows) return { valueGetter: col.valueGetter, valueFormatter: col.valueFormatter };
+    const isGroupRow = (row: R) => groupingRows.has(row.id);
+    const ownGetter = col.valueGetter;
+    const ownFormatter = col.valueFormatter;
+    return {
+        valueGetter: ownGetter
+            ? (p) => (isGroupRow(p.row) ? p.value : ownGetter(p))
+            : undefined,
+        valueFormatter: (p) => {
+            if (isGroupRow(p.row)) return formatAggregateForColumn(p.value, fnName, col, p.row);
+            if (ownFormatter) return ownFormatter(p);
+            return p.value == null ? '' : String(p.value);
+        },
+    };
+}
+
+/**
+ * Columns in render order: left-pinned in `pinnedColumns.left` order, unpinned in column order,
+ * right-pinned in `pinnedColumns.right` order — the order useLayout renders them in.
+ */
+function inPinnedRenderOrder<C extends { field: string }>(columns: C[], pinnedColumns?: GridColumnPinning): C[] {
+    if (!pinnedColumns) return columns;
+    const left = pinnedColumns.left ?? [];
+    const right = pinnedColumns.right ?? [];
+    const rank = (col: C) => {
+        const side = isColumnPinned(col.field, pinnedColumns);
+        if (side === 'left') return left.indexOf(col.field) - left.length;
+        if (side === 'right') return 1 + right.indexOf(col.field);
+        return 0;
+    };
+    return [...columns].sort((a, b) => rank(a) - rank(b));
+}
+
 // Injected hierarchy renderers replace the plain-cell path in Cell, so they must
 // render the formatted value themselves or valueFormatter is silently lost.
 const displayValue = <R extends GridRowModel>(cellParams: GridRenderCellParams<R>): React.ReactNode =>
     cellParams.formattedValue ?? (cellParams.value as React.ReactNode);
 
+interface ConsumerCellResult {
+    useDefault: boolean;
+    content?: React.ReactNode;
+}
+
+/**
+ * Calls the consumer's renderCell for a hierarchy column cell. For a synthetic row (group, subtotal or
+ * auto-created tree parent) a result of `undefined` means "use the grid's default content". In the
+ * hierarchy column the output is wrapped in its own error boundary, so a renderCell that fails on a
+ * group row shows the error icon next to the expand toggle instead of replacing the toggle.
+ */
+function renderConsumerCell<R extends GridRowModel>(
+    col: GridColDef<R>,
+    cellParams: GridRenderCellParams<R>,
+    isolate: boolean,
+): ConsumerCellResult {
+    const renderCell = col.renderCell;
+    if (!renderCell) return { useDefault: true };
+    const isSynthetic = Boolean(cellParams.rowMeta?.isGroupRow);
+    if (!isolate) {
+        const output = renderCell(cellParams);
+        return isSynthetic && output === undefined ? { useDefault: true } : { useDefault: false, content: output };
+    }
+    let output: React.ReactNode;
+    try {
+        output = renderCell(cellParams);
+    } catch (error) {
+        return {
+            useDefault: false,
+            content: <CellErrorBoundary field={col.field} resetKey={cellParams.row} renderFn={() => { throw error; }} />,
+        };
+    }
+    if (isSynthetic && output === undefined) return { useDefault: true };
+    return { useDefault: false, content: <CellErrorBoundary field={col.field} resetKey={cellParams.row} renderFn={() => output} /> };
+}
+
+/** What the hierarchy column shows without a consumer renderCell (or when it returns undefined for a synthetic row). */
+function defaultHierarchyContent<R extends GridRowModel>(
+    cellParams: GridRenderCellParams<R>,
+    isRowGrouping: boolean,
+    isTreeData: boolean,
+): React.ReactNode {
+    const meta = cellParams.rowMeta;
+    if (!meta?.isGroupRow) return displayValue(cellParams);
+    // A subtotal row carries only aggregates; its label column stays empty.
+    if (meta.isGroupFooter) return null;
+    const descendantCount = meta.descendantCount;
+    if (isRowGrouping && meta.hasChildren) {
+        const groupLabel = meta.groupLabel ?? `${meta.groupingField}: ${String(meta.groupingValue)}`;
+        return (
+            <div className="ogx__group-cell-content">
+                {groupLabel}
+                {descendantCount !== undefined ? ` (${descendantCount})` : ''}
+            </div>
+        );
+    }
+    if (isTreeData) {
+        return (
+            <div className="ogx__group-cell-content">
+                {meta.groupLabel}
+                {descendantCount !== undefined && descendantCount > 0 ? ` (${descendantCount})` : ''}
+            </div>
+        );
+    }
+    return displayValue(cellParams);
+}
+
 export interface UseGridColumnsParams<R extends GridRowModel> {
     activeColumns: GridColDef<R>[];
     isHierarchyEnabled: boolean;
@@ -28,6 +142,8 @@ export interface UseGridColumnsParams<R extends GridRowModel> {
     columnVisibilityModel: Record<string, boolean>;
     columnOrder?: string[];
     onColumnOrderChange?: (params: GridColumnOrderChangeParams) => void;
+    /** Receives the whole new column order after every reorder and reset (not in pivot mode). */
+    onColumnOrderModelChange?: (columnOrder: string[]) => void;
     disableColumnReorder: boolean;
     pivotMode: boolean;
     checkboxSelection: boolean;
@@ -35,17 +151,37 @@ export interface UseGridColumnsParams<R extends GridRowModel> {
     rowReordering: boolean;
     initialState?: GridInitialState;
     setColumns: (cols: GridColDef[]) => void;
+    pinnedColumns?: GridColumnPinning;
+    /** Resolves a row's id (getRowId) when the injected expand toggle is clicked; defaults to `row.id`. */
+    getRowId?: (row: R) => GridRowId;
+    /** Formats the aggregates on row-grouping group rows. */
+    aggregationModel?: GridAggregationModel;
+    /** Row grouping only: the synthetic group rows, keyed by id. */
+    groupingRows?: ReadonlyMap<GridRowId, unknown>;
 }
 
+const defaultGetRowId = <R extends GridRowModel>(row: R): GridRowId => row.id;
+
 export interface UseGridColumnsResult<R extends GridRowModel> {
     effectiveColumns: GridColDef<R>[];
+    /** Tree data / row grouping: the column that shows the expand toggle, indent and group labels. */
+    hierarchyField: string | undefined;
     orderedColumns: GridColDef<R>[];
     visibleOrderedColumns: GridColDef<R>[];
-    navigationColumns: Array<GridColDef<R> | { field: string }>;
+    /** Visible data columns in render order: left-pinned, unpinned, right-pinned (`apiRef.getVisibleColumns`). */
+    renderOrderedColumns: GridColDef<R>[];
+    /** Focusable columns in render order: system columns, then the visible data columns (left-pinned, unpinned, right-pinned). */
+    navigationColumns: Array<GridColDef<R> | { field: string; sortable: false; editable: false }>;
+    /** Position of each visible data column in render order (system columns excluded): the public `colIndex`. */
+    columnIndexMap: Map<string, number>;
     columnWidths: Record<string, number>;
     effectiveColumnOrder: string[];
     setInternalColumnOrder: React.Dispatch<React.SetStateAction<string[]>>;
     columnReorderHandlers: ReturnType<typeof useColumnReorder>;
+    /** Moves `fromField` to the position of `toField` in the column order (Columns panel drag). */
+    moveColumn: (fromField: string, toField: string) => void;
+    /** Restores the columns' definition order. */
+    resetColumnOrder: () => void;
     handleColumnResize: (field: string, newWidth: number) => void;
 }
 
@@ -61,6 +197,7 @@ export function useGridColumns<R extends GridRowModel>(
         columnVisibilityModel,
         columnOrder,
         onColumnOrderChange,
+        onColumnOrderModelChange,
         disableColumnReorder,
         pivotMode,
         checkboxSelection,
@@ -68,59 +205,95 @@ export function useGridColumns<R extends GridRowModel>(
         rowReordering,
         initialState,
         setColumns,
+        pinnedColumns,
+        getRowId = defaultGetRowId,
+        aggregationModel,
+        groupingRows,
     } = params;
 
+    // ── Column order ──────────────────────────────────────────────────────────
+    const naturalOrder = useMemo(() => activeColumns.map(col => col.field), [activeColumns]);
+
+    // null = the columns' own order, until the user reorders. Deriving it (instead of snapshotting the
+    // columns at mount) keeps it right when the grid mounts in pivot mode or the columns change.
+    const [storedColumnOrder, setStoredColumnOrder] = useState<string[] | null>(
+        () => initialState?.columns?.columnOrder ?? null
+    );
+
+    // Generated pivot columns keep an order of their own, so pivoting never rewrites the user's column
+    // order, and a controlled `columnOrder` (which names source columns) does not apply to them. It
+    // resets whenever the generated column set changes.
+    const pivotColumnsKey = pivotMode ? naturalOrder.join('\u0000') : '';
+    const [pivotOrderState, setPivotOrderState] = useState<{ key: string; order: string[] } | null>(null);
+    const pivotColumnOrder = pivotOrderState && pivotOrderState.key === pivotColumnsKey ? pivotOrderState.order : naturalOrder;
+
+    const internalColumnOrder = storedColumnOrder ?? naturalOrder;
+    const effectiveColumnOrder = pivotMode ? pivotColumnOrder : (columnOrder ?? internalColumnOrder);
+
+    const setInternalColumnOrder = useCallback<React.Dispatch<React.SetStateAction<string[]>>>((action) => {
+        if (pivotMode) {
+            setPivotOrderState(prev => {
+                const base = prev && prev.key === pivotColumnsKey ? prev.order : naturalOrder;
+                return { key: pivotColumnsKey, order: typeof action === 'function' ? action(base) : action };
+            });
+            return;
+        }
+        setStoredColumnOrder(prev => (typeof action === 'function' ? action(prev ?? naturalOrder) : action));
+    }, [pivotMode, pivotColumnsKey, naturalOrder]);
+
+    // In pivot mode the row-label columns (marked hideable: false) always show: the pivot rows are
+    // labelled by them, and they share their field with the source column a visibility model may hide.
+    const isColumnShown = useCallback(
+        (col: GridColDef<R>) => (pivotMode && col.hideable === false) || columnVisibilityModel[col.field] !== false,
+        [pivotMode, columnVisibilityModel],
+    );
+
+    // The expand toggle, indentation and group label go on the leftmost column actually
+    // on screen, so hiding, reordering or pinning columns never strips group rows of them.
+    // Mirrors the render order: left-pinned, then unpinned, then right-pinned.
+    const hierarchyField = useMemo<string | undefined>(() => {
+        if (!isHierarchyEnabled) return undefined;
+        const orderIndex = new Map(effectiveColumnOrder.map((field, idx) => [field, idx]));
+        const rank = (col: GridColDef<R>) => orderIndex.get(col.field) ?? activeColumns.indexOf(col);
+        const ordered = [...activeColumns].sort((a, b) => rank(a) - rank(b));
+        const onScreen = inPinnedRenderOrder(ordered.filter(col => columnVisibilityModel[col.field] !== false), pinnedColumns);
+        return (onScreen[0] ?? activeColumns[0])?.field;
+    }, [isHierarchyEnabled, effectiveColumnOrder, activeColumns, columnVisibilityModel, pinnedColumns]);
+
     // ── Effective columns (hierarchy cell renderer injection) ─────────────────
     const effectiveColumns = useMemo<GridColDef<R>[]>(() => {
         if (!isHierarchyEnabled) return activeColumns;
 
-        return activeColumns.map((col, index) => {
-            if (index === 0) {
+        const groupRows = isRowGrouping ? groupingRows : undefined;
+
+        return activeColumns.map((col) => {
+            const groupRowAggregates = withGroupRowAggregates(col, aggregationModel?.[col.field], groupRows);
+            if (col.field === hierarchyField) {
                 return {
                     ...col,
+                    ...groupRowAggregates,
                     renderCell: (cellParams: GridRenderCellParams<R>) => {
                         const meta = cellParams.rowMeta;
                         const depth = meta?.treeDepth ?? 0;
                         const hasChildren = Boolean(meta?.hasChildren);
                         const isExpanded = Boolean(meta?.isExpanded);
-                        const groupingField = meta?.groupingField;
-                        const groupingValue = meta?.groupingValue;
-                        const descendantCount = meta?.descendantCount;
-                        const isGroupRow = Boolean(meta?.isGroupRow);
-
-                        let content: React.ReactNode = col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
-
-                        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) {
-                            const groupLabel = meta?.groupLabel ?? `${groupingField}: ${String(groupingValue)}`;
-                            content = (
-                                <div className="ogx__group-cell-content">
-                                    {groupLabel}
-                                    {descendantCount !== undefined ? ` (${descendantCount})` : ''}
-                                </div>
-                            );
-                        }
+
+                        const custom = renderConsumerCell(col, cellParams, true);
+                        const content = custom.useDefault ? defaultHierarchyContent(cellParams, isRowGrouping, isTreeData) : custom.content;
 
                         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); }}
+                                            onClick={(e) => { e.stopPropagation(); e.preventDefault(); activeHierarchyHandlers?.toggleExpansion(getRowId(cellParams.row)); }}
                                             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); }}
+                                                tabIndex={-1}
+                                                onClick={(e) => { e.stopPropagation(); e.preventDefault(); activeHierarchyHandlers?.toggleExpansion(getRowId(cellParams.row)); }}
                                             />
                                         </div>
                                     ) : null}
@@ -134,24 +307,22 @@ export function useGridColumns<R extends GridRowModel>(
 
             return {
                 ...col,
+                ...groupRowAggregates,
                 renderCell: (cellParams: GridRenderCellParams<R>) => {
                     const meta = cellParams.rowMeta;
-                    const hasChildren = Boolean(meta?.hasChildren);
-                    const groupingField = meta?.groupingField;
-
-                    if (isRowGrouping && hasChildren) {
-                        if (col.field === groupingField) return null;
-                        if (cellParams.value !== undefined && cellParams.value !== null) {
-                            return col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
-                        }
-                        return null;
+                    if (!meta?.isGroupRow) {
+                        return col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
                     }
-
-                    return col.renderCell ? col.renderCell(cellParams) : displayValue(cellParams);
+                    // Synthetic rows: the consumer's renderCell decides; `undefined` keeps the default,
+                    // which is the aggregate (or nothing) and never the grouping value the label already shows.
+                    const custom = renderConsumerCell(col, cellParams, false);
+                    if (!custom.useDefault) return custom.content;
+                    if (col.field === meta.groupingField && !meta.isGroupFooter) return null;
+                    return cellParams.value == null ? null : displayValue(cellParams);
                 }
             };
         }) as GridColDef<R>[];
-    }, [activeColumns, isHierarchyEnabled, isRowGrouping, isTreeData, activeHierarchyHandlers]);
+    }, [activeColumns, isHierarchyEnabled, isRowGrouping, isTreeData, activeHierarchyHandlers, hierarchyField, getRowId, aggregationModel, groupingRows]);
 
     // ── Column widths ─────────────────────────────────────────────────────────
     const [columnWidths, setColumnWidths] = useState<Record<string, number>>(
@@ -162,72 +333,104 @@ export function useGridColumns<R extends GridRowModel>(
         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 ─────────────────────────────────────────────
+    // A controlled or initial column order always applies. disableColumnReorder only removes the
+    // user's ways to change it (header drag, Columns-panel reorder).
     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]);
+    }, [effectiveColumns, effectiveColumnOrder]);
 
     const visibleOrderedColumns = useMemo<GridColDef<R>[]>(
-        () => orderedColumns.filter(col => columnVisibilityModel[col.field] !== false),
-        [orderedColumns, columnVisibilityModel]
+        () => orderedColumns.filter(isColumnShown),
+        [orderedColumns, isColumnShown]
     );
 
-    // ── Column reorder handlers ───────────────────────────────────────────────
+    // ── Column reorder ────────────────────────────────────────────────────────
+    // Every move works on the full current order (orderedColumns: all columns, including ones added
+    // after mount or missing from a stored/controlled order, and the synthetic __group__ column),
+    // so the reported indices and the stored order always describe the same list.
+    const commitColumnOrder = useCallback((newOrder: string[], change?: GridColumnOrderChangeParams) => {
+        // A controlled columnOrder names source columns; generated pivot columns keep their own order.
+        if (pivotMode || !columnOrder) setInternalColumnOrder(newOrder);
+        if (change) onColumnOrderChange?.(change);
+        if (!pivotMode) onColumnOrderModelChange?.(newOrder);
+    }, [pivotMode, columnOrder, setInternalColumnOrder, onColumnOrderChange, onColumnOrderModelChange]);
+
+    const applyColumnMove = useCallback((oldIndex: number, targetIndex: number) => {
+        const newOrder = orderedColumns.map(col => col.field);
+        const [movedField] = newOrder.splice(oldIndex, 1);
+        newOrder.splice(targetIndex, 0, movedField);
+        commitColumnOrder(newOrder, {
+            column: orderedColumns[oldIndex] as unknown as GridColDef,
+            oldIndex,
+            targetIndex,
+        });
+    }, [orderedColumns, commitColumnOrder]);
+
     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]),
+        onColumnOrderChange: useCallback(
+            ({ oldIndex, targetIndex }: GridColumnOrderChangeParams) => applyColumnMove(oldIndex, targetIndex),
+            [applyColumnMove]
+        ),
         disableColumnReorder,
     });
 
-    // ── Navigation columns (system cols + data cols for keyboard nav) ─────────
+    const moveColumn = useCallback((fromField: string, toField: string) => {
+        const oldIndex = orderedColumns.findIndex(col => col.field === fromField);
+        const targetIndex = orderedColumns.findIndex(col => col.field === toField);
+        if (oldIndex === -1 || targetIndex === -1 || oldIndex === targetIndex) return;
+        applyColumnMove(oldIndex, targetIndex);
+    }, [orderedColumns, applyColumnMove]);
+
+    const resetColumnOrder = useCallback(() => {
+        commitColumnOrder(naturalOrder);
+    }, [commitColumnOrder, naturalOrder]);
+
+    // ── Navigation columns (system cols + rendered data cols, in render order) ─
+    // Mirrors what Row and Header render, so arrow keys follow the screen and never
+    // land on a hidden column. System columns are never sortable or editable.
+    const renderedDataColumns = useMemo(
+        () => inPinnedRenderOrder(visibleOrderedColumns, pinnedColumns),
+        [visibleOrderedColumns, pinnedColumns]
+    );
+
     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]);
+        const specials: { field: string; sortable: false; editable: false }[] = [];
+        if (rowReordering)    specials.push({ field: REORDER_FIELD, sortable: false, editable: false });
+        if (hasDetailPanel)   specials.push({ field: EXPAND_FIELD, sortable: false, editable: false });
+        if (checkboxSelection) specials.push({ field: CHECKBOX_FIELD, sortable: false, editable: false });
+        return [...specials, ...renderedDataColumns];
+    }, [renderedDataColumns, checkboxSelection, hasDetailPanel, rowReordering]);
+
+    const columnIndexMap = useMemo(
+        () => new Map(renderedDataColumns.map((col, index) => [col.field, index])),
+        [renderedDataColumns]
+    );
 
     return {
         effectiveColumns,
+        hierarchyField,
         orderedColumns,
         visibleOrderedColumns,
+        renderOrderedColumns: renderedDataColumns,
         navigationColumns,
+        columnIndexMap,
         columnWidths,
         effectiveColumnOrder,
         setInternalColumnOrder,
         columnReorderHandlers,
+        moveColumn,
+        resetColumnOrder,
         handleColumnResize,
     };
 }