@alaarab/ogrid-react 2.1.15 → 2.3.0

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

@@ -81,3 +81,5 @@ 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';

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/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

@@ -4,6 +4,7 @@ import type { DataGridLayoutState, DataGridRowSelectionState, DataGridEditingSta
 import type { UseColumnResizeResult } from './useColumnResize';
 import type { UseColumnReorderResult } from './useColumnReorder';
 import type { UseVirtualScrollResult } from './useVirtualScroll';
+import type { IVisibleColumnRange } from '@alaarab/ogrid-core';
 import type { HeaderFilterConfigInput, CellRenderDescriptorInput } from '../utils';
 import type { IStatusBarProps, RowId, HeaderRow } from '../types';
 import { CellDescriptorCache } from '@alaarab/ogrid-core';
@@ -32,6 +33,10 @@ export interface UseDataGridTableOrchestrationResult<T> {
     virtualScrollEnabled: boolean;
     virtualRowHeight: number;
     visibleRange: UseVirtualScrollResult['visibleRange'];
+    /** Visible column range for horizontal virtualization (null when disabled). */
+    columnRange: IVisibleColumnRange | null;
+    /** Callback for horizontal scroll events (column virtualization). */
+    onHorizontalScroll?: (scrollLeft: number) => void;
     items: T[];
     columns: IOGridDataGridProps<T>['columns'];
     getRowId: IOGridDataGridProps<T>['getRowId'];
@@ -56,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/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/useOGridDataFetching.d.ts

@@ -14,6 +14,8 @@ export interface UseOGridDataFetchingParams<T> {
     pageSize: number;
     onError?: (err: unknown) => void;
     onFirstDataRendered?: () => void;
+    /** Worker sort mode: true=always, 'auto'=when data > 5000 rows, false=sync. */
+    workerSort?: boolean | 'auto';
 }
 export interface UseOGridDataFetchingState<T> {
     displayItems: T[];

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

@@ -1,6 +1,6 @@
 import type { Virtualizer } from '@tanstack/react-virtual';
 import type { RefObject } from 'react';
-import type { IVisibleRange } from '@alaarab/ogrid-core';
+import type { IVisibleRange, IVisibleColumnRange } from '@alaarab/ogrid-core';
 export type { IVirtualScrollConfig } from '@alaarab/ogrid-core';
 export interface UseVirtualScrollParams {
     /** Total number of rows in the data set. */
@@ -18,6 +18,12 @@ export interface UseVirtualScrollParams {
     threshold?: number;
     /** Ref to the scrollable container element. */
     containerRef: RefObject<HTMLElement | null>;
+    /** Enable column virtualization (only render visible columns). */
+    columnVirtualization?: boolean;
+    /** Column widths for horizontal virtualization (unpinned columns only). */
+    columnWidths?: number[];
+    /** Column overscan count. Default: 2. */
+    columnOverscan?: number;
 }
 export interface UseVirtualScrollResult {
     /** The TanStack virtualizer instance (null when disabled). */
@@ -28,11 +34,15 @@ export interface UseVirtualScrollResult {
     visibleRange: IVisibleRange;
     /** Scroll to a specific row index. */
     scrollToIndex: (index: number) => void;
+    /** Visible column range for horizontal virtualization (null when column virtualization disabled). */
+    columnRange: IVisibleColumnRange | null;
+    /** Callback to attach to scroll container's onScroll for horizontal tracking. */
+    onHorizontalScroll?: (scrollLeft: number) => void;
 }
 /**
- * Wraps TanStack Virtual for row virtualization.
+ * Wraps TanStack Virtual for row virtualization, with optional column virtualization.
  * When disabled or when totalRows < threshold, returns a pass-through (all rows visible).
- * @param params - Total rows, row height, enabled flag, overscan, threshold, and container ref.
- * @returns Virtualizer instance, total height, visible range, and scrollToIndex helper.
+ * @param params - Total rows, row height, enabled flag, overscan, threshold, container ref, and column virtualization params.
+ * @returns Virtualizer instance, total height, visible range, scrollToIndex, columnRange, and onHorizontalScroll.
  */
 export declare function useVirtualScroll(params: UseVirtualScrollParams): UseVirtualScrollResult;

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 { 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, } 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, } 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';
@@ -32,7 +32,7 @@ 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, 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 type { FilterContentRenderers, MultiSelectRendererProps, TextRendererProps, PeopleRendererProps, DateRendererProps, } from './components/ColumnHeaderFilterRenderers';

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { IColumnDef, IColumnGroupDef, ICellValueChangedEvent } from './columnTypes';
+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, 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';
@@ -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;
@@ -80,12 +83,36 @@ interface IOGridBaseProps<T> {
     rowHeight?: number;
     /** Cell spacing/density preset. Controls cell padding throughout the grid. Default: 'normal'. */
     density?: 'compact' | 'normal' | 'comfortable';
+    /**
+     * Offload sorting to a Web Worker to avoid blocking the main thread.
+     * - `true`: always use worker sort
+     * - `'auto'`: use worker sort when data.length > 5000
+     * - `false` (default): use synchronous sort
+     * Columns with custom `compare` functions fall back to synchronous sort.
+     */
+    workerSort?: boolean | 'auto';
     /** 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;
+    /** 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>;
     'aria-label'?: string;
     'aria-labelledby'?: string;
 }
@@ -144,6 +171,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. */
@@ -177,4 +210,22 @@ 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;
 }

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;
 };

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

@@ -1,5 +1,5 @@
-export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, getCellValue, flattenColumns, buildHeaderRows, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, getStatusBarParts, getDataGridStatusBarConfig, getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut, parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, computeAggregations, processClientSideData, computeNextSortState, measureColumnContentWidth, AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX, findCtrlArrowTarget, computeTabNavigation, rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, applyFillValues, computeArrowNavigation, applyCellDeletion, applyRangeRowSelection, computeRowSelectionState, UndoRedoStack, buildCellIndex, } from '@alaarab/ogrid-core';
-export type { CsvColumn, StatusBarPart, StatusBarPartsInput, GridContextMenuItem, GridContextMenuHandlerProps, PaginationViewModel, ParseValueResult, AggregationResult, IColumnHeaderMenuItem, ColumnHeaderMenuInput, ColumnHeaderMenuHandlers, ArrowNavigationContext, ArrowNavigationResult, } from '@alaarab/ogrid-core';
+export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, getCellValue, flattenColumns, buildHeaderRows, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, getStatusBarParts, getDataGridStatusBarConfig, getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut, parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, computeAggregations, processClientSideData, partitionColumnsForVirtualization, computeNextSortState, measureColumnContentWidth, AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX, findCtrlArrowTarget, computeTabNavigation, rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, applyFillValues, computeArrowNavigation, applyCellDeletion, applyRangeRowSelection, computeRowSelectionState, UndoRedoStack, buildCellIndex, indexToColumnLetter, formatCellReference, getScrollTopForRow, } from '@alaarab/ogrid-core';
+export type { CsvColumn, StatusBarPart, StatusBarPartsInput, GridContextMenuItem, GridContextMenuHandlerProps, PaginationViewModel, ParseValueResult, AggregationResult, IColumnHeaderMenuItem, ColumnHeaderMenuInput, ColumnHeaderMenuHandlers, ArrowNavigationContext, ArrowNavigationResult, IFillFormulaOptions, } from '@alaarab/ogrid-core';
 export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, getCellInteractionProps, } from './dataGridViewModel';
 export { CellDescriptorCache } from '@alaarab/ogrid-core';
 export type { HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, CellInteractionHandlers, } from './dataGridViewModel';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-react",
-  "version": "2.1.15",
+  "version": "2.3.0",
   "description": "OGrid React – React hooks, headless components, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
@@ -39,7 +39,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@alaarab/ogrid-core": "2.1.15",
+    "@alaarab/ogrid-core": "2.3.0",
     "@tanstack/react-virtual": "^3.0.0"
   },
   "peerDependencies": {