@alaarab/ogrid-angular 2.2.0 → 2.4.0

package/dist/types/components/base-column-header-menu.component.d.ts

@@ -0,0 +1,30 @@
+import { type IColumnHeaderMenuItem, type ColumnHeaderMenuHandlers } from '@alaarab/ogrid-core';
+/**
+ * Abstract base class containing all shared TypeScript logic for ColumnHeaderMenu components.
+ * Framework-specific UI packages extend this with their templates and style overrides.
+ *
+ * Uses signal-backed @Input setters so that computed() tracks input changes reactively
+ * (plain @Input properties are not reactive in Angular signals).
+ *
+ * Subclasses must:
+ * 1. Provide a @Component decorator with template and styles
+ * 2. Implement their own menu open/close mechanism (mat-menu, p-menu, or native dropdown)
+ */
+export declare abstract class BaseColumnHeaderMenuComponent {
+    columnId: string;
+    private readonly _canPinLeft;
+    private readonly _canPinRight;
+    private readonly _canUnpin;
+    private readonly _currentSort;
+    private readonly _isSortable;
+    private readonly _isResizable;
+    set canPinLeft(v: boolean);
+    set canPinRight(v: boolean);
+    set canUnpin(v: boolean);
+    set currentSort(v: 'asc' | 'desc' | null);
+    set isSortable(v: boolean);
+    set isResizable(v: boolean);
+    handlers: Partial<ColumnHeaderMenuHandlers>;
+    readonly menuItems: import("@angular/core").Signal<IColumnHeaderMenuItem[]>;
+    handleMenuItemClick(itemId: string): void;
+}

package/dist/types/components/base-datagrid-table.component.d.ts

@@ -126,6 +126,9 @@ export declare abstract class BaseDataGridTableComponent<T = unknown> {
         editable?: boolean;
         onCellValueChanged?: ((event: import("@alaarab/ogrid-core").ICellValueChangedEvent<T>) => void) | undefined;
         isDragging: boolean;
+        getFormulaValue?: (col: number, row: number) => unknown;
+        hasFormula?: (col: number, row: number) => boolean;
+        formulaVersion?: number;
     }>;
     readonly pinnedColumnsMap: import("@angular/core").Signal<Record<string, "left" | "right">>;
     readonly vsEnabled: import("@angular/core").Signal<boolean>;
@@ -245,7 +248,7 @@ export declare abstract class BaseDataGridTableComponent<T = unknown> {
     };
     getCellDescriptor(item: T, col: IColumnDef<T>, rowIndex: number, colIdx: number): CellRenderDescriptor;
     resolveCellContent(col: IColumnDef<T>, item: T, displayValue: unknown): unknown;
-    resolveCellStyleFn(col: IColumnDef<T>, item: T): Record<string, string> | undefined;
+    resolveCellStyleFn(col: IColumnDef<T>, item: T, displayValue?: unknown): Record<string, string> | undefined;
     buildPopoverEditorProps(item: T, col: IColumnDef<T>, descriptor: CellRenderDescriptor): unknown;
     /** Check if a specific cell is the active cell (PrimeNG inline template helper). */
     isActiveCell(rowIndex: number, colIdx: number): boolean;

package/dist/types/components/formula-bar.component.d.ts

@@ -0,0 +1,29 @@
+/**
+ * FormulaBarComponent -- Standalone Angular formula bar component.
+ *
+ * Layout: [Name Box] [fx] [Formula Input]
+ *
+ * Uses --ogrid-* CSS variables for theming.
+ * Port of React's FormulaBar component.
+ */
+export declare class FormulaBarComponent {
+    /** Active cell reference (e.g. "A1"). */
+    readonly cellRef: import("@angular/core").InputSignal<string | null>;
+    /** Text displayed/edited in the formula input. */
+    readonly formulaText: import("@angular/core").InputSignal<string>;
+    /** Whether the input is in editing mode. */
+    readonly isEditing: import("@angular/core").InputSignal<boolean>;
+    /** Called when the user changes the input text. */
+    readonly inputChange: import("@angular/core").OutputEmitterRef<string>;
+    /** Commit the formula bar value. */
+    readonly commit: import("@angular/core").OutputEmitterRef<void>;
+    /** Cancel editing. */
+    readonly cancel: import("@angular/core").OutputEmitterRef<void>;
+    /** Start editing the formula bar. */
+    readonly startEditing: import("@angular/core").OutputEmitterRef<void>;
+    private readonly inputEl;
+    constructor();
+    onInput(event: Event): void;
+    onKeyDown(event: KeyboardEvent): void;
+    onClick(): void;
+}

package/dist/types/components/formula-ref-overlay.component.d.ts

@@ -0,0 +1,27 @@
+/**
+ * FormulaRefOverlayComponent -- Renders colored border overlays on cells
+ * referenced by the active formula, like Excel's reference highlighting.
+ *
+ * Port of React's FormulaRefOverlay component.
+ */
+import { type FormulaReference } from '@alaarab/ogrid-core';
+interface RefRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+    color: string;
+}
+export declare class FormulaRefOverlayComponent {
+    /** The positioned container that wraps the table. */
+    readonly containerEl: import("@angular/core").InputSignal<HTMLElement | null>;
+    /** References to highlight. */
+    readonly references: import("@angular/core").InputSignal<FormulaReference[]>;
+    /** Column offset (1 when checkbox/row-number columns are present). */
+    readonly colOffset: import("@angular/core").InputSignal<number>;
+    readonly rects: import("@angular/core").WritableSignal<RefRect[]>;
+    private rafId;
+    constructor();
+    max0(v: number): number;
+}
+export {};

package/dist/types/components/inline-cell-editor-template.d.ts

@@ -2,5 +2,5 @@
  * Shared inline cell editor template used by all Angular UI packages.
  * The template is identical across Material, PrimeNG, and Radix implementations.
  */
-export declare const INLINE_CELL_EDITOR_TEMPLATE = "\n    @switch (editorType) {\n      @case ('text') {\n        <input\n          #inputEl\n          type=\"text\"\n          [value]=\"localValue()\"\n          (input)=\"localValue.set($any($event.target).value)\"\n          (keydown)=\"onTextKeyDown($event)\"\n          (blur)=\"onTextBlur()\"\n          [style]=\"getInputStyle()\"\n        />\n      }\n      @case ('richSelect') {\n        <div #richSelectWrapper\n             style=\"width:100%;height:100%;display:flex;align-items:center;padding:6px 10px;box-sizing:border-box;min-width:0;position:relative\">\n          <input\n            #richSelectInput\n            type=\"text\"\n            [value]=\"searchText()\"\n            (input)=\"onRichSelectSearch($any($event.target).value)\"\n            (keydown)=\"onRichSelectKeyDown($event)\"\n            placeholder=\"Search...\"\n            style=\"width:100%;padding:0;border:none;background:transparent;color:inherit;font:inherit;font-size:13px;outline:none;min-width:0\"\n          />\n          <div #richSelectDropdown role=\"listbox\"\n               style=\"position:absolute;top:100%;left:0;right:0;max-height:200px;overflow-y:auto;background:var(--ogrid-bg, #fff);border:1px solid var(--ogrid-border, rgba(0,0,0,0.12));z-index:10;box-shadow:0 4px 16px rgba(0,0,0,0.2)\">\n            @for (opt of filteredOptions(); track opt; let i = $index) {\n              <div role=\"option\"\n                   [attr.aria-selected]=\"i === highlightedIndex()\"\n                   (click)=\"commitValue(opt)\"\n                   [style]=\"i === highlightedIndex() ? 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424);background:var(--ogrid-bg-hover, #e8f0fe)' : 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424)'\">\n                {{ getDisplayText(opt) }}\n              </div>\n            }\n            @if (filteredOptions().length === 0) {\n              <div style=\"padding:6px 8px;color:var(--ogrid-muted, #999)\">No matches</div>\n            }\n          </div>\n        </div>\n      }\n      @case ('select') {\n        <div #selectWrapper tabindex=\"0\"\n             style=\"width:100%;height:100%;display:flex;align-items:center;padding:6px 10px;box-sizing:border-box;min-width:0;position:relative\"\n             (keydown)=\"onCustomSelectKeyDown($event)\">\n          <div style=\"display:flex;align-items:center;justify-content:space-between;width:100%;cursor:pointer;font-size:13px;color:inherit\">\n            <span>{{ getDisplayText(value) }}</span>\n            <span style=\"margin-left:4px;font-size:10px;opacity:0.5\">&#9662;</span>\n          </div>\n          <div #selectDropdown role=\"listbox\"\n               style=\"position:absolute;top:100%;left:0;right:0;max-height:200px;overflow-y:auto;background:var(--ogrid-bg, #fff);border:1px solid var(--ogrid-border, rgba(0,0,0,0.12));z-index:10;box-shadow:0 4px 16px rgba(0,0,0,0.2)\">\n            @for (opt of selectOptions(); track opt; let i = $index) {\n              <div role=\"option\"\n                   [attr.aria-selected]=\"i === highlightedIndex()\"\n                   (click)=\"commitValue(opt)\"\n                   [style]=\"i === highlightedIndex() ? 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424);background:var(--ogrid-bg-hover, #e8f0fe)' : 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424)'\">\n                {{ getDisplayText(opt) }}\n              </div>\n            }\n          </div>\n        </div>\n      }\n      @case ('checkbox') {\n        <div style=\"display:flex;align-items:center;justify-content:center;width:100%;height:100%\">\n          <input\n            type=\"checkbox\"\n            [checked]=\"!!localValue()\"\n            (change)=\"commitValue($any($event.target).checked)\"\n            (keydown)=\"onCheckboxKeyDown($event)\"\n          />\n        </div>\n      }\n      @case ('date') {\n        <input\n          #inputEl\n          type=\"date\"\n          [value]=\"localValue()\"\n          (change)=\"commitValue($any($event.target).value)\"\n          (keydown)=\"onTextKeyDown($event)\"\n          (blur)=\"onTextBlur()\"\n          [style]=\"getInputStyle()\"\n        />\n      }\n      @default {\n        <input\n          #inputEl\n          type=\"text\"\n          [value]=\"localValue()\"\n          (input)=\"localValue.set($any($event.target).value)\"\n          (keydown)=\"onTextKeyDown($event)\"\n          (blur)=\"onTextBlur()\"\n          [style]=\"getInputStyle()\"\n        />\n      }\n    }\n";
+export declare const INLINE_CELL_EDITOR_TEMPLATE = "\n    @switch (editorType) {\n      @case ('text') {\n        <input\n          #inputEl\n          type=\"text\"\n          [value]=\"localValue()\"\n          (input)=\"localValue.set($any($event.target).value)\"\n          (keydown)=\"onTextKeyDown($event)\"\n          (blur)=\"onTextBlur()\"\n          [style]=\"getInputStyle()\"\n        />\n      }\n      @case ('richSelect') {\n        <div #richSelectWrapper\n             style=\"width:100%;height:100%;display:flex;align-items:center;padding:6px 10px;box-sizing:border-box;min-width:0;position:relative\">\n          <input\n            #richSelectInput\n            type=\"text\"\n            [value]=\"searchText()\"\n            (input)=\"onRichSelectSearch($any($event.target).value)\"\n            (keydown)=\"onRichSelectKeyDown($event)\"\n            placeholder=\"Search...\"\n            style=\"width:100%;padding:0;border:none;background:transparent;color:inherit;font:inherit;font-size:13px;outline:none;min-width:0\"\n          />\n          <div #richSelectDropdown role=\"listbox\"\n               style=\"position:absolute;top:100%;left:0;right:0;max-height:200px;overflow-y:auto;background:var(--ogrid-bg, #fff);border:1px solid var(--ogrid-border, rgba(0,0,0,0.12));z-index:10;box-shadow:0 4px 16px rgba(0,0,0,0.2);text-align:left\">\n            @for (opt of filteredOptions(); track opt; let i = $index) {\n              <div role=\"option\"\n                   [attr.aria-selected]=\"i === highlightedIndex()\"\n                   (click)=\"commitValue(opt)\"\n                   [style]=\"i === highlightedIndex() ? 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424);background:var(--ogrid-bg-hover, #e8f0fe)' : 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424)'\">\n                {{ getDisplayText(opt) }}\n              </div>\n            }\n            @if (filteredOptions().length === 0) {\n              <div style=\"padding:6px 8px;color:var(--ogrid-muted, #999)\">No matches</div>\n            }\n          </div>\n        </div>\n      }\n      @case ('select') {\n        <div #selectWrapper tabindex=\"0\"\n             style=\"width:100%;height:100%;display:flex;align-items:center;padding:6px 10px;box-sizing:border-box;min-width:0;position:relative\"\n             (keydown)=\"onCustomSelectKeyDown($event)\">\n          <div style=\"display:flex;align-items:center;justify-content:space-between;width:100%;cursor:pointer;font-size:13px;color:inherit\">\n            <span>{{ getDisplayText(value) }}</span>\n            <span style=\"margin-left:4px;font-size:10px;opacity:0.5\">&#9662;</span>\n          </div>\n          <div #selectDropdown role=\"listbox\"\n               style=\"position:absolute;top:100%;left:0;right:0;max-height:200px;overflow-y:auto;background:var(--ogrid-bg, #fff);border:1px solid var(--ogrid-border, rgba(0,0,0,0.12));z-index:10;box-shadow:0 4px 16px rgba(0,0,0,0.2);text-align:left\">\n            @for (opt of selectOptions(); track opt; let i = $index) {\n              <div role=\"option\"\n                   [attr.aria-selected]=\"i === highlightedIndex()\"\n                   (click)=\"commitValue(opt)\"\n                   [style]=\"i === highlightedIndex() ? 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424);background:var(--ogrid-bg-hover, #e8f0fe)' : 'padding:6px 8px;cursor:pointer;color:var(--ogrid-fg, #242424)'\">\n                {{ getDisplayText(opt) }}\n              </div>\n            }\n          </div>\n        </div>\n      }\n      @case ('checkbox') {\n        <div style=\"display:flex;align-items:center;justify-content:center;width:100%;height:100%\">\n          <input\n            type=\"checkbox\"\n            [checked]=\"!!localValue()\"\n            (change)=\"commitValue($any($event.target).checked)\"\n            (keydown)=\"onCheckboxKeyDown($event)\"\n          />\n        </div>\n      }\n      @case ('date') {\n        <input\n          #inputEl\n          type=\"date\"\n          [value]=\"localValue()\"\n          (change)=\"commitValue($any($event.target).value)\"\n          (keydown)=\"onTextKeyDown($event)\"\n          (blur)=\"onTextBlur()\"\n          [style]=\"getInputStyle()\"\n        />\n      }\n      @default {\n        <input\n          #inputEl\n          type=\"text\"\n          [value]=\"localValue()\"\n          (input)=\"localValue.set($any($event.target).value)\"\n          (keydown)=\"onTextKeyDown($event)\"\n          (blur)=\"onTextBlur()\"\n          [style]=\"getInputStyle()\"\n        />\n      }\n    }\n";
 export declare const INLINE_CELL_EDITOR_STYLES = "\n    :host {\n      display: block;\n      width: 100%;\n      height: 100%;\n    }\n";

package/dist/types/components/ogrid-layout.component.d.ts

@@ -1,4 +1,6 @@
 import type { SideBarProps } from './sidebar.component';
+import type { OGridFormulaBarState } from '../services/ogrid.service';
+import type { ISheetDef } from '@alaarab/ogrid-core';
 export declare class OGridLayoutComponent {
     className?: string;
     hasToolbar: boolean;
@@ -6,6 +8,13 @@ export declare class OGridLayoutComponent {
     hasPagination: boolean;
     sideBar: SideBarProps | null;
     fullScreen: boolean;
+    showNameBox: boolean;
+    activeCellRef: string | null;
+    formulaBar: OGridFormulaBarState | null;
+    sheetDefs: ISheetDef[] | undefined;
+    activeSheet: string | undefined;
+    onSheetChange: ((sheetId: string) => void) | undefined;
+    onSheetAdd: (() => void) | undefined;
     isFullScreen: boolean;
     readonly borderRadius = 6;
     private escListener;

package/dist/types/components/sheet-tabs.component.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SheetTabsComponent -- Excel-style sheet tab bar at the bottom of the grid.
+ *
+ * Layout: [+] [Sheet1] [Sheet2] [Sheet3]
+ *
+ * Uses --ogrid-* CSS variables for theming.
+ * Port of React's SheetTabs component.
+ */
+import type { ISheetDef } from '@alaarab/ogrid-core';
+export declare class SheetTabsComponent {
+    readonly sheets: import("@angular/core").InputSignal<ISheetDef[]>;
+    readonly activeSheet: import("@angular/core").InputSignal<string>;
+    readonly showAddButton: import("@angular/core").InputSignal<boolean>;
+    readonly sheetChange: import("@angular/core").OutputEmitterRef<string>;
+    readonly sheetAdd: import("@angular/core").OutputEmitterRef<void>;
+}

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export type { IOGridProps, IOGridClientProps, IOGridServerProps, IOGridDataGridP
 export type { ColumnFilterType, IColumnFilterDef, IColumnMeta, ICellValueChangedEvent, CellEditorParams, IValueParserParams, IDateFilterValue, HeaderCell, HeaderRow, RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, IOGridApi, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, } from './types';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange } from './types';
 export { OGridService } from './services/ogrid.service';
-export type { ColumnChooserPlacement, OGridPagination, OGridColumnChooser, OGridFilters, OGridSideBarState, } from './services/ogrid.service';
+export type { ColumnChooserPlacement, OGridPagination, OGridColumnChooser, OGridFilters, OGridSideBarState, OGridFormulaBarState, } from './services/ogrid.service';
 export { DataGridStateService } from './services/datagrid-state.service';
 export type { DataGridLayoutState, DataGridRowSelectionState, DataGridEditingState, DataGridCellInteractionState, DataGridContextMenuState, DataGridViewModelState, DataGridPinningState, DataGridStateResult, } from './services/datagrid-state.service';
 export { DataGridLayoutHelper } from './services/datagrid-layout.service';
@@ -13,12 +13,17 @@ export { DataGridEditingHelper } from './services/datagrid-editing.service';
 export { DataGridInteractionHelper } from './services/datagrid-interaction.service';
 export { ColumnReorderService } from './services/column-reorder.service';
 export { VirtualScrollService } from './services/virtual-scroll.service';
+export { FormulaEngineService } from './services/formula-engine.service';
+export type { FormulaEngineConfig } from './services/formula-engine.service';
 export { OGridLayoutComponent } from './components/ogrid-layout.component';
 export { StatusBarComponent } from './components/status-bar.component';
 export { GridContextMenuComponent } from './components/grid-context-menu.component';
 export { SideBarComponent } from './components/sidebar.component';
 export type { SideBarProps, SideBarFilterColumn } from './components/sidebar.component';
 export { MarchingAntsOverlayComponent } from './components/marching-ants-overlay.component';
+export { FormulaBarComponent } from './components/formula-bar.component';
+export { SheetTabsComponent } from './components/sheet-tabs.component';
+export { FormulaRefOverlayComponent } from './components/formula-ref-overlay.component';
 export { EmptyStateComponent } from './components/empty-state.component';
 export { BaseOGridComponent } from './components/base-ogrid.component';
 export { BaseDataGridTableComponent } from './components/base-datagrid-table.component';
@@ -28,6 +33,7 @@ export { BaseColumnChooserComponent } from './components/base-column-chooser.com
 export type { IColumnChooserProps } from './components/base-column-chooser.component';
 export { BasePaginationControlsComponent } from './components/base-pagination-controls.component';
 export { BaseInlineCellEditorComponent } from './components/base-inline-cell-editor.component';
+export { BaseColumnHeaderMenuComponent } from './components/base-column-header-menu.component';
 export { INLINE_CELL_EDITOR_TEMPLATE, INLINE_CELL_EDITOR_STYLES } from './components/inline-cell-editor-template';
 export { BasePopoverCellEditorComponent, POPOVER_CELL_EDITOR_TEMPLATE, POPOVER_CELL_EDITOR_OVERLAY_STYLES } from './components/base-popover-cell-editor.component';
 export { OGRID_THEME_VARS_CSS } from './styles/ogrid-theme-vars';

package/dist/types/services/datagrid-state.service.d.ts

@@ -119,6 +119,9 @@ export interface DataGridViewModelState<T> {
         editable?: boolean;
         onCellValueChanged?: (event: ICellValueChangedEvent<T>) => void;
         isDragging: boolean;
+        getFormulaValue?: (col: number, row: number) => unknown;
+        hasFormula?: (col: number, row: number) => boolean;
+        formulaVersion?: number;
     };
     statusBarConfig: IStatusBarProps | null;
     showEmptyInGrid: boolean;

package/dist/types/services/formula-engine.service.d.ts

@@ -0,0 +1,131 @@
+/**
+ * FormulaEngineService — Angular service for integrating the formula engine with the grid.
+ *
+ * Lazily creates a FormulaEngine instance when configured with `formulas: true`.
+ * Provides an accessor bridge between grid data and formula coordinates.
+ * Uses Angular signals for reactive state.
+ *
+ * Port of React's useFormulaEngine hook.
+ */
+import type { IGridDataAccessor, IFormulaFunction, IRecalcResult, IColumnDef, IAuditEntry, IAuditTrail } from '@alaarab/ogrid-core';
+export interface FormulaEngineConfig {
+    /** Enable formula support. */
+    formulas?: boolean;
+    /** Initial formulas to load on first configure. */
+    initialFormulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /** Custom formula functions to register. */
+    formulaFunctions?: Record<string, IFormulaFunction>;
+    /** Called when recalculation produces cascading updates. */
+    onFormulaRecalc?: (result: IRecalcResult) => void;
+    /** Named ranges: name → cell/range reference string. */
+    namedRanges?: Record<string, string>;
+    /** Sheet accessors for cross-sheet references. */
+    sheets?: Record<string, IGridDataAccessor>;
+}
+/**
+ * Per-component injectable service that wraps FormulaEngine from @alaarab/ogrid-core.
+ *
+ * Not providedIn: 'root' — provide it per component so each grid instance
+ * gets its own formula engine.
+ */
+export declare class FormulaEngineService<T = unknown> {
+    private destroyRef;
+    private engine;
+    private initialLoaded;
+    private onFormulaRecalcFn;
+    private items;
+    private flatColumns;
+    /** Whether formula support is currently enabled. */
+    readonly enabled: import("@angular/core").WritableSignal<boolean>;
+    /** Last recalculation result, for UI to react to formula changes. */
+    readonly lastRecalcResult: import("@angular/core").WritableSignal<IRecalcResult | null>;
+    /** Number of formulas currently registered. */
+    readonly formulaCount: import("@angular/core").Signal<number>;
+    constructor();
+    /**
+     * Configure the formula engine. Call this when the grid component initializes.
+     *
+     * Lazily creates the FormulaEngine only when `formulas: true`.
+     */
+    configure(options: FormulaEngineConfig): void;
+    /**
+     * Update the data references used by the accessor bridge.
+     * Call this whenever the grid's items or columns change.
+     */
+    setData(items: T[], flatColumns: IColumnDef<T>[]): void;
+    /**
+     * Set or clear a formula for a cell. Triggers recalculation of dependents.
+     */
+    setFormula(col: number, row: number, formula: string | null, accessor?: IGridDataAccessor): void;
+    /**
+     * Notify the engine that a non-formula cell's value changed.
+     * Triggers recalculation of any formulas that depend on this cell.
+     */
+    onCellChanged(col: number, row: number, accessor?: IGridDataAccessor): void;
+    /**
+     * Get the formula engine's computed value for a cell coordinate.
+     */
+    getValue(col: number, row: number): unknown | undefined;
+    /**
+     * 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;
+    /**
+     * Trigger a full recalculation of all formulas.
+     */
+    recalcAll(accessor?: IGridDataAccessor): void;
+    /**
+     * Get all formulas for serialization.
+     */
+    getAllFormulas(): Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /**
+     * Register a custom function at runtime.
+     */
+    registerFunction(name: string, fn: IFormulaFunction): void;
+    /**
+     * Clear all formulas and cached values.
+     */
+    clear(): void;
+    /**
+     * Define a named range.
+     */
+    defineNamedRange(name: string, ref: string): void;
+    /**
+     * Remove a named range.
+     */
+    removeNamedRange(name: string): void;
+    /**
+     * Register a sheet accessor for cross-sheet references.
+     */
+    registerSheet(name: string, accessor: IGridDataAccessor): void;
+    /**
+     * Unregister a sheet accessor.
+     */
+    unregisterSheet(name: string): 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;
+    /** Create a data accessor that bridges grid data to formula coordinates. */
+    private createAccessor;
+}

package/dist/types/services/ogrid.service.d.ts

@@ -1,4 +1,5 @@
-import type { RowId, IOGridApi, IFilters, FilterValue, IRowSelectionChangeEvent, IStatusBarProps, IColumnDefinition, IDataSource, ISideBarDef, IVirtualScrollConfig, SideBarPanelId } from '../types';
+import type { FormulaReference } from '@alaarab/ogrid-core';
+import type { RowId, IOGridApi, IFilters, FilterValue, IRowSelectionChangeEvent, IStatusBarProps, IColumnDefinition, IDataSource, ISideBarDef, IVirtualScrollConfig, SideBarPanelId, IFormulaFunction, IRecalcResult, IGridDataAccessor } from '../types';
 import type { IOGridProps, IOGridDataGridProps } from '../types';
 import type { IColumnDef, IColumnGroupDef, ICellValueChangedEvent } from '../types';
 import type { SideBarProps } from '../components/sidebar.component';
@@ -26,6 +27,17 @@ export interface OGridFilters {
     hasActiveFilters: boolean;
     setFilters: (f: IFilters) => void;
 }
+/** Formula bar state and handlers. */
+export interface OGridFormulaBarState {
+    cellRef: string | null;
+    formulaText: string;
+    isEditing: boolean;
+    onInputChange: (text: string) => void;
+    onCommit: () => void;
+    onCancel: () => void;
+    startEditing: () => void;
+    referencedCells: FormulaReference[];
+}
 /** Side bar state. */
 export interface OGridSideBarState {
     isEnabled: boolean;
@@ -109,6 +121,44 @@ export declare class OGridService<T> {
     readonly ariaLabel: import("@angular/core").WritableSignal<string | undefined>;
     readonly ariaLabelledBy: import("@angular/core").WritableSignal<string | undefined>;
     readonly workerSort: import("@angular/core").WritableSignal<boolean>;
+    readonly showRowNumbers: import("@angular/core").WritableSignal<boolean>;
+    readonly cellReferences: import("@angular/core").WritableSignal<boolean>;
+    readonly formulasEnabled: import("@angular/core").WritableSignal<boolean>;
+    readonly initialFormulas: import("@angular/core").WritableSignal<{
+        col: number;
+        row: number;
+        formula: string;
+    }[] | undefined>;
+    readonly onFormulaRecalc: import("@angular/core").WritableSignal<((result: IRecalcResult) => void) | undefined>;
+    readonly formulaFunctions: import("@angular/core").WritableSignal<Record<string, IFormulaFunction> | undefined>;
+    readonly namedRanges: import("@angular/core").WritableSignal<Record<string, string> | undefined>;
+    readonly sheets: import("@angular/core").WritableSignal<Record<string, IGridDataAccessor> | undefined>;
+    readonly sheetDefs: import("@angular/core").WritableSignal<import("@alaarab/ogrid-core").ISheetDef[] | undefined>;
+    readonly activeSheet: import("@angular/core").WritableSignal<string | undefined>;
+    readonly onSheetChange: import("@angular/core").WritableSignal<((sheetId: string) => void) | undefined>;
+    readonly onSheetAdd: import("@angular/core").WritableSignal<(() => void) | undefined>;
+    /** Active cell reference string (e.g. 'A1') updated by DataGridTable when cellReferences is enabled. */
+    readonly activeCellRef: import("@angular/core").WritableSignal<string | null>;
+    /** Active cell coordinates (0-based col/row). */
+    readonly activeCellCoords: import("@angular/core").WritableSignal<{
+        col: number;
+        row: number;
+    } | null>;
+    /** Stable callback passed to DataGridTable to update activeCellRef + coords. */
+    private readonly handleActiveCellChange;
+    private readonly formulaBarEditing;
+    private readonly formulaBarEditText;
+    private readonly formulaService;
+    /** Monotonic counter incremented on formula recalculation — drives cache invalidation. */
+    readonly formulaVersion: import("@angular/core").WritableSignal<number>;
+    private readonly getFormulaValueFn;
+    private readonly hasFormulaFn;
+    private readonly getFormulaFn;
+    private readonly setFormulaFn;
+    private readonly onFormulaCellChangedFn;
+    private readonly getPrecedentsFn;
+    private readonly getDependentsFn;
+    private readonly getAuditTrailFn;
     private readonly internalData;
     private readonly internalLoading;
     private readonly internalPage;
@@ -179,6 +229,18 @@ export declare class OGridService<T> {
         filterType: "text" | "multiSelect" | "people" | "date";
     }[]>;
     readonly sideBarState: import("@angular/core").Signal<OGridSideBarState>;
+    /** Display text derived from active cell (formula string or raw value). */
+    private readonly formulaBarDisplayText;
+    /** Formula text shown in the bar: edit text when editing, display text otherwise. */
+    readonly formulaBarText: import("@angular/core").Signal<string>;
+    /** References extracted from the current formula text (for highlighting). */
+    readonly formulaBarReferences: import("@angular/core").Signal<FormulaReference[]>;
+    private readonly formulaBarOnInputChangeFn;
+    private readonly formulaBarOnCommitFn;
+    private readonly formulaBarOnCancelFn;
+    private readonly formulaBarStartEditingFn;
+    /** Aggregate formula bar state for template consumption. */
+    readonly formulaBarState: import("@angular/core").Signal<OGridFormulaBarState>;
     private readonly handleSortFn;
     private readonly handleColumnResizedFn;
     private readonly handleColumnPinnedFn;
@@ -208,6 +270,9 @@ export declare class OGridService<T> {
     handleSelectionChange(event: IRowSelectionChangeEvent<T>): void;
     handleColumnResized(columnId: string, width: number): void;
     handleColumnPinned(columnId: string, pinned: 'left' | 'right' | null): void;
+    private startFormulaBarEditing;
+    private commitFormulaBar;
+    private cancelFormulaBar;
     configure(props: IOGridProps<T>): void;
     /**
      * Pin a column to the left or right edge.

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

@@ -1,8 +1,8 @@
 import type { TemplateRef } from '@angular/core';
 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, IOGridApi, } from '@alaarab/ogrid-core';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IOGridApi, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail, ISheetDef, FormulaReference, } 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, IVirtualScrollConfig, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail, ISheetDef, FormulaReference } from '@alaarab/ogrid-core';
 /** Base props shared by both client-side and server-side OGrid modes. */
 interface IOGridBaseProps<T> {
     columns: (IColumnDef<T> | IColumnGroupDef<T>)[];
@@ -72,6 +72,32 @@ interface IOGridBaseProps<T> {
     onError?: (error: unknown) => void;
     onCellError?: (error: Error, info: unknown) => void;
     showRowNumbers?: boolean;
+    /** Enable Excel-style cell references: column letter headers, row numbers, and name box. Implies showRowNumbers. */
+    cellReferences?: boolean;
+    /** 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 the tab bar at grid bottom. */
+    sheetDefs?: ISheetDef[];
+    /** Active sheet ID (controlled). */
+    activeSheet?: string;
+    /** Called when user clicks a sheet tab. */
+    onSheetChange?: (sheetId: string) => void;
+    /** Called when user clicks the "+" add sheet button. */
+    onSheetAdd?: () => void;
     'aria-label'?: string;
     'aria-labelledby'?: string;
 }
@@ -123,6 +149,9 @@ export interface IOGridDataGridProps<T> {
     selectedRows?: Set<RowId>;
     onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
     showRowNumbers?: boolean;
+    showColumnLetters?: boolean;
+    showNameBox?: boolean;
+    onActiveCellChange?: (ref: string | null) => void;
     currentPage?: number;
     pageSize?: number;
     statusBar?: IStatusBarProps;
@@ -147,4 +176,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: 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?: 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, } 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, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail, ISheetDef, FormulaReference, } from './dataGridTypes';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange } from './dataGridTypes';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-angular",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "OGrid Angular – Angular services, signals, and headless components for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
@@ -35,7 +35,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@alaarab/ogrid-core": "2.2.0"
+    "@alaarab/ogrid-core": "2.4.0"
   },
   "peerDependencies": {
     "@angular/core": "^21.0.0",