@opencorestack/opengridx 3.4.0 → 3.5.0

package/lib/components/AiAssistant/useSpeechInput.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { attempt } from '../../utils/attempt';
+
+/** The part of the Web Speech API's SpeechRecognition the panel uses. */
+interface SpeechRecognitionLike {
+    lang: string;
+    interimResults: boolean;
+    maxAlternatives: number;
+    onresult: ((event: { results: ArrayLike<ArrayLike<{ transcript: string }>> }) => void) | null;
+    onend: (() => void) | null;
+    onerror: (() => void) | null;
+    start: () => void;
+    stop: () => void;
+    abort: () => void;
+}
+
+type SpeechRecognitionConstructor = new () => SpeechRecognitionLike;
+
+function getSpeechRecognition(): SpeechRecognitionConstructor | null {
+    if (typeof window === 'undefined') return null;
+    const w = window as unknown as { SpeechRecognition?: SpeechRecognitionConstructor; webkitSpeechRecognition?: SpeechRecognitionConstructor };
+    return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+
+/**
+ * Dictation for the prompt input. The browser asks for the microphone only when `toggle` starts it
+ * (a click), never on load; without speech recognition `toggle` does nothing.
+ */
+export function useSpeechInput(onText: (text: string) => void): { listening: boolean; toggle: () => void } {
+    const [listening, setListening] = useState(false);
+    const recognitionRef = useRef<SpeechRecognitionLike | null>(null);
+    const onTextRef = useRef(onText);
+    useLayoutEffect(() => {
+        onTextRef.current = onText;
+    });
+
+    useEffect(() => () => {
+        const recognition = recognitionRef.current;
+        recognitionRef.current = null;
+        if (recognition) attempt(() => recognition.abort());
+    }, []);
+
+    const toggle = useCallback(() => {
+        const running = recognitionRef.current;
+        if (running) {
+            attempt(() => running.stop());
+            return;
+        }
+        const Recognition = getSpeechRecognition();
+        if (!Recognition) return;
+        const created = attempt(() => new Recognition());
+        if (!created.ok) return;
+        const recognition = created.value;
+        recognition.lang = typeof navigator === 'undefined' ? 'en-US' : navigator.language;
+        recognition.interimResults = false;
+        recognition.maxAlternatives = 1;
+        recognition.onresult = (event) => {
+            const first = event.results[0];
+            const transcript = first && first[0] ? first[0].transcript : '';
+            if (transcript) onTextRef.current(transcript);
+        };
+        const done = () => {
+            if (recognitionRef.current === recognition) recognitionRef.current = null;
+            setListening(false);
+        };
+        recognition.onend = done;
+        recognition.onerror = done;
+        recognitionRef.current = recognition;
+        setListening(true);
+        if (!attempt(() => recognition.start()).ok) done();
+    }, []);
+
+    return { listening, toggle };
+}

package/lib/components/Cell/Cell.css

@@ -52,6 +52,34 @@
 .ogx__cell--range-right {
   --ogx-range-edge-right: inset -2px 0 0 0 var(--ogx-range-border);
 }
+/*
+ * Fill handle (v3.5): the square on the bottom-right cell of the range. The cell clips its overflow,
+ * so the 24px hit area lies inside the corner and the visible square sits in its corner.
+ * touch-action: none lets a touch drag on it fill instead of scrolling.
+ */
+.ogx__cell-fill-handle {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 24px;
+  height: 24px;
+  max-width: 100%;
+  max-height: 100%;
+  cursor: crosshair;
+  touch-action: none;
+  z-index: 1;
+}
+.ogx__cell-fill-handle::after {
+  content: '';
+  position: absolute;
+  right: 1px;
+  bottom: 1px;
+  width: 7px;
+  height: 7px;
+  box-sizing: border-box;
+  background-color: var(--ogx-fill-handle-color, var(--ogx-range-border));
+  border: 1px solid var(--ogx-grid-background, #fff);
+}
 /* While a pointer drag selects cells, the browser must not select text as well. */
 .ogx--range-dragging,
 .ogx--range-dragging * {

package/lib/components/Cell/Cell.tsx

@@ -7,7 +7,7 @@ import { GridEditInputCell } from './GridEditInputCell';
 import { CellErrorBoundary } from './CellErrorBoundary';
 import { formatValueByType } from '../../utils/values';
 import { attempt } from '../../utils/attempt';
-import { RANGE_BOTTOM, RANGE_CELL, RANGE_LEFT, RANGE_RIGHT, RANGE_TOP } from '../../utils/cellSelection';
+import { RANGE_BOTTOM, RANGE_CELL, RANGE_FILL_HANDLE, RANGE_LEFT, RANGE_RIGHT, RANGE_TOP } from '../../utils/cellSelection';
 
 export interface CellProps<R extends GridRowModel = GridRowModel> {
     onCellClick?: (params: GridCellParams<R>) => void;
@@ -50,7 +50,8 @@ export interface CellProps<R extends GridRowModel = GridRowModel> {
     valueError?: unknown;
     /**
      * Place of the cell in the selected cell range (`cellSelection`), as bit flags: in range 1, top
-     * edge 2, bottom 4, left 8, right 16. 0 or absent: not in a range. @since v3.3
+     * edge 2, bottom 4, left 8, right 16; 32 draws the fill handle (v3.5). 0 or absent: not in a range.
+     * @since v3.3
      */
     rangeFlags?: number;
 }
@@ -341,6 +342,9 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
                     formattedValue
                 )}
             </div>
+            {(rangeFlags & RANGE_FILL_HANDLE) !== 0 && !isEditing && (
+                <div className="ogx__cell-fill-handle" aria-hidden="true" />
+            )}
         </div>
     );
 }

package/lib/components/DataGrid/DataGrid.tsx

@@ -30,6 +30,7 @@ import { useGridEditing } from '../../hooks/features/useGridEditing';
 import { useGridBatchEdit } from '../../hooks/features/useGridBatchEdit';
 import { useGridClipboardPaste } from '../../hooks/core/useGridClipboardPaste';
 import { useGridUndoRedo, useGridEditCommitChannel, UNDO_HISTORY_LIMIT } from '../../hooks/core/useGridUndoRedo';
+import { useGridFillHandle } from '../../hooks/core/useGridFillHandle';
 import { useGridSpanning } from '../../hooks/features/useGridSpanning';
 import { useGridSpanRowWindow, useGridSpanColumnWindow } from '../../hooks/features/useGridSpanRenderWindow';
 import { useColumnGroupReorderGuard } from '../../hooks/features/useColumnGroupReorderGuard';
@@ -43,7 +44,7 @@ import { GridLoadingOverlay } from './GridLoadingOverlay';
 import { GridPinnedRows } from './GridPinnedRows';
 import { GridVirtualRows } from './GridVirtualRows';
 import { GridStandaloneColumnPanel } from './GridStandaloneColumnPanel';
-import { resolveGridModes, EMPTY_ROW_GROUPING_MODEL } from '../../utils/gridModes';
+import { resolveGridModes } from '../../utils/gridModes';
 import { useGridGroupingColumn } from '../../hooks/core/useGridGroupingColumn';
 import { useGridRowIdOf, getDefaultRowId } from '../../hooks/core/useGridRowIdOf';
 import { useGridApiRefBinding } from '../../hooks/core/useGridApiRefBinding';
@@ -65,6 +66,9 @@ import { GridPaginationArea } from './GridPaginationArea';
 import { GridLiveRegion } from './GridLiveRegion';
 import { useGridAriaRows } from '../../hooks/core/useGridAriaRows';
 import { useGridToolbarProps } from '../../hooks/core/useGridToolbarProps';
+import { useGridAiAssistant } from '../../hooks/features/useGridAiAssistant';
+import { GridAiAssistantArea } from '../AiAssistant/GridAiAssistantArea';
+import { DEFAULT_HEADER_FILTER_HEIGHT } from '../../utils/headerFilters';
 import type { DataGridProps, DataGridUntypedColumnsProps, GridValidRowModel, GridRowModel, GridRowId, GridColDef } from '../../types';
 
 /**
@@ -83,6 +87,8 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         rowHeight: rowHeightProp,
         headerHeight: headerHeightProp,
         wrapHeaderText = false,
+        headerFilters = false,
+        headerFilterHeight = DEFAULT_HEADER_FILTER_HEIGHT,
         autoHeight = false,
         density,
         checkboxSelection = false,
@@ -98,6 +104,8 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         onClipboardPaste,
         onBeforeClipboardPaste,
         undoRedo = false,
+        disableFillHandle = false,
+        onFill,
         onHistoryChange,
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange: propOnRowSelectionModelChange,
@@ -138,6 +146,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         groupingColDef,
 
         rowGroupingModel: propRowGroupingModel,
+        onRowGroupingModelChange,
 
         aggregationModel: propAggregationModel,
         onAggregationModelChange,
@@ -177,12 +186,14 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         localeText,
         apiRef: propApiRef,
         overscanRowCount = 3,
+        aiAssistant,
+        onAiAssistantApply,
+        onAiAssistantError,
     } = props;
     // Equal inline column definitions keep one identity, so the row passes memoised on it do not re-run.
     const columns = useStableColumns(columnsProp);
 
     const effectiveNoRowsLabel = localeText?.noRowsLabel ?? noRowsLabel;
-    const rowGroupingModel = propRowGroupingModel || EMPTY_ROW_GROUPING_MODEL;
 
     const controlledState = useGridControlledState({
         initialState,
@@ -192,6 +203,8 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         onFilterModelChange,
         aggregationModel: propAggregationModel,
         onAggregationModelChange,
+        rowGroupingModel: propRowGroupingModel,
+        onRowGroupingModelChange,
         columnVisibilityModel: propColumnVisibilityModel,
         onColumnVisibilityModelChange,
         pinnedColumns: propPinnedColumns,
@@ -213,6 +226,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         selectedRowIds: selectionModelRowIds,
         handleRowSelectionModelChange,
         density: effectiveDensity,
+        rowGroupingModel, handleRowGroupingModelChange,
     } = controlledState;
 
     const pivot = useGridPivot({
@@ -226,6 +240,8 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         hierarchyRequested: treeData || rowGroupingModel.length > 0,
     });
     const isPivotActive = pivot.isActive;
+    // The header filter row filters the source columns; pivot columns are generated, so it is off then.
+    const showHeaderFilters = headerFilters && !isPivotActive;
     const {
         rowReordering, hierarchyRowGroupingModel, isTreeDataRequested, isTreeData,
         isRowGrouping, isHierarchyEnabled, hasGroupingColumn, pagination, listView,
@@ -459,6 +475,14 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
             dataRows,
         }),
         visibleColumns: renderOrderedColumns as unknown as GridColDef[],
+        rowGroupingModel,
+        onRowGroupingModelChange: handleRowGroupingModelChange,
+        aggregationModel,
+        onAggregationModelChange: handleAggregationModelChange,
+        columnVisibilityModel,
+        onColumnVisibilityModelChange: handleColumnVisibilityModelChange,
+        pivotModel: currentPivotModel,
+        onPivotModelChange: handlePivotModelChange,
     });
 
     // Indices address the consumer's own rows, whatever the sort, filter, page or pinning.
@@ -596,6 +620,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         pinExpandColumn,
         rowHeight: effectiveRowHeight,
         cellSelection: cellSelection.keyboard,
+        headerFilters: showHeaderFilters,
     });
 
     const { handleCellClick, handleHeaderClick } = useGridPointerFocusHandlers<R>({
@@ -650,6 +675,23 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         pinnedTopRowCount: pinnedTopRows.length,
     });
 
+    // Fill handle (cellSelection): drag the range's corner, Ctrl/Cmd+D and Ctrl/Cmd+R.
+    const fillHandle = useGridFillHandle<R>({
+        containerRef, viewportRef,
+        selection: cellSelection,
+        disableFillHandle,
+        isEditing: editingHandlers.editingCell !== null,
+        allRenderableRows,
+        getRowId: getRowIdOf,
+        navigationColumns: navigationColumns as unknown as GridColDef<R>[],
+        columnIndexMap,
+        isCellEditable,
+        rowMetaMap,
+        getSpanOrigin: spanning.getSpanOrigin,
+        batchEdit,
+        onFill,
+    });
+
     const { handleHideColumn, handlePinColumn } = useGridColumnMenuHandlers({
         columnVisibilityModel,
         onColumnVisibilityModelChange: handleColumnVisibilityModelChange,
@@ -659,6 +701,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
 
     const ariaRows = useGridAriaRows({
         columnGroupingModel,
+        headerFilterRow: showHeaderFilters,
         pinnedTopCount: pinnedTopRows.length,
         pinnedBottomCount: pinnedBottomRows.length,
         pagination,
@@ -713,6 +756,15 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
     const columnsPanel = useGridColumnsPanel();
     useGridStylesheetWarning(containerRef);
 
+    // The aiAssistant prompt panel (v3.5): applies validated replies through apiRef; apiRef.openAiAssistant.
+    const aiAssistantPanel = useGridAiAssistant({
+        apiRef,
+        options: aiAssistant,
+        columns: activeColumns as unknown as GridColDef[],
+        onApply: onAiAssistantApply,
+        onError: onAiAssistantError,
+    });
+
     const NoRowsOverlaySlot = slots?.noRowsOverlay;
     const LoadingOverlaySlot = slots?.loadingOverlay;
     const loadingOverlay = LoadingOverlaySlot ? <LoadingOverlaySlot {...slotProps?.loadingOverlay} /> : undefined;
@@ -743,6 +795,12 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         disableColumnReorder, columnGroupingModel, moveColumn, resetColumnOrder,
         forceColumnsOpen: columnsPanel.toolbarPanelRequested,
         onColumnsPanelClose: columnsPanel.closeToolbarPanel,
+        aiAssistantEnabled: aiAssistantPanel.enabled,
+        aiAssistantOpen: aiAssistantPanel.open,
+        onAiAssistantToggle: aiAssistantPanel.togglePanel,
+        aiAssistantLabel: localeText?.aiAssistantButton,
+        forceFiltersOpen: columnsPanel.toolbarFiltersRequested,
+        onFiltersPanelClose: columnsPanel.closeToolbarFiltersPanel,
     });
 
     // Props the row renderers (top-pinned, centre and bottom-pinned rows) all take.
@@ -764,6 +822,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         rowMetaMap,
         cellRange: cellSelection.displayRange,
         cellRangeHasRowSpan: cellSelection.hasRowSpan,
+        fillHandle: fillHandle.handle,
     };
 
     return (
@@ -774,7 +833,8 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                 ...style,
                 height: height ?? style?.height,
                 '--ogx-row-height': `${effectiveRowHeight}px`,
-                '--ogx-header-height': `${headerHeight}px`
+                '--ogx-header-height': `${headerHeight}px`,
+                ...(showHeaderFilters ? { '--ogx-header-filter-height': `${headerFilterHeight}px` } : undefined),
             } as unknown as React.CSSProperties}
             aria-busy={effectiveLoading}
         >
@@ -784,6 +844,14 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                 </GridToolbarHostContext.Provider>
             )}
 
+            {aiAssistantPanel.panelProps && (
+                <GridAiAssistantArea
+                    panelProps={aiAssistantPanel.panelProps}
+                    slot={slots?.aiAssistantPanel}
+                    slotProps={slotProps?.aiAssistantPanel}
+                />
+            )}
+
             {/* Used by the column menu's Manage columns when no GridToolbar can show the panel */}
             <GridStandaloneColumnPanel<R>
                 isOpen={columnsPanel.standalonePanelOpen}
@@ -912,6 +980,10 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                                 onPinColumn={handlePinColumn}
                                 wrapHeaderText={wrapHeaderText}
                                 headerHeight={headerHeight}
+                                headerFilters={showHeaderFilters}
+                                filterModel={filterModel}
+                                onFilterModelChange={handleFilterModelChange}
+                                onOpenFilterPanel={columnsPanel.openFiltersPanel}
                             />
 
                             <GridPinnedRows<R>
@@ -1035,6 +1107,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                 dataRowCount={dataRows.length}
                 filterModel={filterModel}
                 cellSelectionAnnouncement={cellSelection.announcement}
+                aiAssistantAnnouncement={aiAssistantPanel.announcement}
             />
 
             {showLoadingOverRows && (

package/lib/components/DataGrid/GridLiveRegion.tsx

@@ -13,13 +13,15 @@ interface GridLiveRegionProps {
     filterModel: GridFilterModel | undefined;
     /** The size of the selected cell range (`cellSelection`), already debounced. */
     cellSelectionAnnouncement?: string;
+    /** The `aiAssistant` status line ("Thinking…", "Applied 3 changes", an error). */
+    aiAssistantAnnouncement?: string;
 }
 
 /**
  * Polite status announcements: loading, a load error, no rows, or the row count of an active filter;
- * and the size of the selected cell range.
+ * the size of the selected cell range; and the AI assistant's status.
  */
-export function GridLiveRegion({ loading, error, noRowsLabel, filteredRowCount, dataRowCount, filterModel, cellSelectionAnnouncement }: GridLiveRegionProps) {
+export function GridLiveRegion({ loading, error, noRowsLabel, filteredRowCount, dataRowCount, filterModel, cellSelectionAnnouncement, aiAssistantAnnouncement }: GridLiveRegionProps) {
     return (
         <div className="ogx-aria-live-status" role="status" aria-live="polite">
             {loading ? 'Loading data...' : ''}
@@ -32,6 +34,7 @@ export function GridLiveRegion({ loading, error, noRowsLabel, filteredRowCount,
                         : ''
             )}
             {cellSelectionAnnouncement ? <span className="ogx-aria-live-status__cells"> {cellSelectionAnnouncement}</span> : null}
+            {aiAssistantAnnouncement ? <span className="ogx-aria-live-status__ai"> {aiAssistantAnnouncement}</span> : null}
         </div>
     );
 }

package/lib/components/DataGrid/GridPinnedRows.tsx

@@ -17,6 +17,7 @@ import type {
 import type { CellColSpanInfo, RowSpanningCaches } from '../../hooks/features/useGridSpanning';
 import type { GridDisplayCellRange } from '../../hooks/core/useGridCellSelection';
 import { getRowCellRange } from '../../utils/cellSelection';
+import type { GridFillHandlePosition } from '../../utils/cellSelection';
 import type { GridEditingState } from '../../hooks/features/useGridEditing';
 
 interface PinnedRowEditingHandlers {
@@ -64,6 +65,8 @@ export interface GridPinnedRowsProps<R extends GridRowModel> {
     cellRange?: GridDisplayCellRange | null;
     /** The grid has row spans: rows tell their cells how far the range bottom is. */
     cellRangeHasRowSpan?: boolean;
+    /** Where the fill handle is drawn (v3.5), or null. */
+    fillHandle?: GridFillHandlePosition | null;
     /** Pinned rows are edited like any other row. */
     editingHandlers?: PinnedRowEditingHandlers;
     isCellEditable?: (params: GridCellParams<R>) => boolean;
@@ -111,6 +114,7 @@ export function GridPinnedRows<R extends GridRowModel>({
     rowReordering = false,
     cellRange,
     cellRangeHasRowSpan = false,
+    fillHandle,
 }: GridPinnedRowsProps<R>) {
     if (rows.length === 0) return null;
 
@@ -156,7 +160,7 @@ export function GridPinnedRows<R extends GridRowModel>({
                     onEditCellValueChange={editingHandlers?.setEditCellValue}
                     isCellEditable={isCellEditable}
                     rowReordering={rowReordering}
-                    cellRange={getRowCellRange(cellRange, rowIndex, cellRangeHasRowSpan)}
+                    cellRange={getRowCellRange(cellRange, rowIndex, cellRangeHasRowSpan, fillHandle)}
                 />
                 );
             })}

package/lib/components/DataGrid/GridVirtualRows.tsx

@@ -20,6 +20,7 @@ import type { GridEditingState } from '../../hooks/features/useGridEditing';
 import type { CellColSpanInfo, RowSpanningCaches } from '../../hooks/features/useGridSpanning';
 import type { GridDisplayCellRange } from '../../hooks/core/useGridCellSelection';
 import { getRowCellRange } from '../../utils/cellSelection';
+import type { GridFillHandlePosition } from '../../utils/cellSelection';
 
 interface RowEditingHandlers {
     editingCell: GridEditingState['editingCell'];
@@ -77,6 +78,8 @@ export interface GridVirtualRowsProps<R extends GridRowModel> {
     cellRange?: GridDisplayCellRange | null;
     /** The grid has row spans: rows tell their cells how far the range bottom is. */
     cellRangeHasRowSpan?: boolean;
+    /** Where the fill handle is drawn (v3.5), or null. */
+    fillHandle?: GridFillHandlePosition | null;
 }
 
 export function GridVirtualRows<R extends GridRowModel>({
@@ -123,6 +126,7 @@ export function GridVirtualRows<R extends GridRowModel>({
     columnIndexMap,
     cellRange,
     cellRangeHasRowSpan = false,
+    fillHandle,
 }: GridVirtualRowsProps<R>) {
     const skeletonColumns: GridColDef<R>[] = baseColumns.length > 0
         ? baseColumns
@@ -214,7 +218,7 @@ export function GridVirtualRows<R extends GridRowModel>({
                             rowSpanningCaches={rowSpanningCaches}
                             rowHeight={rowHeight}
                             rowMeta={rowMetaMap.get(id)}
-                            cellRange={getRowCellRange(cellRange, actualIndex, cellRangeHasRowSpan)}
+                            cellRange={getRowCellRange(cellRange, actualIndex, cellRangeHasRowSpan, fillHandle)}
                         />
                     ))
                 )}

package/lib/components/FilterPanel/FilterPanel.tsx

@@ -6,8 +6,7 @@ import type {
     GridColDef,
     GridFilterOperator
 } from '../../types';
-import { getOperatorsForType, NO_VALUE_OPERATORS } from '../../utils/filtering';
-import { toLocalDateString } from '../../utils/values';
+import { filterValueToInputText, getOperatorsForType, NO_VALUE_OPERATORS } from '../../utils/filtering';
 import { Input } from '../ui/Input';
 
 
@@ -74,13 +73,7 @@ function matchesOption(option: ValueOption, value: unknown): boolean {
 
 /** Text shown in the value input for a committed value. Never used to emit anything. */
 function toInputText(value: unknown, col: GridColDef): string {
-    if (value == null) return '';
-    if (col.type === 'date' || value instanceof Date) {
-        const day = toLocalDateString(value);
-        return day || (typeof value === 'string' ? value : '');
-    }
-    if (Array.isArray(value)) return value.map(v => String(v)).join(', ');
-    return String(value);
+    return filterValueToInputText(value, col.type);
 }
 
 /** The item value for typed text. isAnyOf takes a comma-separated list. */

package/lib/components/Header/Header.tsx

@@ -2,12 +2,14 @@ import React, { useId } from 'react';
 import { Checkbox } from '../ui/Checkbox';
 import { ColumnResizeHandle } from '../ColumnResizeHandle/ColumnResizeHandle';
 import { clampResizeWidth } from '../ColumnResizeHandle/clampResizeWidth';
-import type { GridColDef, GridRowModel, GridSortDirection, GridColumnPinning, GridAggregationModel, GridColumnGroupingModel } from '../../types';
+import type { GridColDef, GridRowModel, GridSortDirection, GridColumnPinning, GridAggregationModel, GridColumnGroupingModel, GridFilterModel } from '../../types';
 import { isColumnPinned, calculatePinnedPositions, getPinnedEdgeFields } from '../../utils/pinning';
 import { getRenderedColumnWidth } from '../../utils/columnWidth';
 import { buildColumnGroupRow, getColumnGroupDepth, getColumnGroupPaths } from '../../utils/columnGroups';
 import { ColumnMenu } from './ColumnMenu';
 import { getHeaderLineClamp, shouldWrapHeaderText } from '../../utils/headerWrap';
+import { getHeaderColumnStyle } from './headerColumnStyle';
+import { HeaderFilterRow } from '../HeaderFilter/HeaderFilterRow';
 
 
 function MenuIcon() {
@@ -60,8 +62,11 @@ export interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onDragOver?: (field: string) => (event: React.DragEvent) => void;
     onDragEnd?: () => void;
     onDrop?: (targetField: string) => (event: React.DragEvent) => void;
-    /** The grid's focus position; `id: null` means a header cell is focused. */
-    focusedCell?: { id: string | number | null; field: string } | null;
+    /**
+     * The grid's focus position; `id: null` means a header cell is focused, and `headerFilter: true`
+     * a cell of the header filter row.
+     */
+    focusedCell?: { id: string | number | null; field: string; headerFilter?: boolean } | null;
     onHeaderClick?: (field: string) => void;
     onSortAdd?: (field: string, direction: GridSortDirection) => void;
     multiSort?: boolean;
@@ -74,6 +79,14 @@ export interface HeaderProps<R extends GridRowModel = GridRowModel> {
     wrapHeaderText?: boolean;
     /** Header row height in pixels; sets how many lines a wrapped title may take. Defaults to 56. */
     headerHeight?: number;
+    /** Renders the header filter row under the column headers (`DataGridProps.headerFilters`). */
+    headerFilters?: boolean;
+    /** The filter model the header filter row reads. */
+    filterModel?: GridFilterModel;
+    /** Receives the filter model after a header filter changes. */
+    onFilterModelChange?: (model: GridFilterModel) => void;
+    /** Opens the filter panel; a header filter cell showing "Custom filter" calls it. */
+    onOpenFilterPanel?: () => void;
 }
 
 export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps<R>) {
@@ -112,6 +125,10 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
         columnIndexMap,
         wrapHeaderText = false,
         headerHeight = 56,
+        headerFilters = false,
+        filterModel,
+        onFilterModelChange,
+        onOpenFilterPanel,
     } = props;
 
     const selectAllId = useId();
@@ -148,7 +165,7 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
         setMenuOpenParams({ colDef, anchorEl: anchor });
     };
 
-    const isHeaderFocused = (field: string) => focusedCell?.id === null && focusedCell.field === field;
+    const isHeaderFocused = (field: string) => focusedCell?.id === null && !focusedCell.headerFilter && focusedCell.field === field;
 
     // aria-colindex: system columns first (reorder, expand, checkbox), then the data columns.
     const reorderColIndex = rowReordering ? 1 : 0;
@@ -437,30 +454,12 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                         colDef.headerClassName
                     ].filter(Boolean).join(' ');
 
-                    const effectiveWidth = columnWidths[colDef.field] ?? colDef.width ?? 100;
-
                     const style: React.CSSProperties = {
-                        width: effectiveWidth,
-                        minWidth: colDef.minWidth,
-                        maxWidth: colDef.maxWidth,
-                        flexGrow: colDef.flex ?? 0,
-                        flexShrink: 0,
-                        flexBasis: colDef.flex ? 'auto' : 'auto',
-                        boxSizing: 'border-box',
-                        position: isPinned ? 'sticky' : 'relative',
+                        ...getHeaderColumnStyle(colDef, columnWidths, pinnedPosition, pinnedPosition ? pinnedPositions[colDef.field] : undefined),
                         zIndex: colDef.zIndex,
                         opacity: isDragging ? 0.5 : 1
                     };
 
-                    if (isPinned && pinnedPosition) {
-                        const offset = pinnedPositions[colDef.field];
-                        if (pinnedPosition === 'left') {
-                            style.left = offset;
-                        } else {
-                            style.right = offset;
-                        }
-                    }
-
                     const headerContent = colDef.renderHeader
                         ? colDef.renderHeader({ field: colDef.field, colDef: colDef as unknown as GridColDef, colIndex })
                         : colDef.headerName || colDef.field;
@@ -565,6 +564,28 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                     />
                 )}
             </div>{/* end .ogx__header */}
+
+            {/* ── Header filter row ── */}
+            {headerFilters && (
+                <HeaderFilterRow
+                    columns={columns as unknown as GridColDef[]}
+                    columnWidths={columnWidths}
+                    pinnedColumns={pinnedColumns}
+                    pinnedPositions={pinnedPositions}
+                    pinnedEdges={pinnedEdges}
+                    rowReordering={rowReordering}
+                    hasDetailPanel={hasDetailPanel}
+                    checkboxSelection={checkboxSelection}
+                    pinExpandColumn={pinExpandColumn}
+                    pinCheckboxColumn={pinCheckboxColumn}
+                    columnIndexMap={columnIndexMap}
+                    ariaRowIndex={groupDepth + 2}
+                    filterModel={filterModel}
+                    onFilterModelChange={onFilterModelChange}
+                    onOpenFilterPanel={onOpenFilterPanel}
+                    focusedField={focusedCell?.id === null && focusedCell.headerFilter ? focusedCell.field : null}
+                />
+            )}
         </div>
     );
 }

package/lib/components/Header/headerColumnStyle.ts

@@ -0,0 +1,28 @@
+import type React from 'react';
+import type { GridColDef, GridRowModel } from '../../types';
+
+/**
+ * Width, flex and sticky offset of a data column's cell in a header row. The column header row
+ * and the header filter row both use it, so their cells line up whatever the pinning and widths.
+ */
+export function getHeaderColumnStyle<R extends GridRowModel>(
+    colDef: GridColDef<R>,
+    columnWidths: Record<string, number>,
+    pinnedPosition: 'left' | 'right' | null,
+    pinnedOffset: number | undefined,
+): React.CSSProperties {
+    const style: React.CSSProperties = {
+        width: columnWidths[colDef.field] ?? colDef.width ?? 100,
+        minWidth: colDef.minWidth,
+        maxWidth: colDef.maxWidth,
+        flexGrow: colDef.flex ?? 0,
+        flexShrink: 0,
+        flexBasis: 'auto',
+        boxSizing: 'border-box',
+        position: pinnedPosition ? 'sticky' : 'relative',
+    };
+    if (pinnedPosition === 'left') style.left = pinnedOffset;
+    else if (pinnedPosition === 'right') style.right = pinnedOffset;
+    return style;
+}
+