/**
 * Value model and error values for the formula engine.
 *
 * Spreadsheet-style error values (`#REF!`, `#DIV/0!`, ...) are first-class cell
 * values: they are produced by evaluation, propagate through operators and
 * functions, and render as their code text in the grid. Because a
 * {@link FormulaError} is not a `number`, it is naturally excluded from numeric
 * aggregates (sum/average), matching the aggregation engine.
 *
 * This module is pure (no DOM, no grid knowledge) and sits at the bottom of the
 * engine: every other formula module depends on the value model defined here.
 */
/** The spreadsheet error codes the engine can produce. */
export type FormulaErrorCode = '#REF!' | '#NAME?' | '#DIV/0!' | '#VALUE!' | '#CYCLE!';
/**
 * A spreadsheet error value. Carries the user-facing {@link FormulaErrorCode}
 * (the text shown in the cell) and an optional internal detail message for
 * debugging. Instances are immutable.
 */
export declare class FormulaError {
    readonly code: FormulaErrorCode;
    readonly detail?: string | undefined;
    constructor(code: FormulaErrorCode, detail?: string | undefined);
    /** Renders as the error code, so the default cell renderer shows e.g. `#DIV/0!`. */
    toString(): string;
}
/** A value a formula cell can hold: the evaluated result or an error value. */
export type CellValue = number | string | boolean | null | FormulaError;
/** `#REF!` — a reference points outside the grid (unknown row/column). */
export declare const refError: (detail?: string) => FormulaError;
/** `#NAME?` — an unknown function name. */
export declare const nameError: (detail?: string) => FormulaError;
/** `#DIV/0!` — division (or modulo) by zero. */
export declare const divZeroError: (detail?: string) => FormulaError;
/** `#VALUE!` — a type error (e.g. arithmetic on non-numeric text). */
export declare const valueError: (detail?: string) => FormulaError;
/** `#CYCLE!` — the cell participates in a circular reference (raised by recalc). */
export declare const cycleError: (detail?: string) => FormulaError;
/** Type guard: is the value a {@link FormulaError}? */
export declare function isFormulaError(value: unknown): value is FormulaError;
/**
 * Returns the first {@link FormulaError} found in `values`, or `undefined`.
 * Used by functions and operators to propagate errors: an error operand yields
 * the same error, the spreadsheet convention.
 */
export declare function firstError(values: readonly CellValue[]): FormulaError | undefined;
/**
 * Thrown by `parseFormula` when the input is not a well-formed formula. Carries
 * the 0-based character {@link position} of the offending token so the editor
 * can point at it.
 */
export declare class ParseError extends Error {
    readonly position: number;
    constructor(message: string, position: number);
}
/**
 * Coerce a value to a number for arithmetic. Booleans map to `1`/`0`, numeric
 * strings parse, empty/`null` is `0`; anything else is a `#VALUE!` error. Errors
 * pass through unchanged so they propagate.
 */
export declare function toNumber(value: CellValue): number | FormulaError;
/**
 * Coerce a value to a boolean for logical functions. Numbers are truthy when
 * non-zero, the strings `TRUE`/`FALSE` (any case) map accordingly; `null` is
 * `false`. Other strings are a `#VALUE!` error. Errors pass through.
 */
export declare function toBoolean(value: CellValue): boolean | FormulaError;
/**
 * Coerce a value to its string form for text concatenation. `null` is the empty
 * string, booleans become `TRUE`/`FALSE`. Errors pass through.
 */
export declare function toText(value: CellValue): string | FormulaError;