@alaarab/ogrid-core 2.2.0 → 2.3.0

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/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/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,139 @@
+/**
+ * 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;
+}
+/** 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

@@ -2,7 +2,7 @@ export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta,
 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 { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './types';
 export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';
-export type { CsvColumn } from './utils';
+export type { CsvColumn, FormulaExportOptions } from './utils';
 export { getCellValue, isColumnEditable } from './utils';
 export { flattenColumns, buildHeaderRows } from './utils';
 export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './utils';
@@ -39,9 +39,13 @@ 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 { 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 { 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/utils/cellReference.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Excel-style cell reference utilities.
+ *
+ * Column letters use base-26 encoding: A–Z, AA–AZ, BA–BZ, …
+ * Row numbers are 1-based.
+ */
+/**
+ * Convert a 0-based column index to an Excel-style column letter.
+ * @example indexToColumnLetter(0)   // 'A'
+ * @example indexToColumnLetter(25)  // 'Z'
+ * @example indexToColumnLetter(26)  // 'AA'
+ * @example indexToColumnLetter(702) // 'AAA'
+ */
+export declare function indexToColumnLetter(index: number): string;
+/**
+ * Format a cell reference string from a 0-based column index and a 1-based row number.
+ * @example formatCellReference(0, 1)    // 'A1'
+ * @example formatCellReference(2, 15)   // 'C15'
+ * @example formatCellReference(26, 100) // 'AA100'
+ */
+export declare function formatCellReference(colIndex: number, rowNumber: number): string;

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

@@ -20,9 +20,17 @@ export declare function formatCellValueForTsv(raw: unknown, formatted: unknown):
  * @param items       Flat array of all row data objects.
  * @param visibleCols Visible column definitions.
  * @param range       The selection range to serialize (will be normalized).
+ * @param formulaOptions  Optional formula-aware options. When provided, cells with
+ *                        formulas will have their formula string copied instead of
+ *                        the computed value.
  * @returns TSV string with rows separated by \\r\\n and columns by \\t.
  */
-export declare function formatSelectionAsTsv<T>(items: T[], visibleCols: IColumnDef<T>[], range: ISelectionRange): string;
+export declare function formatSelectionAsTsv<T>(items: T[], visibleCols: IColumnDef<T>[], range: ISelectionRange, formulaOptions?: {
+    colOffset: number;
+    flatColumns: IColumnDef<T>[];
+    getFormula?: (col: number, row: number) => string | undefined;
+    hasFormula?: (col: number, row: number) => boolean;
+}): string;
 /**
  * Parse a TSV clipboard string into a 2D array of cell strings.
  * Handles both \\r\\n and \\n line endings. Ignores trailing empty lines.
@@ -36,14 +44,22 @@ export declare function parseTsvClipboard(text: string): string[][];
  * For each cell in the parsed rows, validates editability, parses the value,
  * and produces a cell value changed event.
  *
+ * When `formulaOptions` is provided, cells whose pasted text starts with "="
+ * are routed through `setFormula` instead of the normal value parse path.
+ *
  * @param parsedRows   2D array of string values (from parseTsvClipboard).
  * @param anchorRow    Target starting row index.
  * @param anchorCol    Target starting column index (data column, not absolute).
  * @param items        Array of all row data objects.
  * @param visibleCols  Visible column definitions.
+ * @param formulaOptions  Optional formula-aware options.
  * @returns Array of cell value changed events to apply.
  */
-export declare function applyPastedValues<T>(parsedRows: string[][], anchorRow: number, anchorCol: number, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];
+export declare function applyPastedValues<T>(parsedRows: string[][], anchorRow: number, anchorCol: number, items: T[], visibleCols: IColumnDef<T>[], formulaOptions?: {
+    colOffset: number;
+    flatColumns: IColumnDef<T>[];
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+}): ICellValueChangedEvent<T>[];
 /**
  * Clear cells in a cut range by setting each editable cell to an empty-string-parsed value.
  * Used after pasting cut content to clear the original cells.

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

@@ -181,8 +181,9 @@ export declare function getCellRenderDescriptor<T>(item: T, col: IColumnDef<T>,
 export declare function resolveCellDisplayContent<T>(col: IColumnDef<T>, item: T, displayValue: unknown): unknown;
 /**
  * Resolves the cellStyle from a column def, handling both function and static values.
+ * When displayValue is a FormulaError, merges red error color styling.
  */
-export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T): Record<string, string> | undefined;
+export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T, displayValue?: unknown): Record<string, string> | undefined;
 /**
  * Builds props for InlineCellEditor. Shared across all UI packages.
  */

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

@@ -4,8 +4,16 @@ export interface CsvColumn {
 }
 export declare function escapeCsvValue(value: unknown): string;
 export declare function buildCsvHeader(columns: CsvColumn[]): string;
-export declare function buildCsvRows<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string): string[];
-export declare function exportToCsv<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string, filename?: string): void;
+export interface FormulaExportOptions {
+    getFormula?: (col: number, row: number) => string | undefined;
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Map from columnId to flat column index */
+    columnIdToIndex?: Map<string, number>;
+    /** Export mode: 'values' (default) exports computed results, 'formulas' exports formula strings */
+    exportMode?: 'values' | 'formulas';
+}
+export declare function buildCsvRows<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => unknown, formulaOptions?: FormulaExportOptions): string[];
+export declare function exportToCsv<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => unknown, filename?: string, formulaOptions?: FormulaExportOptions): void;
 /**
  * Triggers a browser CSV file download.
  *