feat: Refactor filtering system to use discriminated unions for filter values

- Updated filter value structure to use a discriminated union for better type safety.
- Consolidated filter handling into a single onFilterChange callback.
- Removed deprecated multiSelect, text, and people filter props from IOGridDataGridProps.
- Introduced a new date filter type and updated related documentation.
- Enhanced client-side data processing to support new filter structure.
- Removed the title prop from OGrid components, encouraging external rendering.
- Updated all relevant components and utilities to align with the new filtering approach.
- Bumped package versions to 1.6.0 across all implementations.

Author: alaarab

CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to OGrid will be documented in this file.
 
+## [1.6.0] – 2026-02-09
+
+### BREAKING CHANGES
+
+- **FilterValue discriminated union** — `IFilters` values are now typed discriminated unions instead of raw values. All filter values must specify their `type`:
+  ```typescript
+  // Before (1.5.x)
+  { status: ['Active', 'Closed'], name: 'Alice' }
+  // After (1.6.0)
+  { status: { type: 'multiSelect', value: ['Active', 'Closed'] }, name: { type: 'text', value: 'Alice' } }
+  ```
+  Supported types: `{ type: 'text', value: string }`, `{ type: 'multiSelect', value: string[] }`, `{ type: 'people', value: UserLike }`, `{ type: 'date', value: IDateFilterValue }`.
+
+- **Unified filter API on DataGridTable** — `IOGridDataGridProps` now uses `filters: IFilters` + `onFilterChange: (key, value) => void` instead of the 8 split filter props (`multiSelectFilters`, `textFilters`, `peopleFilters`, `dateFilters` and their onChange handlers). This does NOT affect `OGrid` consumers — only direct `DataGridTable` users.
+
+- **Grouped `useDataGridState` returns** — The hook's return object is now organized into 6 logical groups instead of 42 flat properties:
+  - `layout` — column structure, sizing, container dimensions
+  - `rowSelection` — selected rows, selection handlers
+  - `editing` — cell editing state, commit/cancel
+  - `interaction` — active cell, selection range, keyboard, clipboard, fill handle, undo/redo
+  - `contextMenu` — menu position, handlers (note: `contextMenu` position renamed to `menuPosition`)
+  - `viewModels` — headerFilterInput, cellDescriptorInput, statusBarConfig, showEmptyInGrid
+
+- **Removed deprecated props** — `title`, `gap`, and `columnChooser` removed from `OGridLayout`. Consumers should render titles outside `<OGrid>` and use `toolbarEnd` for column chooser placement.
+
+- **Removed `toDataGridFilterProps`** — This helper was replaced by the unified filter API; use `filters`/`onFilterChange` directly.
+
+### Added
+
+- **`processClientSideData` utility** — Pure function extracted from `useOGrid` for client-side filtering and sorting. Can be used independently for custom data processing pipelines.
+- **Wildcard re-exports** — All three UI packages now use `export * from '@alaarab/ogrid-core'` instead of cherry-picked re-export lists. Every core type is automatically available from any UI package import.
+- **Grouped state sub-interfaces** — `DataGridLayoutState`, `DataGridRowSelectionState`, `DataGridEditingState`, `DataGridCellInteractionState`, `DataGridContextMenuState`, `DataGridViewModelState` are exported for consumers building custom grid wrappers.
+
+### Fixed
+
+- **Material InlineCellEditor auto-focus** — Added `useEffect` auto-focus matching Radix/Fluent behavior.
+
+### Improved
+
+- **Phase 2: Descriptor-to-component pattern** — All three UI packages now use the full suite of 6 core helpers (`getCellRenderDescriptor`, `buildInlineEditorProps`, `buildPopoverEditorProps`, `getCellInteractionProps`, `resolveCellDisplayContent`, `resolveCellStyle`). Each package's `renderCellContent` is now a thin ~50-line mapping from descriptors to framework-specific JSX.
+
+---
+
 ## [1.5.0] – 2026-02-09
 
 ### Added

CLAUDE.md

@@ -41,11 +41,11 @@ npm run docs:build              # Build docs site
 
 ### Core (`packages/core/src/`)
 
-**Types** — `IColumnDef`, `IColumnGroupDef`, `IDataSource`, `IFilters`, `IDateFilterValue`, `UserLike`, `IOGridApi`, `IOGridProps`, `ICellEditorProps`, etc. in `types/`. Column types: `'text' | 'numeric' | 'date' | 'boolean'`. Filter types: `'none' | 'text' | 'multiSelect' | 'people' | 'date'`.
+**Types** — `IColumnDef`, `IColumnGroupDef`, `IDataSource`, `IFilters`, `IDateFilterValue`, `UserLike`, `IOGridApi`, `IOGridProps`, `ICellEditorProps`, `FilterValue`, etc. in `types/`. Column types: `'text' | 'numeric' | 'date' | 'boolean'`. Filter types: `'none' | 'text' | 'multiSelect' | 'people' | 'date'`. `FilterValue` is a discriminated union: `{ type: 'text', value: string } | { type: 'multiSelect', value: string[] } | { type: 'people', value: UserLike } | { type: 'date', value: IDateFilterValue }`.
 
 **Orchestration hooks:**
 - `useOGrid` — Pagination, sorting, filtering, visibility, editing, row selection, status bar. Exposes `IOGridApi` ref.
-- `useDataGridState` — All DataGridTable state (layout, selection, editing, keyboard, clipboard, context menu).
+- `useDataGridState` — All DataGridTable state, grouped into 6 sub-objects: `layout`, `rowSelection`, `editing`, `interaction`, `contextMenu`, `viewModels`.
 
 **Headless state hooks** (consumed by UI packages):
 - `useColumnHeaderFilterState` — Filter popover state (open, temp values, apply/clear, people search debounce)
@@ -56,7 +56,7 @@ npm run docs:build              # Build docs site
 
 **Feature hooks:** `useActiveCell`, `useCellEditing`, `useCellSelection`, `useRowSelection`, `useKeyboardNavigation`, `useClipboard`, `useFillHandle`, `useUndoRedo`, `useContextMenu`, `useColumnResize`, `useFilterOptions`, `useDebounce`
 
-**Utilities:** `exportToCsv`, `getCellValue`, `flattenColumns`, `buildHeaderRows`, `getPaginationViewModel`, `getHeaderFilterConfig`, `getCellRenderDescriptor`, `getStatusBarParts`, `getDataGridStatusBarConfig`, `computeAggregations`, `GRID_CONTEXT_MENU_ITEMS`, `getContextMenuHandlers`, `formatShortcut`
+**Utilities:** `exportToCsv`, `getCellValue`, `flattenColumns`, `buildHeaderRows`, `getPaginationViewModel`, `getHeaderFilterConfig`, `getCellRenderDescriptor`, `resolveCellDisplayContent`, `resolveCellStyle`, `buildInlineEditorProps`, `buildPopoverEditorProps`, `getCellInteractionProps`, `getStatusBarParts`, `getDataGridStatusBarConfig`, `computeAggregations`, `processClientSideData`, `GRID_CONTEXT_MENU_ITEMS`, `getContextMenuHandlers`, `formatShortcut`
 
 **Headless components:** `OGridLayout`, `StatusBar`, `GridContextMenu`, `SideBar`
 
@@ -104,7 +104,7 @@ Pure React hooks. No external state libraries. Supports uncontrolled (internal)
 
 ## Testing
 
-**504 tests** across 4 packages (Core: 228, Radix: 92, Fluent: 92, Material: 92).
+**521 tests** across 4 packages (Core: 245, Radix: 92, Fluent: 92, Material: 92).
 
 - Jest 29 + React Testing Library 16 + ts-jest, jsdom environment, 10s timeout
 - Core tests: `packages/core/src/*/__tests__/**/*.test.ts(x)`
@@ -214,15 +214,14 @@ Opus is the **orchestrator**. For multi-step tasks, break the work into well-sco
 - [ ] State logic stays in core hooks — UI packages should only add view-layer code.
 - [ ] If the same pattern appears in 2+ UI packages, consider a shared factory or headless component.
 
-## Remaining Duplication (Future Work)
+## View Layer Architecture (Phase 2 Complete)
 
-State and behavior are centralized in core. The remaining triplication is in the **view layer** of DataGridTable:
+State and behavior are centralized in core. Each UI package's `renderCellContent` is a thin ~50-line mapping from core-computed descriptors to framework-specific JSX, using 6 core helpers: `getCellRenderDescriptor`, `buildInlineEditorProps`, `buildPopoverEditorProps`, `getCellInteractionProps`, `resolveCellDisplayContent`, `resolveCellStyle`.
 
-| What's shared | What's triplicated |
+| What's in core | What's per-framework |
 |---|---|
 | `useDataGridState`, all sub-hooks, types, utils | Table primitives (Fluent DataGrid vs MUI Table vs native `<table>`) |
-| `getCellRenderDescriptor` (cell mode, flags) | Cell rendering (editing vs display, active/range styling) |
-| `getHeaderFilterConfig` | Header filter rendering (Fluent/MUI/Radix popovers) |
+| `getCellRenderDescriptor` + 5 builder helpers | Popover rendering (Radix/Fluent/MUI popover APIs) |
+| `getHeaderFilterConfig` | Header filter rendering (framework-specific popovers) |
 | `getPaginationViewModel` | Pagination rendering (Fluent/MUI/native buttons) |
-
-**Next step (Phase 2):** Use `getCellRenderDescriptor` in all three DataGridTable implementations so cell rendering is "map descriptor to component" instead of reimplementing the booleans and callbacks. This would make each DataGridTable a thin mapping from descriptors to framework-specific primitives.
+| `processClientSideData` | CSS/styling (CSS modules vs MUI sx) |

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "OGrid core – framework-agnostic types, hooks, and utilities for OGrid data tables.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",

packages/core/src/components/OGridLayout.tsx

@@ -13,15 +13,9 @@ export interface OGridLayoutProps {
   containerComponent?: React.ElementType;
   /** Extra props for the root container (e.g. sx for MUI Box). */
   containerProps?: Record<string, unknown>;
-  /** Gap between deprecated title and the bordered container in px (default: 8). */
-  gap?: number | string;
   className?: string;
-  /** @deprecated Render title outside OGrid. Renders above the bordered container during transition. */
-  title?: React.ReactNode;
   /** Custom toolbar content (left-aligned in toolbar strip). */
   toolbar?: React.ReactNode;
-  /** @deprecated Use toolbarEnd instead. */
-  columnChooser?: React.ReactNode;
   /** Built-in toolbar items rendered on the right side (column chooser, etc.). */
   toolbarEnd?: React.ReactNode;
   /** Grid content (DataGridTable). */
@@ -95,7 +89,6 @@ const gridChildStyle: React.CSSProperties = {
 
 /**
  * Renders OGrid layout as a unified bordered container:
- *   [deprecated title above]
  *   ┌────────────────────────────────────┐
  *   │ [toolbar strip]                    │
  *   ├────────────────────────────────────┤
@@ -108,30 +101,22 @@ export function OGridLayout(props: OGridLayoutProps): React.ReactElement {
   const {
     containerComponent: Container = 'div',
     containerProps = {},
-    gap = 8,
     className,
-    title,
     toolbar,
-    columnChooser,
-    toolbarEnd: toolbarEndProp,
+    toolbarEnd,
     children,
     pagination,
     sideBar,
   } = props;
 
   const hasSideBar = sideBar != null;
   const sideBarPosition = sideBar?.position ?? 'right';
-
-  // Backward compat: columnChooser prop → toolbarEnd
-  const toolbarEnd = toolbarEndProp ?? columnChooser;
   const hasToolbar = toolbar != null || toolbarEnd != null;
 
-  // Root styles: flex column, fill parent height, gap for deprecated title spacing
   const rootStyle: React.CSSProperties = {
     display: 'flex',
     flexDirection: 'column',
     height: '100%',
-    gap: title != null ? (typeof gap === 'number' ? `${gap}px` : gap) : undefined,
   };
 
   return (
@@ -140,9 +125,6 @@ export function OGridLayout(props: OGridLayoutProps): React.ReactElement {
       style={rootStyle}
       {...containerProps}
     >
-      {/* Deprecated: title renders ABOVE the bordered container */}
-      {title != null && <div style={{ margin: 0 }}>{title}</div>}
-
       {/* === Bordered container === */}
       <div style={borderedContainerStyle}>
         {/* Toolbar strip */}

packages/core/src/components/SideBar.tsx

@@ -4,7 +4,7 @@
  * Uses inline styles for framework-agnostic rendering.
  */
 import * as React from 'react';
-import type { IColumnDefinition, IDateFilterValue, SideBarPanelId } from '../types';
+import type { IColumnDefinition, IDateFilterValue, SideBarPanelId, IFilters, FilterValue } from '../types';
 
 /** Describes a filterable column for the sidebar filters panel. */
 export interface SideBarFilterColumn {
@@ -27,12 +27,8 @@ export interface SideBarProps {
   onSetVisibleColumns: (columns: Set<string>) => void;
   // Filters panel
   filterableColumns: SideBarFilterColumn[];
-  multiSelectFilters: Record<string, string[]>;
-  textFilters: Record<string, string>;
-  onMultiSelectFilterChange: (key: string, values: string[]) => void;
-  onTextFilterChange: (key: string, value: string) => void;
-  dateFilters: Record<string, IDateFilterValue>;
-  onDateFilterChange: (key: string, value: IDateFilterValue | undefined) => void;
+  filters: IFilters;
+  onFilterChange: (key: string, value: FilterValue | undefined) => void;
   filterOptions: Record<string, string[]>;
 }
 
@@ -55,12 +51,8 @@ export function SideBar(props: SideBarProps): React.ReactElement {
     onVisibilityChange,
     onSetVisibleColumns,
     filterableColumns,
-    multiSelectFilters,
-    textFilters,
-    onMultiSelectFilterChange,
-    onTextFilterChange,
-    dateFilters,
-    onDateFilterChange,
+    filters,
+    onFilterChange,
     filterOptions,
   } = props;
 
@@ -157,12 +149,8 @@ export function SideBar(props: SideBarProps): React.ReactElement {
         {activePanel === 'filters' && (
           <FiltersPanel
             filterableColumns={filterableColumns}
-            multiSelectFilters={multiSelectFilters}
-            textFilters={textFilters}
-            onMultiSelectFilterChange={onMultiSelectFilterChange}
-            onTextFilterChange={onTextFilterChange}
-            dateFilters={dateFilters}
-            onDateFilterChange={onDateFilterChange}
+            filters={filters}
+            onFilterChange={onFilterChange}
             filterOptions={filterOptions}
           />
         )}
@@ -238,15 +226,11 @@ function ColumnsPanel(props: {
 
 function FiltersPanel(props: {
   filterableColumns: SideBarFilterColumn[];
-  multiSelectFilters: Record<string, string[]>;
-  textFilters: Record<string, string>;
-  onMultiSelectFilterChange: (key: string, values: string[]) => void;
-  onTextFilterChange: (key: string, value: string) => void;
-  dateFilters: Record<string, IDateFilterValue>;
-  onDateFilterChange: (key: string, value: IDateFilterValue | undefined) => void;
+  filters: IFilters;
+  onFilterChange: (key: string, value: FilterValue | undefined) => void;
   filterOptions: Record<string, string[]>;
 }): React.ReactElement {
-  const { filterableColumns, multiSelectFilters, textFilters, onMultiSelectFilterChange, onTextFilterChange, dateFilters, onDateFilterChange, filterOptions } = props;
+  const { filterableColumns, filters, onFilterChange, filterOptions } = props;
 
   if (filterableColumns.length === 0) {
     return <div style={{ color: 'var(--ogrid-muted, #999)', fontStyle: 'italic' }}>No filterable columns</div>;
@@ -262,8 +246,8 @@ function FiltersPanel(props: {
             {col.filterType === 'text' && (
               <input
                 type="text"
-                value={textFilters[filterKey] ?? ''}
-                onChange={(e) => onTextFilterChange(filterKey, e.target.value)}
+                value={filters[filterKey]?.type === 'text' ? filters[filterKey]!.value : ''}
+                onChange={(e) => onFilterChange(filterKey, e.target.value ? { type: 'text', value: e.target.value } : undefined)}
                 placeholder={`Filter ${col.name}...`}
                 aria-label={`Filter ${col.name}`}
                 style={{ width: '100%', boxSizing: 'border-box', padding: '4px 6px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 }}
@@ -275,11 +259,12 @@ function FiltersPanel(props: {
                   From:
                   <input
                     type="date"
-                    value={dateFilters[filterKey]?.from ?? ''}
+                    value={filters[filterKey]?.type === 'date' ? (filters[filterKey]!.value.from ?? '') : ''}
                     onChange={(e) => {
                       const from = e.target.value || undefined;
-                      const to = dateFilters[filterKey]?.to;
-                      onDateFilterChange(filterKey, from || to ? { from, to } : undefined);
+                      const existingValue = filters[filterKey]?.type === 'date' ? filters[filterKey]!.value : {};
+                      const to = existingValue.to;
+                      onFilterChange(filterKey, from || to ? { type: 'date', value: { from, to } } : undefined);
                     }}
                     aria-label={`${col.name} from date`}
                     style={{ flex: 1, padding: '2px 4px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 }}
@@ -289,11 +274,12 @@ function FiltersPanel(props: {
                   To:
                   <input
                     type="date"
-                    value={dateFilters[filterKey]?.to ?? ''}
+                    value={filters[filterKey]?.type === 'date' ? (filters[filterKey]!.value.to ?? '') : ''}
                     onChange={(e) => {
                       const to = e.target.value || undefined;
-                      const from = dateFilters[filterKey]?.from;
-                      onDateFilterChange(filterKey, from || to ? { from, to } : undefined);
+                      const existingValue = filters[filterKey]?.type === 'date' ? filters[filterKey]!.value : {};
+                      const from = existingValue.from;
+                      onFilterChange(filterKey, from || to ? { type: 'date', value: { from, to } } : undefined);
                     }}
                     aria-label={`${col.name} to date`}
                     style={{ flex: 1, padding: '2px 4px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 }}
@@ -304,7 +290,7 @@ function FiltersPanel(props: {
             {col.filterType === 'multiSelect' && (
               <div style={{ maxHeight: 120, overflowY: 'auto' }} role="group" aria-label={`${col.name} options`}>
                 {(filterOptions[filterKey] ?? []).map((opt) => {
-                  const selected = (multiSelectFilters[filterKey] ?? []).includes(opt);
+                  const selected = filters[filterKey]?.type === 'multiSelect' ? filters[filterKey]!.value.includes(opt) : false;
                   return (
                     <label
                       key={opt}
@@ -314,11 +300,11 @@ function FiltersPanel(props: {
                         type="checkbox"
                         checked={selected}
                         onChange={(e) => {
-                          const current = multiSelectFilters[filterKey] ?? [];
+                          const current = filters[filterKey]?.type === 'multiSelect' ? filters[filterKey]!.value : [];
                           const next = e.target.checked
                             ? [...current, opt]
                             : current.filter((v) => v !== opt);
-                          onMultiSelectFilterChange(filterKey, next);
+                          onFilterChange(filterKey, next.length > 0 ? { type: 'multiSelect', value: next } : undefined);
                         }}
                       />
                       <span>{opt}</span>