@alaarab/ogrid-react 2.0.0-beta

package/dist/types/hooks/useKeyboardNavigation.d.ts

@@ -0,0 +1,47 @@
+import type { RowId, IActiveCell, ISelectionRange, IColumnDef, ICellValueChangedEvent, RowSelectionMode } from '../types';
+import type { EditingCell } from './useCellEditing';
+import type { ContextMenuPosition } from './useContextMenu';
+export interface UseKeyboardNavigationParams<T> {
+    data: {
+        items: T[];
+        visibleCols: IColumnDef<T>[];
+        colOffset: number;
+        hasCheckboxCol: boolean;
+        visibleColumnCount: number;
+        getRowId: (item: T) => RowId;
+    };
+    state: {
+        activeCell: IActiveCell | null;
+        selectionRange: ISelectionRange | null;
+        editingCell: EditingCell | null;
+        selectedRowIds: Set<RowId>;
+    };
+    handlers: {
+        setActiveCell: (cell: IActiveCell | null) => void;
+        setSelectionRange: (range: ISelectionRange | null) => void;
+        setEditingCell: (cell: EditingCell | null) => void;
+        handleRowCheckboxChange: (rowId: RowId, checked: boolean, rowIndex: number, shiftKey: boolean) => void;
+        handleCopy: () => void;
+        handleCut: () => void;
+        handlePaste: () => Promise<void>;
+        setContextMenu: (pos: ContextMenuPosition | null) => void;
+        onUndo?: () => void;
+        onRedo?: () => void;
+        clearClipboardRanges?: () => void;
+    };
+    features: {
+        editable?: boolean;
+        onCellValueChanged: ((event: ICellValueChangedEvent<T>) => void) | undefined;
+        rowSelection: RowSelectionMode;
+        wrapperRef: React.RefObject<HTMLElement | null>;
+    };
+}
+export interface UseKeyboardNavigationResult {
+    handleGridKeyDown: (e: React.KeyboardEvent) => void;
+}
+/**
+ * Handles all keyboard navigation, shortcuts, and cell editing triggers for the grid.
+ * @param params - Grouped data, state, handlers, and feature flags for keyboard interactions.
+ * @returns Keyboard event handler for the grid wrapper.
+ */
+export declare function useKeyboardNavigation<T>(params: UseKeyboardNavigationParams<T>): UseKeyboardNavigationResult;

package/dist/types/hooks/useLatestRef.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a ref that always holds the latest value.
+ * Useful for capturing volatile state in stable callbacks
+ * without adding the value to dependency arrays.
+ */
+export declare function useLatestRef<T>(value: T): React.MutableRefObject<T>;

package/dist/types/hooks/useMultiSelectFilterState.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Multi-select filter state sub-hook for column header filters.
+ * Manages temporary selection set, search text, debounced search, filtered options, and select/clear handlers.
+ */
+import { type Dispatch, type SetStateAction } from 'react';
+export interface UseMultiSelectFilterStateParams {
+    selectedValues?: string[];
+    onFilterChange?: (values: string[]) => void;
+    options?: string[];
+    isFilterOpen: boolean;
+}
+export interface UseMultiSelectFilterStateResult {
+    tempSelected: Set<string>;
+    setTempSelected: Dispatch<SetStateAction<Set<string>>>;
+    searchText: string;
+    setSearchText: (v: string) => void;
+    debouncedSearchText: string;
+    filteredOptions: string[];
+    handleCheckboxChange: (option: string, checked: boolean) => void;
+    handleSelectAll: () => void;
+    handleClearSelection: () => void;
+    handleApplyMultiSelect: () => void;
+}
+export declare function useMultiSelectFilterState(params: UseMultiSelectFilterStateParams): UseMultiSelectFilterStateResult;

package/dist/types/hooks/useOGrid.d.ts

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import type { SideBarProps } from '../components/SideBar';
+import type { IOGridProps, IOGridDataGridProps, IOGridApi, IFilters, IColumnDefinition } from '../types';
+/** Resolved column chooser placement. */
+export type ColumnChooserPlacement = 'toolbar' | 'sidebar' | 'none';
+/** Pagination state and handlers. */
+export interface UseOGridPagination {
+    page: number;
+    pageSize: number;
+    displayTotalCount: number;
+    setPage: (p: number) => void;
+    setPageSize: (size: number) => void;
+    pageSizeOptions?: number[];
+    entityLabelPlural: string;
+}
+/** Column chooser state and handlers. */
+export interface UseOGridColumnChooser {
+    columns: IColumnDefinition[];
+    visibleColumns: Set<string>;
+    onVisibilityChange: (columnKey: string, isVisible: boolean) => void;
+    placement: ColumnChooserPlacement;
+}
+/** Layout / chrome configuration. */
+export interface UseOGridLayout {
+    toolbar: React.ReactNode;
+    toolbarBelow: React.ReactNode;
+    className?: string;
+    emptyState?: {
+        message?: React.ReactNode;
+        render?: () => React.ReactNode;
+    };
+    sideBarProps: SideBarProps | null;
+}
+/** Filter state. */
+export interface UseOGridFilters {
+    hasActiveFilters: boolean;
+    setFilters: (f: IFilters) => void;
+}
+export interface UseOGridResult<T> {
+    dataGridProps: IOGridDataGridProps<T>;
+    pagination: UseOGridPagination;
+    columnChooser: UseOGridColumnChooser;
+    layout: UseOGridLayout;
+    filters: UseOGridFilters;
+}
+/**
+ * Top-level orchestration hook for OGrid: manages pagination, sorting, filtering, column visibility, and sidebar.
+ * @param props - All OGrid props (columns, data, callbacks, feature flags).
+ * @param ref - Forwarded ref for imperative API (refresh, export, applyColumnState).
+ * @returns Grouped props for DataGridTable, pagination controls, column chooser, layout, and filters.
+ */
+export declare function useOGrid<T>(props: IOGridProps<T>, ref: React.Ref<IOGridApi<T>>): UseOGridResult<T>;

package/dist/types/hooks/usePeopleFilterState.d.ts

@@ -0,0 +1,25 @@
+/**
+ * People filter state sub-hook for column header filters.
+ * Manages people search text, suggestions, loading state, input ref, and user select/clear handlers.
+ * Includes debounced people search effect.
+ */
+import { type RefObject } from 'react';
+import type { UserLike } from '../types/dataGridTypes';
+import type { ColumnFilterType } from '../types/columnTypes';
+export interface UsePeopleFilterStateParams {
+    selectedUser?: UserLike;
+    onUserChange?: (user: UserLike | undefined) => void;
+    peopleSearch?: (query: string) => Promise<UserLike[]>;
+    isFilterOpen: boolean;
+    filterType: ColumnFilterType;
+}
+export interface UsePeopleFilterStateResult {
+    peopleSuggestions: UserLike[];
+    isPeopleLoading: boolean;
+    peopleSearchText: string;
+    setPeopleSearchText: (v: string) => void;
+    peopleInputRef: RefObject<HTMLInputElement | null>;
+    handleUserSelect: (user: UserLike) => void;
+    handleClearUser: () => void;
+}
+export declare function usePeopleFilterState(params: UsePeopleFilterStateParams): UsePeopleFilterStateResult;

package/dist/types/hooks/useRichSelectState.d.ts

@@ -0,0 +1,22 @@
+export interface UseRichSelectStateParams {
+    values: unknown[];
+    formatValue?: (value: unknown) => string;
+    initialValue: unknown;
+    onCommit: (value: unknown) => void;
+    onCancel: () => void;
+}
+export interface UseRichSelectStateResult {
+    searchText: string;
+    setSearchText: (text: string) => void;
+    filteredValues: unknown[];
+    highlightedIndex: number;
+    handleKeyDown: (e: React.KeyboardEvent) => void;
+    selectValue: (value: unknown) => void;
+    getDisplayText: (value: unknown) => string;
+}
+/**
+ * Manages searchable rich select editor state with keyboard navigation (arrow keys, enter, escape).
+ * @param params - Values, format function, initial value, and commit/cancel callbacks.
+ * @returns Search text, filtered values, highlighted index, keyboard handler, and select function.
+ */
+export declare function useRichSelectState(params: UseRichSelectStateParams): UseRichSelectStateResult;

package/dist/types/hooks/useRowSelection.d.ts

@@ -0,0 +1,22 @@
+import type { RowId, RowSelectionMode, IRowSelectionChangeEvent } from '../types';
+export interface UseRowSelectionParams<T> {
+    items: T[];
+    getRowId: (item: T) => RowId;
+    rowSelection: RowSelectionMode;
+    controlledSelectedRows: Set<RowId> | undefined;
+    onSelectionChange: ((event: IRowSelectionChangeEvent<T>) => void) | undefined;
+}
+export interface UseRowSelectionResult {
+    selectedRowIds: Set<RowId>;
+    updateSelection: (newSelectedIds: Set<RowId>) => void;
+    handleRowCheckboxChange: (rowId: RowId, checked: boolean, rowIndex: number, shiftKey: boolean) => void;
+    handleSelectAll: (checked: boolean) => void;
+    allSelected: boolean;
+    someSelected: boolean;
+}
+/**
+ * Manages row selection state for single or multiple selection modes with shift-click range support.
+ * @param params - Items, getRowId, selection mode, controlled state, and selection change callback.
+ * @returns Selected row IDs, update function, checkbox handlers, and selection state booleans.
+ */
+export declare function useRowSelection<T>(params: UseRowSelectionParams<T>): UseRowSelectionResult;

package/dist/types/hooks/useSideBarState.d.ts

@@ -0,0 +1,20 @@
+import type { SideBarPanelId, ISideBarDef } from '../types';
+export interface UseSideBarStateParams {
+    config: boolean | ISideBarDef | undefined;
+}
+export interface UseSideBarStateResult {
+    isEnabled: boolean;
+    activePanel: SideBarPanelId | null;
+    setActivePanel: (panel: SideBarPanelId | null) => void;
+    panels: SideBarPanelId[];
+    position: 'left' | 'right';
+    isOpen: boolean;
+    toggle: (panel: SideBarPanelId) => void;
+    close: () => void;
+}
+/**
+ * Manages side bar panel state: enabled panels, active panel, position, and toggle/close handlers.
+ * @param params - Side bar config (boolean, ISideBarDef, or undefined).
+ * @returns Enabled flag, active panel, setters, panel list, position, open state, toggle, and close.
+ */
+export declare function useSideBarState(params: UseSideBarStateParams): UseSideBarStateResult;

package/dist/types/hooks/useTableLayout.d.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from 'react';
+import type { IColumnDef } from '../types';
+export interface UseTableLayoutParams<T> {
+    wrapperRef: RefObject<HTMLDivElement | null>;
+    visibleCols: IColumnDef<T>[];
+    flatColumns: IColumnDef<T>[];
+    hasCheckboxCol: boolean;
+    initialColumnWidths?: Record<string, number>;
+    onColumnResized?: (columnId: string, width: number) => void;
+}
+export interface UseTableLayoutResult {
+    containerWidth: number;
+    minTableWidth: number;
+    desiredTableWidth: number;
+    columnSizingOverrides: Record<string, {
+        widthPx: number;
+    }>;
+    setColumnSizingOverrides: React.Dispatch<React.SetStateAction<Record<string, {
+        widthPx: number;
+    }>>>;
+    onColumnResized?: (columnId: string, width: number) => void;
+}
+/**
+ * Manages table layout: container width measurement, column sizing overrides,
+ * min/desired table width calculations.
+ */
+export declare function useTableLayout<T>(params: UseTableLayoutParams<T>): UseTableLayoutResult;

package/dist/types/hooks/useTextFilterState.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Text filter state sub-hook for column header filters.
+ * Manages temporary text value and apply/clear handlers.
+ */
+export interface UseTextFilterStateParams {
+    textValue?: string;
+    onTextChange?: (value: string) => void;
+    isFilterOpen: boolean;
+}
+export interface UseTextFilterStateResult {
+    tempTextValue: string;
+    setTempTextValue: (v: string) => void;
+    handleTextApply: () => void;
+    handleTextClear: () => void;
+}
+export declare function useTextFilterState(params: UseTextFilterStateParams): UseTextFilterStateResult;

package/dist/types/hooks/useUndoRedo.d.ts

@@ -0,0 +1,23 @@
+import type { ICellValueChangedEvent } from '../types';
+export interface UseUndoRedoParams<T> {
+    onCellValueChanged: ((event: ICellValueChangedEvent<T>) => void) | undefined;
+    maxUndoDepth?: number;
+}
+export interface UseUndoRedoResult<T> {
+    onCellValueChanged: ((event: ICellValueChangedEvent<T>) => void) | undefined;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Start a batch — all changes until endBatch() are grouped as one undo step. */
+    beginBatch: () => void;
+    /** End a batch — commits the accumulated changes as a single undo entry. */
+    endBatch: () => void;
+    /** The configured maximum undo stack depth. */
+    maxUndoDepth: number;
+}
+/**
+ * Wraps onCellValueChanged with an undo/redo history stack.
+ * Supports batch operations: changes between beginBatch/endBatch are one undo step.
+ */
+export declare function useUndoRedo<T>(params: UseUndoRedoParams<T>): UseUndoRedoResult<T>;

package/dist/types/index.d.ts

@@ -0,0 +1,23 @@
+export { CHECKBOX_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from '@alaarab/ogrid-core';
+export type { ColumnFilterType, IColumnFilterDef, IColumnMeta, IColumnDef, IColumnGroupDef, IColumnDefinition, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IValueParserParams, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, IOGridApi, IOGridProps, IOGridDataGridProps, RowSelectionMode, RowId, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, HeaderCell, HeaderRow, SideBarPanelId, ISideBarDef, IDateFilterValue, } from './types';
+export { toUserLike, isInSelectionRange, normalizeSelectionRange } from './types';
+export { useFilterOptions, useOGrid, useActiveCell, useCellEditing, useContextMenu, useCellSelection, useClipboard, useRowSelection, useKeyboardNavigation, useUndoRedo, useDebounce, useFillHandle, useDataGridState, useColumnHeaderFilterState, useTextFilterState, useMultiSelectFilterState, usePeopleFilterState, useDateFilterState, useColumnChooserState, useInlineCellEditorState, useColumnResize, useRichSelectState, useSideBarState, useTableLayout, useLatestRef, } from './hooks';
+export type { UseFilterOptionsResult, UseOGridResult, UseOGridPagination, UseOGridColumnChooser, UseOGridLayout, UseOGridFilters, ColumnChooserPlacement, UseActiveCellResult, UseCellEditingResult, EditingCell, UseContextMenuResult, ContextMenuPosition, UseCellSelectionResult, UseCellSelectionParams, UseClipboardResult, UseClipboardParams, UseRowSelectionResult, UseRowSelectionParams, UseKeyboardNavigationResult, UseKeyboardNavigationParams, UseUndoRedoResult, UseUndoRedoParams, UseFillHandleResult, UseFillHandleParams, UseDataGridStateParams, UseDataGridStateResult, DataGridLayoutState, DataGridRowSelectionState, DataGridEditingState, DataGridCellInteractionState, DataGridContextMenuState, DataGridViewModelState, UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, UseTextFilterStateParams, UseTextFilterStateResult, UseMultiSelectFilterStateParams, UseMultiSelectFilterStateResult, UsePeopleFilterStateParams, UsePeopleFilterStateResult, UseDateFilterStateParams, UseDateFilterStateResult, UseColumnChooserStateParams, UseColumnChooserStateResult, UseInlineCellEditorStateParams, UseInlineCellEditorStateResult, InlineCellEditorType, UseColumnResizeParams, UseColumnResizeResult, UseRichSelectStateParams, UseRichSelectStateResult, UseSideBarStateParams, UseSideBarStateResult, UseTableLayoutParams, UseTableLayoutResult, } from './hooks';
+export { OGridLayout } from './components/OGridLayout';
+export type { OGridLayoutProps } from './components/OGridLayout';
+export { StatusBar } from './components/StatusBar';
+export type { StatusBarProps, StatusBarClassNames } from './components/StatusBar';
+export { BaseInlineCellEditor, editorWrapperStyle, editorInputStyle, richSelectWrapperStyle, richSelectDropdownStyle, richSelectOptionStyle, richSelectOptionHighlightedStyle, richSelectNoMatchesStyle, selectEditorStyle, } from './components/BaseInlineCellEditor';
+export type { BaseInlineCellEditorProps } from './components/BaseInlineCellEditor';
+export { GridContextMenu } from './components/GridContextMenu';
+export type { GridContextMenuProps, GridContextMenuClassNames } from './components/GridContextMenu';
+export { MarchingAntsOverlay } from './components/MarchingAntsOverlay';
+export type { MarchingAntsOverlayProps } from './components/MarchingAntsOverlay';
+export { SideBar } from './components/SideBar';
+export type { SideBarProps, SideBarFilterColumn } from './components/SideBar';
+export { CellErrorBoundary } from './components/CellErrorBoundary';
+export type { CellErrorBoundaryProps } from './components/CellErrorBoundary';
+export { EmptyState } from './components/EmptyState';
+export type { EmptyStateProps } from './components/EmptyState';
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, getCellValue, flattenColumns, buildHeaderRows, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, getStatusBarParts, getDataGridStatusBarConfig, GRID_CONTEXT_MENU_ITEMS, getContextMenuHandlers, formatShortcut, getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, getHeaderFilterConfig, getCellRenderDescriptor, isRowInRange, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, getCellInteractionProps, parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, computeAggregations, processClientSideData, areGridRowPropsEqual, } from './utils';
+export type { CsvColumn, StatusBarPart, StatusBarPartsInput, GridContextMenuItem, GridContextMenuHandlerProps, PaginationViewModel, HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, CellInteractionHandlers, ParseValueResult, AggregationResult, GridRowComparatorProps, } from './utils';

package/dist/types/storybook/index.d.ts

@@ -0,0 +1,2 @@
+export { storyRows, storyGetRowId, noop, editableInitialRows, editableColumns, NotesPopupEditor, spreadsheetRows, spreadsheetColumns, departmentFilterOptions, statusFilterOptions, } from './mockData';
+export type { StoryRow, EditableRow, RowWithNotes, SpreadsheetRow, } from './mockData';

package/dist/types/storybook/mockData.d.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import type { IColumnDef, ICellEditorProps } from '../types';
+export interface StoryRow {
+    id: string;
+    name: string;
+    status: string;
+    owner: string;
+    approved?: boolean;
+}
+export declare const storyRows: StoryRow[];
+export declare const storyGetRowId: (r: StoryRow) => string;
+export declare const noop: () => void;
+export interface EditableRow {
+    id: string;
+    name: string;
+    status: string;
+    approved: boolean;
+}
+export declare const editableInitialRows: EditableRow[];
+export declare const editableColumns: IColumnDef<EditableRow>[];
+export interface RowWithNotes extends EditableRow {
+    notes?: string;
+}
+export declare function NotesPopupEditor<T>({ value, onValueChange, onCommit, onCancel }: ICellEditorProps<T>): React.ReactElement;
+export interface SpreadsheetRow {
+    id: string;
+    name: string;
+    department: string;
+    salary: number;
+    startDate: string;
+    status: string;
+    email: string;
+}
+export declare const spreadsheetRows: SpreadsheetRow[];
+export declare const spreadsheetColumns: IColumnDef<SpreadsheetRow>[];
+export declare const departmentFilterOptions: string[];
+export declare const statusFilterOptions: string[];

package/dist/types/types/columnTypes.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { IColumnDef as ICoreColumnDef, CellEditorParams } from '@alaarab/ogrid-core';
+export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, ICellValueChangedEvent, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } from '@alaarab/ogrid-core';
+/** Props passed to custom cell editor components. */
+export interface ICellEditorProps<T = unknown> {
+    value: unknown;
+    onValueChange: (value: unknown) => void;
+    onCommit: () => void;
+    onCancel: () => void;
+    item: T;
+    column: IColumnDef<T>;
+    cellEditorParams?: CellEditorParams;
+}
+/**
+ * React-specific column definition. Extends core's framework-agnostic IColumnDef
+ * with renderCell, cellStyle, and a narrowed cellEditor type.
+ */
+export interface IColumnDef<T = unknown> extends ICoreColumnDef<T> {
+    /** Custom cell renderer (React-specific). */
+    renderCell?: (item: T) => React.ReactNode;
+    /** Static or per-row cell inline styles (React-specific). */
+    cellStyle?: React.CSSProperties | ((item: T) => React.CSSProperties);
+    /** Built-in editor type or custom React component. */
+    cellEditor?: 'text' | 'select' | 'checkbox' | 'richSelect' | 'date' | React.ComponentType<ICellEditorProps<T>>;
+}

package/dist/types/types/dataGridTypes.d.ts

@@ -0,0 +1,152 @@
+import type { ReactNode } from 'react';
+import type { IColumnDef, IColumnGroupDef, ICellValueChangedEvent } from './columnTypes';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IOGridApi, } from '@alaarab/ogrid-core';
+export { toUserLike, isInSelectionRange, normalizeSelectionRange } from '@alaarab/ogrid-core';
+import type { RowId, UserLike, IFilters, FilterValue, RowSelectionMode, IRowSelectionChangeEvent, IStatusBarProps, IDataSource, ISideBarDef } from '@alaarab/ogrid-core';
+/** Base props shared by both client-side and server-side OGrid modes. */
+interface IOGridBaseProps<T> {
+    columns: (IColumnDef<T> | IColumnGroupDef<T>)[];
+    getRowId: (item: T) => RowId;
+    page?: number;
+    pageSize?: number;
+    sort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    filters?: IFilters;
+    visibleColumns?: Set<string>;
+    isLoading?: boolean;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (size: number) => void;
+    onSortChange?: (sort: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }) => void;
+    onFiltersChange?: (filters: IFilters) => void;
+    onVisibleColumnsChange?: (cols: Set<string>) => void;
+    columnOrder?: string[];
+    onColumnOrderChange?: (order: string[]) => void;
+    /** Called when a column is resized by the user. */
+    onColumnResized?: (columnId: string, width: number) => void;
+    /** Called when a column is pinned or unpinned. */
+    onColumnPinned?: (columnId: string, pinned: 'left' | 'right' | null) => void;
+    freezeRows?: number;
+    freezeCols?: number;
+    editable?: boolean;
+    /** Enable spreadsheet-like cell selection (active cell, range, fill handle, clipboard, context menu). Default: true. */
+    cellSelection?: boolean;
+    onCellValueChanged?: (event: ICellValueChangedEvent<T>) => void;
+    onUndo?: () => void;
+    onRedo?: () => void;
+    canUndo?: boolean;
+    canRedo?: boolean;
+    rowSelection?: RowSelectionMode;
+    selectedRows?: Set<RowId>;
+    onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
+    statusBar?: boolean | IStatusBarProps;
+    defaultPageSize?: number;
+    defaultSortBy?: string;
+    defaultSortDirection?: 'asc' | 'desc';
+    toolbar?: ReactNode;
+    /** Secondary toolbar row rendered below the primary toolbar (e.g. active filter chips). */
+    toolbarBelow?: ReactNode;
+    emptyState?: {
+        message?: ReactNode;
+        render?: () => ReactNode;
+    };
+    entityLabelPlural?: string;
+    className?: string;
+    /** Where the column chooser renders.
+     *  - `true` or `'toolbar'` (default): column chooser button in the toolbar strip.
+     *  - `'sidebar'`: column chooser only available via the sidebar columns panel.
+     *  - `false`: column chooser hidden entirely. */
+    columnChooser?: boolean | 'toolbar' | 'sidebar';
+    layoutMode?: 'content' | 'fill';
+    /** When true, horizontal scrolling is suppressed (overflow-x hidden). */
+    suppressHorizontalScroll?: boolean;
+    /** Side bar configuration. `true` shows default panels (columns + filters). Pass ISideBarDef for options. */
+    sideBar?: boolean | ISideBarDef;
+    /** Page size options shown in the pagination dropdown. Default: [10, 20, 50, 100]. */
+    pageSizeOptions?: number[];
+    /** Fires once when the grid first renders with data (useful for restoring column state). */
+    onFirstDataRendered?: () => void;
+    /** Called when server-side fetchPage fails. */
+    onError?: (error: unknown) => void;
+    /** Called when a cell renderer or custom editor throws an error. */
+    onCellError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+}
+/** Client-side mode: pass a data array. */
+export interface IOGridClientProps<T> extends IOGridBaseProps<T> {
+    data: T[];
+    dataSource?: never;
+}
+/** Server-side mode: pass a dataSource. */
+export interface IOGridServerProps<T> extends IOGridBaseProps<T> {
+    data?: never;
+    dataSource: IDataSource<T>;
+}
+/** Props for the OGrid wrapper component (shared across Fluent, Material, Radix).
+ *  Must provide either `data` (client-side) or `dataSource` (server-side), not both. */
+export type IOGridProps<T> = IOGridClientProps<T> | IOGridServerProps<T>;
+/** Props passed from useOGrid to the framework-specific DataGridTable. */
+export interface IOGridDataGridProps<T> {
+    items: T[];
+    columns: (IColumnDef<T> | IColumnGroupDef<T>)[];
+    getRowId: (item: T) => RowId;
+    sortBy?: string;
+    sortDirection: 'asc' | 'desc';
+    onColumnSort: (columnKey: string) => void;
+    visibleColumns: Set<string>;
+    /** Optional column display order (column ids). When set, visible columns are ordered by this array. */
+    columnOrder?: string[];
+    onColumnOrderChange?: (order: string[]) => void;
+    /** Called when a column is resized by the user. */
+    onColumnResized?: (columnId: string, width: number) => void;
+    /** Called when a column is pinned or unpinned. */
+    onColumnPinned?: (columnId: string, pinned: 'left' | 'right' | null) => void;
+    /** Runtime pin overrides (from restored state or programmatic changes). */
+    pinnedColumns?: Record<string, 'left' | 'right'>;
+    /** Initial column width overrides (from restored state). */
+    initialColumnWidths?: Record<string, number>;
+    /** Number of rows to freeze (sticky), e.g. 1 = header row. */
+    freezeRows?: number;
+    /** Number of data columns to freeze (sticky left). */
+    freezeCols?: number;
+    layoutMode?: 'content' | 'fill';
+    /** When true, horizontal scrolling is suppressed (overflow-x hidden). */
+    suppressHorizontalScroll?: boolean;
+    isLoading?: boolean;
+    loadingMessage?: string;
+    editable?: boolean;
+    /** Enable spreadsheet-like cell selection. Default: true. */
+    cellSelection?: boolean;
+    onCellValueChanged?: (event: ICellValueChangedEvent<T>) => void;
+    onUndo?: () => void;
+    onRedo?: () => void;
+    canUndo?: boolean;
+    canRedo?: boolean;
+    rowSelection?: RowSelectionMode;
+    selectedRows?: Set<RowId>;
+    onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
+    statusBar?: IStatusBarProps;
+    /** Unified filter model (discriminated union values). */
+    filters: IFilters;
+    /** Single callback for all filter changes. Pass undefined to clear. */
+    onFilterChange: (key: string, value: FilterValue | undefined) => void;
+    filterOptions: Record<string, string[]>;
+    loadingFilterOptions: Record<string, boolean>;
+    peopleSearch?: (query: string) => Promise<UserLike[]>;
+    getUserByEmail?: (email: string) => Promise<UserLike | undefined>;
+    emptyState?: {
+        onClearAll: () => void;
+        hasActiveFilters: boolean;
+        message?: ReactNode;
+        render?: () => ReactNode;
+    };
+    /** Called when a cell renderer or custom editor throws an error. */
+    onCellError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { ColumnFilterType, IColumnFilterDef, IColumnMeta, IColumnDef, IColumnGroupDef, IColumnDefinition, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IValueParserParams, IDateFilterValue, HeaderCell, HeaderRow, } from './columnTypes';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, IOGridApi, IOGridProps, IOGridClientProps, IOGridServerProps, IOGridDataGridProps, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, } from './dataGridTypes';
+export { toUserLike, isInSelectionRange, normalizeSelectionRange } from './dataGridTypes';