@alaarab/ogrid-react 2.2.0 → 2.4.0

package/dist/types/components/ColumnChooserContent.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared inner content for ColumnChooser dropdowns across all React UI packages.
+ * Each UI package provides its own popover/dropdown wrapper and CheckboxItem slot.
+ * Optional Header, OptionsListContainer, OptionItemContainer, and Actions slots
+ * allow framework-specific wrappers (e.g. MUI Box/Typography) for Material.
+ */
+import * as React from 'react';
+import type { IColumnDefinition } from '../types/columnTypes';
+export interface IColumnChooserCheckboxItemProps {
+    columnId: string;
+    columnName: string;
+    checked: boolean;
+    disabled: boolean;
+    onChange: (checked: boolean) => void;
+}
+export interface IColumnChooserActionsProps {
+    onClearAll: () => void;
+    onSelectAll: () => void;
+}
+export interface IColumnChooserHeaderProps {
+    visibleCount: number;
+    totalCount: number;
+}
+export interface ColumnChooserContentClassNames {
+    header?: string;
+    optionsList?: string;
+    optionItem?: string;
+    actions?: string;
+    clearButton?: string;
+    selectAllButton?: string;
+}
+export interface ColumnChooserContentProps {
+    columns: IColumnDefinition[];
+    visibleColumns: Set<string>;
+    visibleCount: number;
+    totalCount: number;
+    handleSelectAll: () => void;
+    handleClearAll: () => void;
+    /** Curried handler: (columnId) => (checked: boolean) => void */
+    handleCheckboxChange: (columnId: string) => (checked: boolean) => void;
+    CheckboxItem: React.ComponentType<IColumnChooserCheckboxItemProps>;
+    classNames?: ColumnChooserContentClassNames;
+    Header?: React.ComponentType<IColumnChooserHeaderProps>;
+    OptionsListContainer?: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+    OptionItemContainer?: React.ComponentType<{
+        columnId: string;
+        children: React.ReactNode;
+    }>;
+    Actions?: React.ComponentType<IColumnChooserActionsProps>;
+}
+export declare const ColumnChooserContent: React.FC<ColumnChooserContentProps>;

package/dist/types/components/ColumnHeaderFilterRenderers.d.ts

@@ -6,10 +6,11 @@
  * to the correct renderer based on filterType, eliminating the duplicated if/switch chain
  * that was previously in each UI package's ColumnHeaderFilter component.
  */
-import type * as React from 'react';
+import * as React from 'react';
 import type { ColumnFilterType } from '../types/columnTypes';
 import type { UserLike } from '../types/dataGridTypes';
 import type { UseColumnHeaderFilterStateResult } from '../hooks/useColumnHeaderFilterState';
+import { type DateFilterClassNames } from './ColumnHeaderFilterContent';
 /**
  * Framework-specific renderers for each filter type.
  * Each UI package maps its own sub-filter components to these slots.
@@ -69,3 +70,16 @@ export interface DateRendererProps {
  * @returns The rendered filter content, or null for unsupported filter types
  */
 export declare function renderFilterContent(filterType: ColumnFilterType, state: UseColumnHeaderFilterStateResult, options: string[], isLoadingOptions: boolean, selectedUser: UserLike | undefined, renderers: FilterContentRenderers): React.ReactNode;
+/**
+ * Factory that creates the standard FilterContentRenderers for packages that use
+ * the default prop-passthrough pattern (Radix, Material). Fluent keeps its own
+ * memoized renderers because it adds extra event-propagation handlers.
+ *
+ * @param components - The framework-specific sub-filter popover components
+ * @param dateClassNames - Optional CSS class names for the date filter buttons (used by packages with CSS modules)
+ */
+export declare function createBaseFilterRenderers(components: {
+    MultiSelectFilterPopover: React.ComponentType<MultiSelectRendererProps>;
+    TextFilterPopover: React.ComponentType<TextRendererProps>;
+    PeopleFilterPopover: React.ComponentType<PeopleRendererProps>;
+}, dateClassNames?: DateFilterClassNames): FilterContentRenderers;

package/dist/types/components/FormulaBar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FormulaBar — Headless Excel-style formula bar component.
+ *
+ * Layout: [Name Box] [fx] [Formula Input]
+ *
+ * Uses --ogrid-* CSS variables for theming.
+ */
+import * as React from 'react';
+export interface FormulaBarProps {
+    /** Active cell reference (e.g. "A1"). */
+    cellRef: string | null;
+    /** Text displayed/edited in the formula input. */
+    formulaText: string;
+    /** Whether the input is in editing mode. */
+    isEditing: boolean;
+    /** Called when the user changes the input text. */
+    onInputChange: (text: string) => void;
+    /** Commit the formula bar value. */
+    onCommit: () => void;
+    /** Cancel editing. */
+    onCancel: () => void;
+    /** Start editing the formula bar. */
+    startEditing: () => void;
+}
+export declare function FormulaBar({ cellRef, formulaText, isEditing, onInputChange, onCommit, onCancel, startEditing, }: FormulaBarProps): React.ReactElement;

package/dist/types/components/FormulaRefOverlay.d.ts

@@ -0,0 +1,19 @@
+/**
+ * FormulaRefOverlay — Renders colored border overlays on cells referenced by
+ * the active formula, like Excel's reference highlighting.
+ *
+ * Uses the same container measurement pattern as MarchingAntsOverlay.
+ */
+import * as React from 'react';
+import { type FormulaReference } from '@alaarab/ogrid-core';
+export interface FormulaRefOverlayProps {
+    /** Ref to the positioned container that wraps the table. */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** References to highlight. */
+    references: FormulaReference[];
+    /** Column offset (1 when checkbox/row-number columns are present). */
+    colOffset: number;
+}
+declare function FormulaRefOverlayInner({ containerRef, references, colOffset, }: FormulaRefOverlayProps): React.ReactElement | null;
+export declare const FormulaRefOverlay: React.MemoExoticComponent<typeof FormulaRefOverlayInner>;
+export {};

package/dist/types/components/OGridLayout.d.ts

@@ -25,6 +25,10 @@ export interface OGridLayoutProps {
     sideBar?: SideBarProps | null;
     /** When true, render a fullscreen toggle button in the toolbar. */
     fullScreen?: boolean;
+    /** Formula bar element (rendered between toolbar and grid). */
+    formulaBar?: React.ReactNode;
+    /** Sheet tabs element (rendered between grid and footer). */
+    sheetTabs?: React.ReactNode;
 }
 /**
  * Renders OGrid layout as a unified bordered container:

package/dist/types/components/PaginationControlsBase.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared base component for PaginationControls across all React UI packages.
+ * Handles hook call, null guard, vm destructure, and renders the full layout structure.
+ * Each UI package provides slots for framework-specific interactive elements.
+ */
+import * as React from 'react';
+import type { IPaginationControlsProps } from './PaginationControlsProps';
+export interface INavButtonSlotProps {
+    variant: 'first' | 'prev' | 'next' | 'last';
+    onClick: () => void;
+    disabled: boolean;
+    'aria-label': string;
+    className?: string;
+}
+export interface IPageButtonSlotProps {
+    onClick: () => void;
+    active: boolean;
+    'aria-label': string;
+    'aria-current'?: 'page';
+    children: React.ReactNode;
+    className?: string;
+}
+export interface IPageSizeSelectSlotProps {
+    value: number;
+    options: readonly number[];
+    onChange: (value: number) => void;
+    'aria-label': string;
+    className?: string;
+}
+export interface IOuterContainerSlotProps {
+    children: React.ReactNode;
+    className?: string;
+    role: string;
+    'aria-label': string;
+}
+export interface IPaginationControlsSlots {
+    NavButton: React.ComponentType<INavButtonSlotProps>;
+    PageButton: React.ComponentType<IPageButtonSlotProps>;
+    PageSizeSelect: React.ComponentType<IPageSizeSelectSlotProps>;
+    OuterContainer?: React.ComponentType<IOuterContainerSlotProps>;
+    InfoText?: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+    NavButtonsContainer?: React.ComponentType<{
+        children: React.ReactNode;
+        className?: string;
+    }>;
+    PageSizeContainer?: React.ComponentType<{
+        children: React.ReactNode;
+        className?: string;
+    }>;
+    PageSizeLabel?: React.ComponentType<Record<string, never>>;
+    Ellipsis?: React.ComponentType<Record<string, never>>;
+}
+export interface PaginationControlsBaseClassNames {
+    pagination?: string;
+    paginationInfo?: string;
+    paginationControls?: string;
+    pageNumbers?: string;
+    ellipsis?: string;
+    navBtn?: string;
+    pageBtn?: string;
+    pageSizeSelector?: string;
+    pageSizeLabel?: string;
+    pageSizeSelect?: string;
+}
+export interface PaginationControlsBaseProps extends IPaginationControlsProps {
+    slots: IPaginationControlsSlots;
+    classNames?: PaginationControlsBaseClassNames;
+}
+export declare const PaginationControlsBase: React.FC<PaginationControlsBaseProps>;

package/dist/types/components/SheetTabs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SheetTabs — Excel-style sheet tab bar at the bottom of the grid.
+ *
+ * Layout: [+] [Sheet1] [Sheet2] [Sheet3]
+ */
+import * as React from 'react';
+import type { ISheetDef } from '@alaarab/ogrid-core';
+export interface SheetTabsProps {
+    sheets: ISheetDef[];
+    activeSheet: string;
+    onSheetChange: (sheetId: string) => void;
+    onSheetAdd?: () => void;
+}
+export declare function SheetTabs({ sheets, activeSheet, onSheetChange, onSheetAdd, }: SheetTabsProps): React.ReactElement;

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

@@ -57,7 +57,7 @@ export { useColumnResize } from './useColumnResize';
 export type { UseColumnResizeParams, UseColumnResizeResult, } from './useColumnResize';
 export { useColumnPinning } from './useColumnPinning';
 export type { UseColumnPinningParams, UseColumnPinningResult, } from './useColumnPinning';
-export { useColumnHeaderMenuState } from './useColumnHeaderMenuState';
+export { useColumnHeaderMenuState, getColumnHeaderMenuProps } from './useColumnHeaderMenuState';
 export type { UseColumnHeaderMenuStateParams, UseColumnHeaderMenuStateResult, } from './useColumnHeaderMenuState';
 export { useRichSelectState } from './useRichSelectState';
 export type { UseRichSelectStateParams, UseRichSelectStateResult } from './useRichSelectState';
@@ -81,3 +81,7 @@ export { useDataGridTableOrchestration } from './useDataGridTableOrchestration';
 export type { UseDataGridTableOrchestrationParams, UseDataGridTableOrchestrationResult, } from './useDataGridTableOrchestration';
 export { useColumnMeta } from './useColumnMeta';
 export type { UseColumnMetaParams, ColumnMetaResult } from './useColumnMeta';
+export { useFormulaEngine } from './useFormulaEngine';
+export type { UseFormulaEngineParams, UseFormulaEngineResult } from './useFormulaEngine';
+export { useFormulaBar } from './useFormulaBar';
+export type { UseFormulaBarParams, UseFormulaBarResult } from './useFormulaBar';

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

@@ -9,6 +9,16 @@ export interface UseClipboardParams<T> {
     onCellValueChanged: ((event: ICellValueChangedEvent<T>) => void) | undefined;
     beginBatch?: () => void;
     endBatch?: () => void;
+    /** When true, enables formula-aware copy/paste. */
+    formulas?: boolean;
+    /** Flat (unfiltered) column list used to map visible col to flat col index. */
+    flatColumns?: IColumnDef<T>[];
+    /** Returns the formula string for a flat column + row, or undefined if none. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Returns true if a flat column + row has a formula. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Sets or clears a formula for a flat column + row. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
 }
 export interface UseClipboardResult {
     handleCopy: () => void;

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

@@ -41,3 +41,26 @@ export interface UseColumnHeaderMenuStateResult {
  * Tracks which column's menu is open, anchor element, and action handlers.
  */
 export declare function useColumnHeaderMenuState(params: UseColumnHeaderMenuStateParams): UseColumnHeaderMenuStateResult;
+/**
+ * Maps a UseColumnHeaderMenuStateResult to the flat ColumnHeaderMenuProps shape.
+ * Eliminates the 18-prop spread that each DataGridTable package repeats.
+ */
+export declare function getColumnHeaderMenuProps(headerMenu: UseColumnHeaderMenuStateResult): {
+    isOpen: boolean;
+    anchorElement: HTMLElement | null;
+    onClose: () => void;
+    onPinLeft: () => void;
+    onPinRight: () => void;
+    onUnpin: () => void;
+    onSortAsc: () => void;
+    onSortDesc: () => void;
+    onClearSort: () => void;
+    onAutosizeThis: () => void;
+    onAutosizeAll: () => void;
+    canPinLeft: boolean;
+    canPinRight: boolean;
+    canUnpin: boolean;
+    currentSort: "asc" | "desc" | null;
+    isSortable: boolean;
+    isResizable: boolean;
+};

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

@@ -31,6 +31,14 @@ export interface UseDataGridEditingParams<T> {
         endCol: number;
     } | null) => void;
     colOffset: number;
+    /** Formula integration: set a formula for a cell coordinate. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+    /** Formula integration: notify a non-formula cell changed. */
+    onFormulaCellChanged?: (col: number, row: number) => void;
+    /** Whether formula support is enabled. */
+    formulas?: boolean;
+    /** All flat columns (for mapping columnId → column index). */
+    flatColumns?: IColumnDef<T>[];
 }
 export interface UseDataGridEditingResult<T> {
     editing: DataGridEditingState<T>;

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

@@ -47,6 +47,16 @@ export interface UseDataGridInteractionParams<T> {
     wrapperRef: RefObject<HTMLDivElement | null>;
     /** Custom keydown handler — called before grid default. preventDefault() suppresses grid handling. */
     onKeyDown?: (event: React.KeyboardEvent) => void;
+    /** When true, enables formula-aware clipboard and fill handle. */
+    formulas?: boolean;
+    /** Flat column list for formula coordinate mapping. */
+    flatColumns?: IColumnDef<T>[];
+    /** Returns the formula string for a flat column + row. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Returns true if a flat column + row has a formula. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Sets or clears a formula for a flat column + row. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
 }
 export interface UseDataGridInteractionResult<T> {
     interaction: DataGridCellInteractionState;

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

@@ -61,6 +61,8 @@ export interface UseDataGridTableOrchestrationResult<T> {
     headerRows: HeaderRow<T>[];
     allowOverflowX: boolean;
     fitToContent: boolean;
+    showColumnLetters: boolean;
+    showNameBox: boolean;
     editCallbacks: {
         commitCellEdit: DataGridEditingState<T>['commitCellEdit'];
         setEditingCell: DataGridEditingState<T>['setEditingCell'];

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

@@ -1,6 +1,7 @@
 import type { RefObject } from 'react';
 import type { ISelectionRange, IActiveCell } from '../types';
 import type { IColumnDef, ICellValueChangedEvent } from '../types/columnTypes';
+import type { IFillFormulaOptions } from '../utils';
 export interface UseFillHandleParams<T> {
     items: T[];
     visibleCols: IColumnDef<T>[];
@@ -13,6 +14,8 @@ export interface UseFillHandleParams<T> {
     wrapperRef: RefObject<HTMLDivElement | null>;
     beginBatch?: () => void;
     endBatch?: () => void;
+    /** Optional formula-aware fill options. When provided, cells with formulas adjust references during fill. */
+    formulaOptions?: IFillFormulaOptions<T>;
 }
 export interface UseFillHandleResult {
     fillDrag: {

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

@@ -0,0 +1,43 @@
+/**
+ * useFormulaBar — React hook for formula bar state.
+ *
+ * Manages the formula bar text, editing mode, and reference extraction.
+ */
+import { type FormulaReference } from '@alaarab/ogrid-core';
+export interface UseFormulaBarParams {
+    /** Active cell column index (0-based). */
+    activeCol: number | null;
+    /** Active cell row index (0-based). */
+    activeRow: number | null;
+    /** Active cell reference string (e.g. "A1"). */
+    activeCellRef: string | null;
+    /** Get formula string for a cell. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Get raw display value for a cell. */
+    getRawValue?: (col: number, row: number) => unknown;
+    /** Set formula for a cell. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+    /** Commit a non-formula value change. */
+    onCellValueChanged?: (col: number, row: number, value: unknown) => void;
+}
+export interface UseFormulaBarResult {
+    /** Cell reference string (e.g. "A1"). */
+    cellRef: string | null;
+    /** Text shown in the formula bar input. */
+    formulaText: string;
+    /** Whether the formula bar input is being edited. */
+    isEditing: boolean;
+    /** Update the formula bar input text. */
+    onInputChange: (text: string) => void;
+    /** Commit the current edit. */
+    onCommit: () => void;
+    /** Cancel the current edit. */
+    onCancel: () => void;
+    /** Start editing the formula bar. */
+    startEditing: () => void;
+    /** References extracted from the current formula text (for highlighting). */
+    referencedCells: FormulaReference[];
+    /** Whether the formula bar is actively being edited (for click-to-insert-ref guards). */
+    isFormulaBarEditing: React.MutableRefObject<boolean>;
+}
+export declare function useFormulaBar(params: UseFormulaBarParams): UseFormulaBarResult;

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

@@ -0,0 +1,52 @@
+/**
+ * useFormulaEngine — React hook for integrating the formula engine with the grid.
+ *
+ * Lazily creates a FormulaEngine instance when `formulas` prop is true.
+ * Provides accessor bridge between grid data and formula coordinates.
+ * Tree-shakeable: if `formulas` is false, no formula code is loaded.
+ */
+import { type IGridDataAccessor, type IFormulaFunction, type IRecalcResult, type IAuditEntry, type IAuditTrail } from '@alaarab/ogrid-core';
+import type { IColumnDef } from '@alaarab/ogrid-core';
+export interface UseFormulaEngineParams<T> {
+    /** Enable formula support. */
+    formulas?: boolean;
+    /** Grid data items. */
+    items: T[];
+    /** Flat leaf columns (for mapping column index ↔ columnId). */
+    flatColumns: IColumnDef<T>[];
+    /** Initial formulas to load. */
+    initialFormulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /** Called when recalculation produces cascading updates. */
+    onFormulaRecalc?: (result: IRecalcResult) => void;
+    /** Custom formula functions. */
+    formulaFunctions?: Record<string, IFormulaFunction>;
+    /** Named ranges: name → cell/range reference string. */
+    namedRanges?: Record<string, string>;
+    /** Sheet accessors for cross-sheet references. */
+    sheets?: Record<string, IGridDataAccessor>;
+}
+export interface UseFormulaEngineResult {
+    /** Get the formula engine's computed value for a cell coordinate. */
+    getFormulaValue: (col: number, row: number) => unknown;
+    /** Check if a cell has a formula. */
+    hasFormula: (col: number, row: number) => boolean;
+    /** Get the formula string for a cell. */
+    getFormula: (col: number, row: number) => string | undefined;
+    /** Set or clear a formula for a cell. Triggers recalculation. */
+    setFormula: (col: number, row: number, formula: string | null) => void;
+    /** Notify the engine that a non-formula cell value changed. Triggers dependent recalc. */
+    onCellChanged: (col: number, row: number) => void;
+    /** Get all cells that a cell depends on (deep, transitive). */
+    getPrecedents: (col: number, row: number) => IAuditEntry[];
+    /** Get all cells that depend on a cell (deep, transitive). */
+    getDependents: (col: number, row: number) => IAuditEntry[];
+    /** Get full audit trail for a cell. */
+    getAuditTrail: (col: number, row: number) => IAuditTrail | null;
+    /** Whether formula support is active. */
+    enabled: boolean;
+}
+export declare function useFormulaEngine<T>(params: UseFormulaEngineParams<T>): UseFormulaEngineResult;

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

@@ -32,6 +32,10 @@ export interface UseOGridLayout {
     };
     sideBarProps: SideBarProps | null;
     fullScreen?: boolean;
+    /** Formula bar element (rendered between toolbar and grid when formulas are enabled). */
+    formulaBar?: React.ReactNode;
+    /** Sheet tabs element (rendered between grid and footer when sheetDefs are provided). */
+    sheetTabs?: React.ReactNode;
 }
 /** Filter state. */
 export interface UseOGridFilters {

package/dist/types/index.d.ts

@@ -1,8 +1,8 @@
 export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_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, IVirtualScrollConfig, IColumnReorderConfig, } from './types';
+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, IVirtualScrollConfig, IColumnReorderConfig, ISheetDef, } 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, useSelectState, useSideBarState, useTableLayout, useColumnReorder, useVirtualScroll, useListVirtualizer, useLatestRef, usePaginationControls, useDataGridTableOrchestration, useColumnMeta, } 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, DataGridPinningState, UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, UseTextFilterStateParams, UseTextFilterStateResult, UseMultiSelectFilterStateParams, UseMultiSelectFilterStateResult, UsePeopleFilterStateParams, UsePeopleFilterStateResult, UseDateFilterStateParams, UseDateFilterStateResult, UseColumnChooserStateParams, UseColumnChooserStateResult, UseInlineCellEditorStateParams, UseInlineCellEditorStateResult, InlineCellEditorType, UseColumnResizeParams, UseColumnResizeResult, UseRichSelectStateParams, UseRichSelectStateResult, UseSelectStateParams, UseSelectStateResult, UseSideBarStateParams, UseSideBarStateResult, UseTableLayoutParams, UseTableLayoutResult, UseColumnReorderParams, UseColumnReorderResult, UseVirtualScrollParams, UseVirtualScrollResult, UsePaginationControlsProps, UsePaginationControlsResult, UseDataGridTableOrchestrationParams, UseDataGridTableOrchestrationResult, UseColumnMetaParams, ColumnMetaResult, } from './hooks';
+export { useFilterOptions, useOGrid, useActiveCell, useCellEditing, useContextMenu, useCellSelection, useClipboard, useRowSelection, useKeyboardNavigation, useUndoRedo, useDebounce, useFillHandle, useDataGridState, useColumnHeaderFilterState, useTextFilterState, useMultiSelectFilterState, usePeopleFilterState, useDateFilterState, useColumnChooserState, useInlineCellEditorState, useColumnResize, useRichSelectState, useSelectState, useSideBarState, useTableLayout, useColumnReorder, useVirtualScroll, useListVirtualizer, useLatestRef, usePaginationControls, useDataGridTableOrchestration, useColumnMeta, useFormulaEngine, useFormulaBar, getColumnHeaderMenuProps, } 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, DataGridPinningState, UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, UseTextFilterStateParams, UseTextFilterStateResult, UseMultiSelectFilterStateParams, UseMultiSelectFilterStateResult, UsePeopleFilterStateParams, UsePeopleFilterStateResult, UseDateFilterStateParams, UseDateFilterStateResult, UseColumnChooserStateParams, UseColumnChooserStateResult, UseInlineCellEditorStateParams, UseInlineCellEditorStateResult, InlineCellEditorType, UseColumnResizeParams, UseColumnResizeResult, UseRichSelectStateParams, UseRichSelectStateResult, UseSelectStateParams, UseSelectStateResult, UseSideBarStateParams, UseSideBarStateResult, UseTableLayoutParams, UseTableLayoutResult, UseColumnReorderParams, UseColumnReorderResult, UseVirtualScrollParams, UseVirtualScrollResult, UsePaginationControlsProps, UsePaginationControlsResult, UseDataGridTableOrchestrationParams, UseDataGridTableOrchestrationResult, UseColumnMetaParams, ColumnMetaResult, UseFormulaEngineParams, UseFormulaEngineResult, UseFormulaBarParams, UseFormulaBarResult, } from './hooks';
 export { GRID_ROOT_STYLE, CURSOR_CELL_STYLE, POPOVER_ANCHOR_STYLE, PREVENT_DEFAULT, NOOP, STOP_PROPAGATION, } from './constants/domHelpers';
 export { OGridLayout } from './components/OGridLayout';
 export type { OGridLayoutProps } from './components/OGridLayout';
@@ -14,10 +14,20 @@ export { GridContextMenu } from './components/GridContextMenu';
 export type { GridContextMenuProps, GridContextMenuClassNames } from './components/GridContextMenu';
 export { MarchingAntsOverlay } from './components/MarchingAntsOverlay';
 export type { MarchingAntsOverlayProps } from './components/MarchingAntsOverlay';
+export { FormulaBar } from './components/FormulaBar';
+export type { FormulaBarProps } from './components/FormulaBar';
+export { FormulaRefOverlay } from './components/FormulaRefOverlay';
+export type { FormulaRefOverlayProps } from './components/FormulaRefOverlay';
+export { SheetTabs } from './components/SheetTabs';
+export type { SheetTabsProps } from './components/SheetTabs';
 export { SideBar } from './components/SideBar';
 export type { SideBarProps, SideBarFilterColumn } from './components/SideBar';
 export { BaseColumnHeaderMenu } from './components/BaseColumnHeaderMenu';
 export type { BaseColumnHeaderMenuProps, ColumnHeaderMenuClassNames } from './components/BaseColumnHeaderMenu';
+export { PaginationControlsBase } from './components/PaginationControlsBase';
+export type { PaginationControlsBaseProps, PaginationControlsBaseClassNames, IPaginationControlsSlots, INavButtonSlotProps, IPageButtonSlotProps, IPageSizeSelectSlotProps, IOuterContainerSlotProps, } from './components/PaginationControlsBase';
+export { ColumnChooserContent } from './components/ColumnChooserContent';
+export type { ColumnChooserContentProps, ColumnChooserContentClassNames, IColumnChooserCheckboxItemProps, IColumnChooserActionsProps, IColumnChooserHeaderProps, } from './components/ColumnChooserContent';
 export { createOGrid } from './components/createOGrid';
 export type { CreateOGridComponents, GridRowProps, InlineCellEditorProps } from './components/createOGrid';
 export { CellErrorBoundary } from './components/CellErrorBoundary';
@@ -32,9 +42,9 @@ export { BaseDropIndicator } from './components/BaseDropIndicator';
 export type { BaseDropIndicatorProps } from './components/BaseDropIndicator';
 export { DateFilterContent, getColumnHeaderFilterStateParams, getDateFilterContentProps, } from './components/ColumnHeaderFilterContent';
 export type { IColumnHeaderFilterProps, DateFilterContentProps, DateFilterClassNames, } from './components/ColumnHeaderFilterContent';
-export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, getCellValue, flattenColumns, buildHeaderRows, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, getStatusBarParts, getDataGridStatusBarConfig, GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut, getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, getHeaderFilterConfig, getCellRenderDescriptor, CellDescriptorCache, isRowInRange, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, getCellInteractionProps, parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, computeAggregations, processClientSideData, partitionColumnsForVirtualization, areGridRowPropsEqual, findCtrlArrowTarget, computeTabNavigation, rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, UndoRedoStack, } from './utils';
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, getCellValue, flattenColumns, buildHeaderRows, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, getStatusBarParts, getDataGridStatusBarConfig, GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut, getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, getHeaderFilterConfig, getCellRenderDescriptor, CellDescriptorCache, isRowInRange, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, getCellInteractionProps, parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, computeAggregations, processClientSideData, partitionColumnsForVirtualization, areGridRowPropsEqual, findCtrlArrowTarget, computeTabNavigation, rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, UndoRedoStack, indexToColumnLetter, formatCellReference, } from './utils';
 export type { CsvColumn, StatusBarPart, StatusBarPartsInput, GridContextMenuItem, GridContextMenuHandlerProps, PaginationViewModel, HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, CellInteractionHandlers, ParseValueResult, AggregationResult, GridRowComparatorProps, IColumnHeaderMenuItem, ColumnHeaderMenuInput, ColumnHeaderMenuHandlers, } from './utils';
-export { renderFilterContent } from './components/ColumnHeaderFilterRenderers';
+export { renderFilterContent, createBaseFilterRenderers } from './components/ColumnHeaderFilterRenderers';
 export type { FilterContentRenderers, MultiSelectRendererProps, TextRendererProps, PeopleRendererProps, DateRendererProps, } from './components/ColumnHeaderFilterRenderers';
 export type { IColumnChooserProps } from './components/ColumnChooserProps';
 export type { IPaginationControlsProps } from './components/PaginationControlsProps';

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

@@ -1,8 +1,9 @@
 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, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from '@alaarab/ogrid-core';
+import type { IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail } from '@alaarab/ogrid-core';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, ISheetDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from '@alaarab/ogrid-core';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange } from '@alaarab/ogrid-core';
-import type { RowId, UserLike, IFilters, FilterValue, RowSelectionMode, IRowSelectionChangeEvent, IStatusBarProps, IDataSource, ISideBarDef, IVirtualScrollConfig } from '@alaarab/ogrid-core';
+import type { RowId, UserLike, IFilters, FilterValue, RowSelectionMode, IRowSelectionChangeEvent, IStatusBarProps, IDataSource, ISideBarDef, ISheetDef, IVirtualScrollConfig } from '@alaarab/ogrid-core';
 /** Base props shared by both client-side and server-side OGrid modes. */
 interface IOGridBaseProps<T> {
     columns: (IColumnDef<T> | IColumnGroupDef<T>)[];
@@ -43,6 +44,8 @@ interface IOGridBaseProps<T> {
     onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
     /** Show Excel-style row numbers column at the start of the grid (1, 2, 3...). Default: false. */
     showRowNumbers?: boolean;
+    /** Enable Excel-style cell references: column letter headers (A, B, C...), row number gutter, and a name box showing the active cell (e.g. "A1"). Implies showRowNumbers. */
+    cellReferences?: boolean;
     statusBar?: boolean | IStatusBarProps;
     defaultPageSize?: number;
     defaultSortBy?: string;
@@ -94,6 +97,30 @@ interface IOGridBaseProps<T> {
     onError?: (error: unknown) => void;
     /** Called when a cell renderer or custom editor throws an error. */
     onCellError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    /** Enable Excel-like formula support. When true, cells starting with '=' are treated as formulas. Default: false. */
+    formulas?: boolean;
+    /** Initial formulas to load when the formula engine initializes. */
+    initialFormulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /** Called when formula recalculation produces updated cell values (e.g. cascade from an edited cell). */
+    onFormulaRecalc?: (result: IRecalcResult) => void;
+    /** Custom formula functions to register with the formula engine (e.g. { MYFUNC: { minArgs: 1, maxArgs: 1, evaluate: ... } }). */
+    formulaFunctions?: Record<string, IFormulaFunction>;
+    /** Named ranges for the formula engine: name → cell/range ref string (e.g. { Revenue: 'A1:A10' }). */
+    namedRanges?: Record<string, string>;
+    /** Sheet accessors for cross-sheet formula references (e.g. { Sheet2: accessor }). */
+    sheets?: Record<string, IGridDataAccessor>;
+    /** Sheet definitions for bottom tab bar. When set, renders Excel-style sheet tabs. */
+    sheetDefs?: ISheetDef[];
+    /** Currently active sheet id. */
+    activeSheet?: string;
+    /** Called when the user switches sheets. */
+    onSheetChange?: (sheetId: string) => void;
+    /** Called when the user clicks the add-sheet button. */
+    onSheetAdd?: () => void;
     'aria-label'?: string;
     'aria-labelledby'?: string;
 }
@@ -152,6 +179,12 @@ export interface IOGridDataGridProps<T> {
     onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
     /** Show Excel-style row numbers column. */
     showRowNumbers?: boolean;
+    /** Show Excel-style column letter headers (A, B, C...) above the header row. */
+    showColumnLetters?: boolean;
+    /** Show a name box displaying the active cell reference (e.g. "A1"). */
+    showNameBox?: boolean;
+    /** Callback when the active cell changes. Used by the name box to display the current cell reference. */
+    onActiveCellChange?: (ref: string | null) => void;
     /** Current page number (1-based) for row number calculation. */
     currentPage?: number;
     /** Page size for row number calculation. */
@@ -185,4 +218,26 @@ export interface IOGridDataGridProps<T> {
     'aria-labelledby'?: string;
     /** Custom keydown handler. Called before grid's built-in handling. Call event.preventDefault() to suppress grid default. */
     onKeyDown?: (event: React.KeyboardEvent) => void;
+    /** Enable formula support. When true, cell values starting with '=' are treated as formulas. */
+    formulas?: boolean;
+    /** Get the formula engine's computed value for a cell, or undefined if no formula. */
+    getFormulaValue?: (col: number, row: number) => unknown;
+    /** Check if a cell has a formula. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Get the formula string for a cell. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Set a formula for a cell (called from edit commit when value starts with '='). */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+    /** Notify the formula engine that a non-formula cell changed. */
+    onFormulaCellChanged?: (col: number, row: number) => void;
+    /** Get all cells that a cell depends on (deep, transitive). */
+    getPrecedents?: (col: number, row: number) => IAuditEntry[];
+    /** Get all cells that depend on a cell (deep, transitive). */
+    getDependents?: (col: number, row: number) => IAuditEntry[];
+    /** Get full audit trail for a cell. */
+    getAuditTrail?: (col: number, row: number) => IAuditTrail | null;
+    /** Monotonic counter incremented on each formula recalculation — used for cache invalidation. */
+    formulaVersion?: number;
+    /** Cell references to highlight (from active formula in formula bar). */
+    formulaReferences?: import('@alaarab/ogrid-core').FormulaReference[];
 }

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

@@ -1,3 +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, IVirtualScrollConfig, IColumnReorderConfig, } from './dataGridTypes';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, IOGridApi, IOGridProps, IOGridClientProps, IOGridServerProps, IOGridDataGridProps, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IColumnReorderConfig, ISheetDef, } from './dataGridTypes';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange } from './dataGridTypes';

package/dist/types/utils/dataGridViewModel.d.ts

@@ -19,7 +19,7 @@ export declare function resolveCellDisplayContent<T>(col: IColumnDef<T>, item: T
  * Resolves the cellStyle from a column def.
  * Returns React.CSSProperties for JSX compatibility.
  */
-export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T): React.CSSProperties | undefined;
+export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T, displayValue?: unknown): React.CSSProperties | undefined;
 /**
  * Builds props for InlineCellEditor with React-specific IColumnDef.
  */
@@ -63,6 +63,7 @@ export declare function getCellInteractionProps(descriptor: CellRenderDescriptor
     onClick: () => void;
     onContextMenu: (e: React.MouseEvent) => void;
     'data-in-range'?: "true" | undefined;
+    'data-active-cell'?: "true" | undefined;
     'data-row-index': number;
     'data-col-index': number;
 };