@alaarab/ogrid-core 2.2.0 → 2.4.0

package/dist/types/constants/formulaBar.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Formula bar and formula reference highlighting constants.
+ * Shared across React, Angular, Vue, and JS packages.
+ */
+/** Color palette for formula reference highlights (cycles 0–5). Uses CSS vars with fallbacks. */
+export declare const FORMULA_REF_COLORS: readonly ["var(--ogrid-formula-ref-0, #4285f4)", "var(--ogrid-formula-ref-1, #ea4335)", "var(--ogrid-formula-ref-2, #34a853)", "var(--ogrid-formula-ref-3, #9334e6)", "var(--ogrid-formula-ref-4, #ff6d01)", "var(--ogrid-formula-ref-5, #46bdc6)"];
+/** CSS text for the formula bar container (used by JS and Angular inline styles). */
+export declare const FORMULA_BAR_CSS: {
+    readonly bar: "display:flex;align-items:center;border-bottom:1px solid var(--ogrid-border, #e0e0e0);background:var(--ogrid-bg, #fff);min-height:28px;font-size:13px;";
+    readonly nameBox: "font-family:monospace;font-size:12px;font-weight:500;padding:2px 8px;border-right:1px solid var(--ogrid-border, #e0e0e0);background:var(--ogrid-bg, #fff);color:var(--ogrid-fg, #242424);min-width:52px;text-align:center;line-height:24px;user-select:none;white-space:nowrap;";
+    readonly fxLabel: "padding:2px 8px;font-style:italic;font-weight:600;color:var(--ogrid-muted-fg, #888);user-select:none;border-right:1px solid var(--ogrid-border, #e0e0e0);line-height:24px;font-size:12px;";
+    readonly input: "flex:1;border:none;outline:none;padding:2px 8px;font-family:monospace;font-size:12px;line-height:24px;background:transparent;color:var(--ogrid-fg, #242424);min-width:0;";
+};
+/** Style objects for the formula bar — used by React and Vue (CSSProperties-compatible). */
+export declare const FORMULA_BAR_STYLES: {
+    readonly bar: {
+        readonly display: "flex";
+        readonly alignItems: "center";
+        readonly borderBottom: "1px solid var(--ogrid-border, #e0e0e0)";
+        readonly background: "var(--ogrid-bg, #fff)";
+        readonly minHeight: "28px";
+        readonly fontSize: "13px";
+    };
+    readonly nameBox: {
+        readonly fontFamily: "monospace";
+        readonly fontSize: "12px";
+        readonly fontWeight: 500;
+        readonly padding: "2px 8px";
+        readonly borderRight: "1px solid var(--ogrid-border, #e0e0e0)";
+        readonly background: "var(--ogrid-bg, #fff)";
+        readonly color: "var(--ogrid-fg, #242424)";
+        readonly minWidth: "52px";
+        readonly textAlign: "center";
+        readonly lineHeight: "24px";
+        readonly userSelect: "none";
+        readonly whiteSpace: "nowrap";
+    };
+    readonly fxLabel: {
+        readonly padding: "2px 8px";
+        readonly fontStyle: "italic";
+        readonly fontWeight: 600;
+        readonly color: "var(--ogrid-muted-fg, #888)";
+        readonly userSelect: "none";
+        readonly borderRight: "1px solid var(--ogrid-border, #e0e0e0)";
+        readonly lineHeight: "24px";
+        readonly fontSize: "12px";
+    };
+    readonly input: {
+        readonly flex: 1;
+        readonly border: "none";
+        readonly outline: "none";
+        readonly padding: "2px 8px";
+        readonly fontFamily: "monospace";
+        readonly fontSize: "12px";
+        readonly lineHeight: "24px";
+        readonly background: "transparent";
+        readonly color: "var(--ogrid-fg, #242424)";
+        readonly minWidth: 0;
+    };
+};

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

@@ -2,3 +2,4 @@ export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDT
 export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './timing';
 export { Z_INDEX } from './zIndex';
 export type { ZIndexKey } from './zIndex';
+export { FORMULA_REF_COLORS, FORMULA_BAR_CSS, FORMULA_BAR_STYLES } from './formulaBar';

package/dist/types/formula/cellAddressUtils.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cell address parsing and formatting utilities for the formula system.
+ * Extends the existing cellReference.ts with reverse parsing and absolute reference support.
+ */
+import type { ICellAddress, ICellRange, CellKey } from './types';
+/**
+ * Parse a column letter string to a 0-based index.
+ * @example columnLetterToIndex('A')  // 0
+ * @example columnLetterToIndex('Z')  // 25
+ * @example columnLetterToIndex('AA') // 26
+ * @example columnLetterToIndex('AZ') // 51
+ */
+export declare function columnLetterToIndex(letters: string): number;
+/**
+ * Parse a cell reference string like "A1", "$B$2", "$A1", "A$1".
+ * Returns null on invalid input.
+ */
+export declare function parseCellRef(ref: string): ICellAddress | null;
+/**
+ * Parse a range string like "A1:B10".
+ * Returns null on invalid input.
+ */
+export declare function parseRange(rangeStr: string): ICellRange | null;
+/**
+ * Convert a cell address back to a display string like "A1", "$A$1", or "Sheet2!A1".
+ */
+export declare function formatAddress(addr: ICellAddress): string;
+/**
+ * Adjusts relative cell references in a formula string by a row/column delta.
+ * Absolute references ($A$1) are not adjusted. Mixed refs ($A1, A$1) adjust only the relative part.
+ *
+ * @param formula   The formula string (e.g. "=A1+B1")
+ * @param colDelta  Column offset to apply to relative column references
+ * @param rowDelta  Row offset to apply to relative row references
+ * @returns The adjusted formula string. Out-of-bounds references become "#REF!".
+ */
+export declare function adjustFormulaReferences(formula: string, colDelta: number, rowDelta: number): string;
+/**
+ * Convert (col, row) to a CellKey for Map storage.
+ * When sheet is specified: "sheetName:col,row". Otherwise: "col,row".
+ */
+export declare function toCellKey(col: number, row: number, sheet?: string): CellKey;
+/**
+ * Parse a CellKey back to (col, row) and optional sheet.
+ */
+export declare function fromCellKey(key: CellKey): {
+    col: number;
+    row: number;
+    sheet?: string;
+};

package/dist/types/formula/dependencyGraph.d.ts

@@ -0,0 +1,72 @@
+import type { CellKey } from './types';
+export declare class DependencyGraph {
+    /** cell -> set of cells it depends on (references in its formula) */
+    private dependencies;
+    /** cell -> set of cells that depend on it (reverse index) */
+    private dependents;
+    /**
+     * Set the dependencies for a cell, replacing any previous ones.
+     * Updates both the forward (dependencies) and reverse (dependents) maps.
+     */
+    setDependencies(cell: CellKey, deps: Set<CellKey>): void;
+    /**
+     * Remove all dependency information for a cell from both maps.
+     */
+    removeDependencies(cell: CellKey): void;
+    /**
+     * Get all cells that directly or transitively depend on `changedCell`,
+     * returned in topological order (a cell appears AFTER all cells it depends on).
+     *
+     * Uses Kahn's algorithm. If a cycle is detected, cycle participants are
+     * appended at the end (the engine will assign #CIRC! to them).
+     */
+    getRecalcOrder(changedCell: CellKey): CellKey[];
+    /**
+     * Same as getRecalcOrder but for multiple changed cells.
+     * Union of all transitive dependents, topologically sorted.
+     */
+    getRecalcOrderBatch(changedCells: CellKey[]): CellKey[];
+    /**
+     * Check if adding dependencies from `cell` to `deps` would create a cycle.
+     * DFS from each dep: if we can reach `cell`, it would create a cycle.
+     */
+    wouldCreateCycle(cell: CellKey, deps: Set<CellKey>): boolean;
+    /**
+     * Return direct dependents of a cell (cells whose formulas reference this cell).
+     * Returns an empty set if none.
+     */
+    getDependents(cell: CellKey): ReadonlySet<CellKey>;
+    /**
+     * Return direct dependencies of a cell (cells referenced in this cell's formula).
+     * Returns an empty set if none.
+     */
+    getDependencies(cell: CellKey): ReadonlySet<CellKey>;
+    /**
+     * Clear both maps entirely.
+     */
+    clear(): void;
+    /**
+     * Remove `cell` from the forward dependencies map and clean up reverse
+     * references in the dependents map.
+     */
+    private removeDependenciesInternal;
+    /**
+     * Iterative DFS: check if `target` is reachable from `start` by following
+     * the dependency chain. Iterative to avoid stack overflow for deep chains.
+     */
+    private canReach;
+    /**
+     * Topological sort using Kahn's algorithm.
+     *
+     * 1. Collect all cells transitively dependent on the changed cell(s).
+     * 2. Build in-degree map for these cells (count how many of their
+     *    dependencies are in the affected set).
+     * 3. Start with cells whose in-degree is 0 (only depend on unaffected
+     *    cells or the changed cells themselves).
+     * 4. Process queue: for each cell, reduce in-degree of its dependents,
+     *    add to queue when in-degree reaches 0.
+     * 5. If any cells remain unprocessed, they're in a cycle — append them
+     *    at the end (engine marks as #CIRC!).
+     */
+    private topologicalSort;
+}

package/dist/types/formula/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Formula error constants for convenient usage.
+ */
+import { FormulaError } from './types';
+import type { FormulaErrorType } from './types';
+export { FormulaError, type FormulaErrorType };
+export declare const REF_ERROR: FormulaError;
+export declare const DIV_ZERO_ERROR: FormulaError;
+export declare const VALUE_ERROR: FormulaError;
+export declare const NAME_ERROR: FormulaError;
+export declare const CIRC_ERROR: FormulaError;
+export declare const GENERAL_ERROR: FormulaError;
+export declare const NA_ERROR: FormulaError;
+/** Check if a value is a FormulaError instance. */
+export declare function isFormulaError(value: unknown): value is FormulaError;

package/dist/types/formula/evaluator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Formula evaluator — walks an AST and computes the result.
+ */
+import type { ASTNode, IFormulaContext, IEvaluator, IFormulaFunction } from './types';
+import { FormulaError } from './types';
+/** Coerce a value to number following Excel semantics. */
+export declare function toNumber(val: unknown): number | FormulaError;
+/** Coerce a value to string. */
+export declare function toString(val: unknown): string;
+/** Coerce a value to boolean following Excel semantics. */
+export declare function toBoolean(val: unknown): boolean;
+/** Evaluate each arg, expanding ranges into flat arrays. */
+export declare function flattenArgs(args: ASTNode[], context: IFormulaContext, evaluator: IEvaluator): unknown[];
+export declare class FormulaEvaluator implements IEvaluator {
+    private functions;
+    constructor(builtInFunctions: Map<string, IFormulaFunction>);
+    registerFunction(name: string, fn: IFormulaFunction): void;
+    evaluate(node: ASTNode, context: IFormulaContext): unknown;
+    private evaluateFunction;
+    private evaluateBinaryOp;
+    private evaluateUnaryOp;
+    private compare;
+    private numCompare;
+    private strCompare;
+}

package/dist/types/formula/formulaEngine.d.ts

@@ -0,0 +1,104 @@
+/**
+ * FormulaEngine — orchestrates parser, evaluator, dependency graph, and formula storage.
+ */
+import type { IFormulaEngineConfig, IRecalcResult, IFormulaFunction, IGridDataAccessor, IAuditEntry, IAuditTrail } from './types';
+export declare class FormulaEngine {
+    private readonly formulas;
+    private readonly parsedFormulas;
+    private readonly values;
+    private readonly depGraph;
+    private readonly evaluator;
+    private readonly maxChainLength;
+    private readonly namedRanges;
+    private readonly sheetAccessors;
+    constructor(config?: IFormulaEngineConfig);
+    /**
+     * Set or clear a formula for a cell.
+     */
+    setFormula(col: number, row: number, formula: string | null, accessor: IGridDataAccessor): IRecalcResult;
+    /**
+     * Notify the engine that a non-formula cell's value changed.
+     */
+    onCellChanged(col: number, row: number, accessor: IGridDataAccessor): IRecalcResult;
+    /**
+     * Batch notify: multiple cells changed.
+     */
+    onCellsChanged(cells: Array<{
+        col: number;
+        row: number;
+    }>, accessor: IGridDataAccessor): IRecalcResult;
+    /**
+     * Get the current computed value for a cell.
+     */
+    getValue(col: number, row: number): unknown | undefined;
+    /**
+     * Get the formula string for a cell.
+     */
+    getFormula(col: number, row: number): string | undefined;
+    /**
+     * Check if a cell has a formula.
+     */
+    hasFormula(col: number, row: number): boolean;
+    /**
+     * Register a custom function at runtime.
+     */
+    registerFunction(name: string, fn: IFormulaFunction): void;
+    /**
+     * Full recalculation of all formulas.
+     */
+    recalcAll(accessor: IGridDataAccessor): IRecalcResult;
+    /**
+     * Clear all formulas and cached values.
+     */
+    clear(): void;
+    /**
+     * Get all formula entries for serialization.
+     */
+    getAllFormulas(): Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /**
+     * Bulk-load formulas. Recalculates everything.
+     */
+    loadFormulas(formulas: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>, accessor: IGridDataAccessor): IRecalcResult;
+    /**
+     * Define a named range (e.g. "Revenue" → "A1:A10").
+     */
+    defineNamedRange(name: string, ref: string): void;
+    /**
+     * Remove a named range by name.
+     */
+    removeNamedRange(name: string): void;
+    /**
+     * Get all named ranges as a Map (name → ref).
+     */
+    getNamedRanges(): ReadonlyMap<string, string>;
+    /**
+     * Register a data accessor for a named sheet (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 precedents).
+     */
+    getPrecedents(col: number, row: number): IAuditEntry[];
+    /**
+     * Get all cells that depend on this cell (deep, transitive dependents).
+     */
+    getDependents(col: number, row: number): IAuditEntry[];
+    /**
+     * Get a full audit trail for a cell: target + precedents + dependents.
+     */
+    getAuditTrail(col: number, row: number): IAuditTrail;
+    private createContext;
+    private recalcCells;
+}

package/dist/types/formula/functions/date.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerDateFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/financial.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerFinancialFunctions(registry: Map<string, IFormulaFunction>): void;

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

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function createBuiltInFunctions(): Map<string, IFormulaFunction>;

package/dist/types/formula/functions/info.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerInfoFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/logical.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerLogicalFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/lookup.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerLookupFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/math.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerMathFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/reference.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerReferenceFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/statistical-extended.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerStatisticalExtendedFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/stats.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerStatsFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/text.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerTextFunctions(registry: Map<string, IFormulaFunction>): void;

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

@@ -0,0 +1,13 @@
+/**
+ * Formula system — barrel export.
+ */
+export type { ICellAddress, ICellRange, CellKey, FormulaErrorType, TokenType, Token, ASTNode, NumberLiteral, StringLiteral, BooleanLiteral, CellRefNode, RangeNode, FunctionCallNode, BinaryOp, BinaryOpNode, UnaryOpNode, ErrorNode, IFormulaContext, IFormulaFunction, IEvaluator, IRecalcResult, IFormulaEngineConfig, IGridDataAccessor, INamedRange, IAuditEntry, IAuditTrail, } from './types';
+export { FormulaError } from './types';
+export { REF_ERROR, DIV_ZERO_ERROR, VALUE_ERROR, NAME_ERROR, CIRC_ERROR, GENERAL_ERROR, NA_ERROR, isFormulaError, } from './errors';
+export { columnLetterToIndex, parseCellRef, parseRange, formatAddress, toCellKey, fromCellKey, adjustFormulaReferences, } from './cellAddressUtils';
+export { tokenize } from './tokenizer';
+export { parse } from './parser';
+export { FormulaEvaluator, toNumber, toString, toBoolean, flattenArgs, } from './evaluator';
+export { DependencyGraph } from './dependencyGraph';
+export { FormulaEngine } from './formulaEngine';
+export { createBuiltInFunctions } from './functions';

package/dist/types/formula/parser.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Recursive descent parser: converts Token[] to an ASTNode.
+ *
+ * Grammar (precedence low → high):
+ *   expression     → comparison
+ *   comparison     → concat (('>' | '<' | '>=' | '<=' | '=' | '<>') concat)*
+ *   concat         → addition ('&' addition)*
+ *   addition       → multiplication (('+' | '-') multiplication)*
+ *   multiplication → power (('*' | '/') power)*
+ *   power          → unary ('^' unary)*
+ *   unary          → ('-' | '+') unary | postfix
+ *   postfix        → primary '%'?
+ *   primary        → NUMBER | STRING | BOOLEAN | cellRefOrRange | functionCall
+ *                   | '(' expression ')'
+ *   cellRefOrRange → CELL_REF (':' CELL_REF)?
+ *   functionCall   → FUNCTION '(' (expression (',' expression)*)? ')'
+ */
+import type { Token, ASTNode } from './types';
+/**
+ * Parse an array of tokens into an AST.
+ * Never throws — returns an ErrorNode on parse errors.
+ *
+ * @param tokens - The token array from the tokenizer.
+ * @param namedRanges - Optional map of named ranges (name → ref string like "A1:B10").
+ */
+export declare function parse(tokens: Token[], namedRanges?: Map<string, string>): ASTNode;

package/dist/types/formula/tokenizer.d.ts

@@ -0,0 +1,7 @@
+import type { Token } from './types';
+/**
+ * Tokenizes a formula string (without the leading '=') into an array of tokens.
+ *
+ * This is a single-pass character-at-a-time lexer for spreadsheet formulas.
+ */
+export declare function tokenize(input: string): Token[];

package/dist/types/formula/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Formula system type definitions.
+ */
+/** A parsed cell address. Row and column are 0-based internally. */
+export interface ICellAddress {
+    col: number;
+    row: number;
+    absCol: boolean;
+    absRow: boolean;
+    /** Sheet name for cross-sheet references. Undefined = current sheet. */
+    sheet?: string;
+}
+/** A rectangular range of cells. */
+export interface ICellRange {
+    start: ICellAddress;
+    end: ICellAddress;
+}
+/** String key for a cell: "col,row" for internal Map storage. */
+export type CellKey = string;
+export type FormulaErrorType = '#REF!' | '#DIV/0!' | '#VALUE!' | '#NAME?' | '#CIRC!' | '#ERROR!' | '#N/A' | '#NUM!';
+export declare class FormulaError {
+    readonly type: FormulaErrorType;
+    readonly message?: string | undefined;
+    constructor(type: FormulaErrorType, message?: string | undefined);
+    toString(): string;
+}
+export type TokenType = 'NUMBER' | 'STRING' | 'BOOLEAN' | 'CELL_REF' | 'FUNCTION' | 'IDENTIFIER' | 'SHEET_REF' | 'LPAREN' | 'RPAREN' | 'COMMA' | 'COLON' | 'PLUS' | 'MINUS' | 'MULTIPLY' | 'DIVIDE' | 'POWER' | 'PERCENT' | 'AMPERSAND' | 'GT' | 'LT' | 'GTE' | 'LTE' | 'EQ' | 'NEQ' | 'EOF';
+export interface Token {
+    type: TokenType;
+    value: string;
+    position: number;
+}
+export type ASTNode = NumberLiteral | StringLiteral | BooleanLiteral | CellRefNode | RangeNode | FunctionCallNode | BinaryOpNode | UnaryOpNode | ErrorNode;
+export interface NumberLiteral {
+    kind: 'number';
+    value: number;
+}
+export interface StringLiteral {
+    kind: 'string';
+    value: string;
+}
+export interface BooleanLiteral {
+    kind: 'boolean';
+    value: boolean;
+}
+export interface CellRefNode {
+    kind: 'cellRef';
+    address: ICellAddress;
+    raw: string;
+}
+export interface RangeNode {
+    kind: 'range';
+    start: ICellAddress;
+    end: ICellAddress;
+    raw: string;
+}
+export interface FunctionCallNode {
+    kind: 'functionCall';
+    name: string;
+    args: ASTNode[];
+}
+export type BinaryOp = '+' | '-' | '*' | '/' | '^' | '%' | '&' | '>' | '<' | '>=' | '<=' | '=' | '<>';
+export interface BinaryOpNode {
+    kind: 'binaryOp';
+    op: BinaryOp;
+    left: ASTNode;
+    right: ASTNode;
+}
+export interface UnaryOpNode {
+    kind: 'unaryOp';
+    op: '+' | '-';
+    operand: ASTNode;
+}
+export interface ErrorNode {
+    kind: 'error';
+    error: FormulaError;
+}
+/** Context passed to formula functions during evaluation. */
+export interface IFormulaContext {
+    getCellValue(address: ICellAddress): unknown;
+    getRangeValues(range: ICellRange): unknown[][];
+    now(): Date;
+    /** Optional: return the formula string for a cell, or undefined if not a formula cell. */
+    getCellFormula?(address: ICellAddress): string | undefined;
+}
+/** A registered formula function. */
+export interface IFormulaFunction {
+    minArgs: number;
+    maxArgs: number;
+    /** Functions receive raw AST nodes so they can handle ranges specially. */
+    evaluate(args: ASTNode[], context: IFormulaContext, evaluator: IEvaluator): unknown;
+}
+/** The evaluator interface that functions can call back into. */
+export interface IEvaluator {
+    evaluate(node: ASTNode, context: IFormulaContext): unknown;
+}
+/** Result of a cell change: which cells were recalculated. */
+export interface IRecalcResult {
+    updatedCells: Array<{
+        cellKey: CellKey;
+        col: number;
+        row: number;
+        oldValue: unknown;
+        newValue: unknown;
+    }>;
+}
+/** Configuration for the FormulaEngine. */
+export interface IFormulaEngineConfig {
+    maxChainLength?: number;
+    customFunctions?: Record<string, IFormulaFunction>;
+    /** Named ranges: name → cell/range reference string (e.g. "A1:B10"). */
+    namedRanges?: Record<string, string>;
+}
+/** Grid data accessor — bridge between FormulaEngine and the grid's data model. */
+export interface IGridDataAccessor {
+    getCellValue(col: number, row: number): unknown;
+    getRowCount(): number;
+    getColumnCount(): number;
+}
+/** A named range definition. */
+export interface INamedRange {
+    name: string;
+    /** Cell or range reference string, e.g. "A1" or "A1:B10". */
+    ref: string;
+}
+/** A single cell entry in an audit trail. */
+export interface IAuditEntry {
+    cellKey: CellKey;
+    col: number;
+    row: number;
+    formula?: string;
+    value: unknown;
+}
+/** Full audit trail for a cell: its precedents and dependents. */
+export interface IAuditTrail {
+    target: IAuditEntry;
+    /** All cells that this cell depends on (deep, transitive). */
+    precedents: IAuditEntry[];
+    /** All cells that depend on this cell (deep, transitive). */
+    dependents: IAuditEntry[];
+}

package/dist/types/index.d.ts

@@ -1,9 +1,9 @@
 export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, IColumnDef, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } from './types';
-export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './types';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, ISheetDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './types';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './types';
 export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';
-export type { CsvColumn } from './utils';
-export { getCellValue, isColumnEditable } from './utils';
+export type { CsvColumn, FormulaExportOptions } from './utils';
+export { getCellValue, isColumnEditable, createGridDataAccessor } from './utils';
 export { flattenColumns, buildHeaderRows } from './utils';
 export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './utils';
 export { getStatusBarParts } from './utils';
@@ -39,9 +39,16 @@ export type { ArrowNavigationContext, ArrowNavigationResult } from './utils';
 export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, applyRangeRowSelection, computeRowSelectionState } from './utils';
 export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, } from './utils';
 export { applyFillValues } from './utils';
+export type { IFillFormulaOptions } from './utils';
 export { UndoRedoStack } from './utils';
 export { validateColumns, validateRowIds, validateVirtualScrollConfig } from './utils';
+export { indexToColumnLetter, formatCellReference } from './utils';
+export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown } from './utils';
+export type { FormulaReference } from './utils';
 export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './constants';
 export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './constants';
 export { Z_INDEX } from './constants';
 export type { ZIndexKey } from './constants';
+export { FORMULA_REF_COLORS, FORMULA_BAR_CSS, FORMULA_BAR_STYLES } from './constants';
+export { FormulaError, FormulaEngine, FormulaEvaluator, DependencyGraph, tokenize, parse, createBuiltInFunctions, columnLetterToIndex, parseCellRef, parseRange, formatAddress, toCellKey, fromCellKey, adjustFormulaReferences, toNumber, toString as formulaToString, toBoolean, flattenArgs, isFormulaError, REF_ERROR, DIV_ZERO_ERROR, VALUE_ERROR, NAME_ERROR, CIRC_ERROR, GENERAL_ERROR, NA_ERROR, } from './formula';
+export type { ICellAddress, ICellRange, CellKey, FormulaErrorType, TokenType, Token, ASTNode, BinaryOp, IFormulaContext, IFormulaFunction, IEvaluator, IRecalcResult, IFormulaEngineConfig, IGridDataAccessor, INamedRange, IAuditEntry, IAuditTrail, } from './formula';

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

@@ -69,6 +69,8 @@ export interface ICellValueChangedEvent<T> {
     oldValue: unknown;
     newValue: unknown;
     rowIndex: number;
+    /** True when the newValue was produced by the formula engine (not a direct user edit). */
+    isFormulaResult?: boolean;
 }
 /** Props passed to custom cell editor components. */
 export interface ICellEditorProps<T> {

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

@@ -128,6 +128,13 @@ export interface ISideBarDef {
     /** Position of the side bar (default: 'right'). */
     position?: 'left' | 'right';
 }
+/** Definition for a sheet tab. */
+export interface ISheetDef {
+    id: string;
+    name: string;
+    /** Optional tab color (CSS value). */
+    color?: string;
+}
 /** Configuration for virtual scrolling. */
 export interface IVirtualScrollConfig {
     /** Enable virtual scrolling (default: false). */

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

@@ -1,3 +1,3 @@
 export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, IColumnDef, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } 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 './dataGridTypes';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, ISheetDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './dataGridTypes';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './dataGridTypes';