@gui-chat-plugin/spreadsheet 2.0.0 → 2.1.0

package/dist/engine/calculator.d.ts

@@ -3,7 +3,18 @@
  *
  * Core calculation engine with circular reference detection and cross-sheet support
  */
-import type { SheetData, CalculatedSheet } from "./types";
+import type { SheetData, CalculatedSheet, SpreadsheetCell, CalculateOptions } from "./types";
+/**
+ * Normalize malformed data structures
+ * Some models generate flat arrays instead of 2D arrays - fix them
+ *
+ * @param data - Potentially malformed sheet data
+ * @returns Normalized 2D array
+ */
+export declare function normalizeData(data: any): SpreadsheetCell[][];
+type SheetCalculateOptions = CalculateOptions & {
+    skipFormatting?: boolean;
+};
 /**
  * Calculate formulas in a single sheet
  *
@@ -11,11 +22,12 @@ import type { SheetData, CalculatedSheet } from "./types";
  * @param allSheets - All sheets for cross-sheet references
  * @returns Calculated sheet with formulas evaluated
  */
-export declare function calculateSheet(sheet: SheetData, allSheets?: SheetData[]): CalculatedSheet;
+export declare function calculateSheet(sheet: SheetData, allSheets?: SheetData[], options?: SheetCalculateOptions): CalculatedSheet;
 /**
  * Calculate all sheets in a workbook
  *
  * @param sheets - Array of sheets to calculate
  * @returns Array of calculated sheets
  */
-export declare function calculateWorkbook(sheets: SheetData[]): CalculatedSheet[];
+export declare function calculateWorkbook(sheets: SheetData[], options?: CalculateOptions): CalculatedSheet[];
+export {};

package/dist/engine/cellBuilder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Build a SpreadsheetCell from the raw input captured by the mini
+ * editor (type + value / formula / format). Extracted from
+ * `saveMiniEditor` in `src/plugins/spreadsheet/View.vue` where it
+ * was inlined as ~30 lines of nested if/else that pushed the
+ * surrounding function over the cognitive-complexity threshold.
+ *
+ * Pure — no refs, no DOM, no side effects. Given the same inputs
+ * it always returns the same SpreadsheetCell. Tested in
+ * `test/plugins/spreadsheet/engine/test_cellBuilder.ts`.
+ */
+import type { SpreadsheetCell } from "./types.js";
+/** Inputs to the cell builder. Mirrors the mini editor refs in the
+ *  View but as plain values so unit tests don't need a Vue runtime. */
+export interface MiniEditorInput {
+    /** "string" → value is stored as-is as a string.
+     *  Anything else → the `formula` field is parsed (formula / number / raw string). */
+    type: string;
+    /** Used when type === "string". Coerced to string. */
+    value: unknown;
+    /** Used when type !== "string". Trimmed before classification. */
+    formula?: string;
+    /** Optional format code (e.g. "$#,##0.00"). */
+    format?: string;
+}
+/**
+ * Best-effort formula detection. The rules are conservative enough
+ * that plain text like "hello world" stays as text, but any input
+ * with arithmetic operators or function calls is treated as a
+ * formula and gets the "=" prefix the engine expects.
+ */
+export declare function looksLikeFormula(input: string): boolean;
+/**
+ * Parse the raw (non-string-type) editor input into a cell value.
+ * Priority: formula > number > raw string > empty string.
+ */
+export declare function parseNonStringInput(raw: string): number | string;
+/**
+ * Build the full SpreadsheetCell from a mini editor input record.
+ * String type short-circuits to `{ v: String(value) }`.
+ * Everything else goes through parseNonStringInput for formula /
+ * number / text classification, then optionally attaches `f`.
+ */
+export declare function buildCellFromInput(input: MiniEditorInput): SpreadsheetCell;

package/dist/engine/cellEmpty.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Telling a genuinely empty cell apart from one that holds the number 0.
+ *
+ * The calculator reads a blank cell as 0 for arithmetic (`=A1+1` on a blank A1
+ * is 1, as in Excel). But an aggregate must not: `AVERAGE` divides by the count
+ * of real values, and `COUNT` counts numbers — a blank that reads as 0 inflates
+ * the denominator and the count. So range collection needs to skip the blanks,
+ * which means distinguishing them from a stored 0, which this does.
+ */
+/** True when a cell holds no value at all — absent, null, or an empty/whitespace
+ *  string, in either the bare or the `{ v }` form. A cell containing the number
+ *  0, `false`, or any non-empty text is NOT empty. */
+export declare function isEmptyCell(cell: unknown): boolean;

package/dist/engine/cellFormatting.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cell display formatting
+ *
+ * Turns a cell's raw calculated value into its display value (currency,
+ * percentage, date, ...). Pure — no engine state — so cross-sheet reference
+ * resolution can deliberately SKIP it and keep raw serial numbers, while the
+ * final output pass applies it for presentation.
+ */
+import type { CellValue, StoredCellValue } from "./types";
+/** An integer within the date-serial window — a calculated number the engine
+ *  should display as a date when the cell carries no explicit format. */
+export declare const isLikelyDateSerial: (value: CellValue) => boolean;
+/**
+ * Resolve the display value of one cell from its original definition and its
+ * calculated value.
+ *
+ * - A formula error renders as its code, so the cell still reads `#NUM!`.
+ * - Explicit format code wins (currency, percentage, date, ...).
+ * - A formula that produced a date serial auto-formats as a date.
+ * - Everything else (text, plain numbers, empty) passes through unchanged.
+ *
+ * The result is always a STORED value: this is the boundary where a computed
+ * error becomes the text a cell shows and a workbook serializes.
+ */
+export declare const formatCellForDisplay: (originalCell: unknown, calculatedValue: CellValue, preferDDMMYYYY: boolean) => StoredCellValue;

package/dist/engine/coerce-boolean.d.ts

@@ -0,0 +1,7 @@
+import type { CellValue } from "./types";
+/** Excel-style truthiness, shared by IF and AND/OR/NOT so the same value cannot
+ *  read as true in one function and false in another. A number is false only
+ *  when 0; blank and empty text are false; the words `true`/`false` are their
+ *  logical values (case-insensitively); a numeric string follows its number
+ *  (`"0"` → false); any other non-empty text is true. */
+export declare function coerceToBoolean(value: CellValue | null | undefined): boolean;

package/dist/engine/condition.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Evaluating a spreadsheet condition without running it as code.
+ *
+ * A condition is one comparison, or a bare value tested for truthiness. That is
+ * the whole grammar — small enough to read directly, which is the point: the
+ * previous implementation handed the substituted text to `eval`, so a cell
+ * containing `globalThis.x = 1` executed when any IFS referenced it.
+ */
+import type { CellValue } from "./types";
+export type ComparisonOperator = ">=" | "<=" | "<>" | "!=" | "==" | "=" | ">" | "<";
+export interface Comparison {
+    left: string;
+    operator: ComparisonOperator;
+    right: string;
+}
+/** Remove parentheses that wrap the WHOLE expression, repeatedly. `(1>0)` is
+ *  the same condition as `1>0`, but `(A)=(B)` is not `A)=(B` — the leading `(`
+ *  closes before the end, so it wraps only its own operand and must stay.
+ *  Unbalanced input is left untouched rather than guessed at. */
+export declare function stripOuterParens(condition: string): string;
+/** Split a condition into its two sides, or null when it holds no comparison.
+ *  Only the FIRST top-level operator counts — `a>b>c` is not a chain here, and
+ *  treating it as one is what let `1=1=1` reach a JS parser before.
+ *
+ *  "Top-level" means outside quotes: a cell holding `a>b` substitutes into the
+ *  condition as `"a>b"`, and splitting on that `>` would compare two fragments
+ *  of one string literal. */
+export declare function splitComparison(condition: string): Comparison | null;
+/** Read an operand as the value it denotes: a quoted string stays text, a
+ *  numeric literal becomes a number, `TRUE`/`FALSE` become booleans, and
+ *  anything else stays the text it already is. */
+export declare function readOperand(raw: string): CellValue;
+/** True when a bare (non-comparison) condition counts as satisfied. */
+export declare function isTruthyCondition(raw: string): boolean;
+/** Evaluate a condition — one comparison, or a value tested for truthiness.
+ *  Never executes its input. */
+export declare function evaluateCondition(condition: string): boolean;
+/** Like `evaluateCondition`, but each operand is resolved by `evaluate` — so a
+ *  caller holding the engine can compute arithmetic and sub-expressions
+ *  (`5+1>10`) instead of reading each side as a bare string. It still never runs
+ *  the condition as code: it only splits on the top-level comparison and
+ *  compares the two resolved values. */
+export declare function evaluateConditionValues(condition: string, evaluate: (operand: string) => CellValue): boolean;
+/** Render a cell's value as an operand for a condition string. A string is
+ *  quoted, with its own quotes and backslashes escaped, so its contents cannot
+ *  be re-parsed as operators — `evaluateCondition` then unquotes it back to the
+ *  original text. A missing value becomes an empty string; numbers and booleans
+ *  render as themselves. */
+export declare function renderConditionOperand(value: CellValue | null | undefined): string;

package/dist/engine/date-locale.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Which order an ambiguous slash date is written in, per locale.
+ *
+ * Only dates whose two leading numbers are BOTH 12 or under are ambiguous —
+ * `13/04/2025` can only be day-first, and `04/13/2025` can only be month-first,
+ * so those decide themselves. This is purely about `03/04/2025`.
+ */
+/** True when an ambiguous `A/B/YYYY` should read as day-first. Accepts a full
+ *  BCP 47 tag or a bare language subtag; the region is used when present so a
+ *  caller that can supply `en-GB` gets the right answer even though the app's
+ *  own locale resolution discards it. */
+export declare function prefersDayFirst(locale: string | undefined | null): boolean;

package/dist/engine/date-parser.d.ts

@@ -10,6 +10,12 @@
  * @returns true if string matches common date patterns
  */
 export declare function isDateLike(str: string): boolean;
+/**
+ * Build the Excel serial number for a year/month/day triple, or null when the
+ * triple is not a valid calendar date. Every dated branch of `parseDate` ends in
+ * this same validate → Date.UTC → dateToSerial step.
+ */
+export declare function serialFromParts(year: number, month: number, day: number): number | null;
 /**
  * Parse a date string into Excel serial number
  *
@@ -31,4 +37,4 @@ export declare function parseDate(dateStr: string, preferDDMMYYYY?: boolean): nu
  * @param originalStr - Original date string
  * @returns Appropriate format code
  */
-export declare function getDefaultDateFormat(originalStr: string): string;
+export declare function getDefaultDateFormat(originalStr: string, preferDDMMYYYY?: boolean): string;

package/dist/engine/date-utils.d.ts

@@ -19,13 +19,16 @@ export declare const dateToSerial: (date: Date) => number;
  * @returns JavaScript Date object
  */
 export declare const serialToDate: (serial: number) => Date;
+/** A name list that always has a first entry, so a formatter can fall back to it
+ *  when a date is unreadable and its month/weekday index comes out NaN. */
+export type NameList = readonly [string, ...string[]];
 /**
  * Month names for formatting
  */
-export declare const MONTH_NAMES_SHORT: string[];
-export declare const MONTH_NAMES_FULL: string[];
+export declare const MONTH_NAMES_SHORT: NameList;
+export declare const MONTH_NAMES_FULL: NameList;
 /**
  * Day names for formatting
  */
-export declare const DAY_NAMES_SHORT: string[];
-export declare const DAY_NAMES_FULL: string[];
+export declare const DAY_NAMES_SHORT: NameList;
+export declare const DAY_NAMES_FULL: NameList;

package/dist/engine/datedif.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DATEDIF — complete elapsed time between two dates, in a chosen unit.
+ *
+ * Pure: two Excel serials and a unit in, a number (or a formula error value)
+ * out. The unit branches each have their own boundary handling (month-end
+ * borrowing, year wraparound), which is exactly what makes them worth testing
+ * apart from the handler that reads the arguments.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** Complete `unit`s between two dates, or `#NUM!` when start is after end or
+ *  the unit is not one of Y / M / D / MD / YM / YD. `unit` is matched
+ *  case-insensitively. */
+export declare function computeDatedif(startSerial: number, endSerial: number, unit: string): number | SpreadsheetError;

package/dist/engine/evaluator.d.ts

@@ -10,9 +10,48 @@ import type { CellValue } from "./types";
 export interface EvaluatorContext {
     getCellValue: (ref: string) => CellValue;
     getRangeValues: (range: string) => CellValue[];
-    getRangeValuesRaw?: (range: string) => CellValue[];
+    getRangeValuesRaw?: ((range: string) => CellValue[]) | undefined;
     evaluateFormula: (formula: string) => CellValue;
+    /** Reading order for an ambiguous slash date; see engine/date-locale.ts. */
+    preferDDMMYYYY?: boolean | undefined;
 }
+/** Render a cell's value as the text that stands in for it inside an
+ *  expression. Strings are quoted so they cannot be read as identifiers or
+ *  operators, and their own quotes and backslashes are escaped so the literal
+ *  cannot be closed early. A missing value becomes 0, matching how blanks are
+ *  treated everywhere else in the engine. */
+export declare function renderOperand(value: CellValue | null | undefined): string;
+/** Replace every quoted string literal with an empty pair of quotes, honouring
+ *  `\` escapes so an escaped quote does not end the literal early. Used to
+ *  validate the STRUCTURE of a concat/arithmetic expression without letting the
+ *  arbitrary CONTENT of a string decide whether the whole thing looks safe. */
+export declare function maskStringLiterals(expr: string): string;
+/** Whether a `&`-to-`+` concatenation expression is safe to evaluate. Checks the
+ *  structure with string CONTENT masked out — a string literal may hold any
+ *  character (a `!`, a `\`), and validating those against a character allowlist
+ *  rejected valid formulas like `=A1&"!"` and every escaped operand. Once the
+ *  literals are masked, only the joining structure remains to validate. */
+export declare function isSafeConcatExpression(expr: string): boolean;
+/** Index just past the string literal that opens at `start` (a quote char),
+ *  honouring `\` escapes so an escaped quote does not close it early. Returns
+ *  `expr.length` when the literal is never closed. */
+export declare function endOfStringLiteral(expr: string, start: number): number;
+/** Every cell reference in an expression, as `{ref, start}` spans in source
+ *  order. Quoted string literals are skipped whole: a `"A1"` in the text is a
+ *  constant, not a reference, and substituting it would turn `="A1"&"!"` into
+ *  A1's value. A `'` opens either a `'Sheet'!A1` reference or a string literal —
+ *  only the former is a reference; the latter is skipped like a `"` literal. */
+export interface CellRefSpan {
+    ref: string;
+    start: number;
+}
+export declare function findCellRefs(expr: string): CellRefSpan[];
+/** Replace every reference span in `expr` with the text `render` gives for it,
+ *  walking BACK TO FRONT so the spans ahead of each edit stay valid. A global
+ *  string replace rewrote every occurrence of the shorter reference first, so
+ *  `=A1+A10` had its `A10` broken into `<A1's value>0` and produced a plausible
+ *  wrong number (#2357). */
+export declare function substituteCellRefs(expr: string, cellRefs: CellRefSpan[], render: (ref: string) => string): string;
 /**
  * Parse function arguments, handling nested functions and quoted strings
  *
@@ -29,6 +68,10 @@ export declare function parseFunctionArgs(argsStr: string): string[];
  * - Arithmetic: 2+3, A1*B1, (A1+B1)/2
  * - Nested expressions: ROUND(SUM(A1:A10)/COUNT(A1:A10), 2)
  *
+ * A genuine failure THROWS (a typed FormulaError or any handler error) rather
+ * than returning the raw formula text; the calculator classifies it into
+ * errors[] and shows the Excel error value in the cell (#2359).
+ *
  * @param formula - Formula string (without leading =)
  * @param context - Evaluation context with cell/range accessors
  * @returns Evaluated result (number or string)

package/dist/engine/financial-math.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Annuity math for the financial functions, as pure numeric helpers.
+ *
+ * Excel's cash-flow sign convention: money received is positive, money paid out
+ * is negative — so a loan's `pv` is positive and its payment and interest come
+ * back negative. Keeping the per-period split as plain number-in / number-out
+ * functions lets it be tested against known Excel values without routing string
+ * arguments back through the formula evaluator.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** Future value after `nper` periods. `type` is 0 (end of period) or 1 (begin). */
+export declare function computeFv(rate: number, nper: number, pmt: number, pv: number, type: number): number;
+/** Constant per-period payment amortising a present value `pv` to `fv`. */
+export declare function computePmt(rate: number, nper: number, pv: number, fv: number, type: number): number;
+/** Interest portion of the `per`-th payment. */
+export declare function computeIpmt(rate: number, per: number, nper: number, pv: number, fv: number, type: number): number;
+/** Principal portion of the `per`-th payment (total payment minus interest). */
+export declare function computePpmt(rate: number, per: number, nper: number, pv: number, fv: number, type: number): number;
+/** Present value of an annuity that grows to `fv` after `nper` payments of `pmt`. */
+export declare function computePv(rate: number, nper: number, pmt: number, fv: number, type: number): number;
+/** Number of periods needed to amortise `pv` to `fv` at constant `pmt`. */
+export declare function computeNper(rate: number, pmt: number, pv: number, fv: number, type: number): number;
+/** Interest rate per period solving the annuity equation, via Newton-Raphson. */
+export declare function computeRate(nper: number, pmt: number, pv: number, fv: number, type: number, guess: number): number | SpreadsheetError;
+/** Net present value of `cashflows`, each discounted one period further into the future. */
+export declare function computeNpv(rate: number, cashflows: number[]): number;
+/** Internal rate of return of `values` (element 0 at period 0), via Newton-Raphson. */
+export declare function computeIrr(values: number[], guess: number): number | SpreadsheetError;

package/dist/engine/formatter.d.ts

@@ -3,6 +3,15 @@
  *
  * Handles Excel-style format codes for currency, percentages, decimals, dates, etc.
  */
+/**
+ * Insert thousands separators into a run of digits ("1234567" → "1,234,567").
+ * Regex free on purpose: the classic `\B(?=(\d{3})+(?!\d))` lookahead
+ * backtracks badly on a long run of digits.
+ */
+export declare const groupThousands: (digits: string) => string;
+/** Group the integer part of a formatted number ("1234567.89" → "1,234,567.89"),
+ *  leaving any fractional part after the decimal point untouched. */
+export declare const addThousandSeparators: (formatted: string) => string;
 /**
  * Format a number according to Excel format code
  *

package/dist/engine/formulaError.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed formula-evaluation errors
+ *
+ * A failed formula must surface as a typed error with an Excel-style error value
+ * in the cell, never as a swallowed bare string (issue #2359). This module holds
+ * the error taxonomy, the throwable carrier, and the pure helpers that classify a
+ * thrown error and propagate an error value across cell references. No engine
+ * state is captured — every export is input → output only.
+ */
+import type { CalculationError } from "./types";
+import type { SpreadsheetErrorCode } from "./spreadsheet-errors";
+/** The evaluator-facing error kinds: every `CalculationError["type"]` except
+ *  `circular`, which the calculator raises directly (not via a thrown error). */
+export type FormulaErrorType = Exclude<CalculationError["type"], "circular">;
+/** The error code shown for each kind, matching Excel's error literals. */
+export declare const FORMULA_ERROR_VALUES: Record<FormulaErrorType, SpreadsheetErrorCode>;
+/** A recoverable formula failure carrying the kind and the code to show. */
+export declare class FormulaError extends Error {
+    readonly errorType: FormulaErrorType;
+    readonly display: SpreadsheetErrorCode;
+    constructor(errorType: FormulaErrorType, display: SpreadsheetErrorCode, message?: string);
+}
+export declare const isFormulaError: (error: unknown) => error is FormulaError;
+export declare const divZeroError: () => FormulaError;
+export declare const invalidRefError: (ref: string) => FormulaError;
+export declare const nameError: (funcName: string) => FormulaError;
+export declare const unknownError: (message?: string) => FormulaError;
+/** The FormulaError that re-raises an error read from a referenced cell or a
+ *  nested call, so `=A1+1` inherits A1's error instead of corrupting into
+ *  `"#DIV/0!"+1`. */
+export declare const propagatedError: (value: SpreadsheetErrorCode) => FormulaError;
+/** Map any thrown value onto the typed entry the calculator records. A
+ *  `FormulaError` keeps its own kind and display; anything else is `unknown`. */
+export declare const classifyThrownError: (error: unknown) => {
+    type: FormulaErrorType;
+    display: SpreadsheetErrorCode;
+};

package/dist/engine/formulaRefs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Extract the set of cells that a formula references.
+ *
+ * Extracted from `src/plugins/spreadsheet/View.vue` (was the body of
+ * `extractCellReferences`, cognitive complexity 32). The original
+ * function combined regex scanning, range expansion, single-cell
+ * parsing, and deduplication all in one body; splitting each concern
+ * into a named helper brings the top-level function well under the
+ * sonarjs/cognitive-complexity threshold of 15 and makes the pure
+ * logic unit-testable in isolation (see
+ * `test/plugins/spreadsheet/engine/test_formulaRefs.ts`).
+ *
+ * Tracks #175. No behavioural change — the wrapper in View.vue
+ * still returns exactly the same `{ row, col }` list as before.
+ */
+export interface CellCoord {
+    row: number;
+    col: number;
+}
+export declare function stripFormulaPrefix(formula: string): string;
+export declare function expandRange(rangeStr: string): CellCoord[];
+export declare function expandRangeOrCell(ref: string): CellCoord[] | null;
+export declare function parseSingleCellRef(refStr: string): CellCoord | null;
+export interface RangeBounds {
+    sheetPrefix: string;
+    startCol: number;
+    startRow: number;
+    endCol: number;
+    endRow: number;
+}
+export declare function parseRangeBounds(range: string): RangeBounds | null;
+export declare function resolveIndexTarget(bounds: RangeBounds, rowNum: number, colNum: number): {
+    colIndex: number;
+    row: number;
+} | null;
+export declare function resolveTableOffset(position: number, size: number): number | null;
+export declare function extractCellReferences(formula: string): CellCoord[];

package/dist/engine/functions/lookup-math.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure lookup rules, separated from the range-reading handlers so they can be
+ * unit-tested directly.
+ */
+import type { CellValue } from "../types";
+/**
+ * Interpret VLOOKUP/HLOOKUP's 4th argument (range_lookup): TRUE (or omitted) =
+ * approximate match, FALSE = exact.
+ *
+ * The literal `TRUE` reaches the handler as the STRING `"TRUE"` — the evaluator
+ * leaves bare words unquoted — so an accept-only-`true | 1 | "1"` check silently
+ * fell back to exact match and returned `#N/A` for a valid approximate lookup
+ * (#2360). Read it the way Excel coerces a logical instead: a boolean as-is, a
+ * non-zero number as TRUE, and the words `TRUE` / `FALSE` (case-insensitive)
+ * and `"1"` / `"0"` as their logical value. Anything else (blank, stray text)
+ * is treated as FALSE, matching Excel's coercion of a blank range_lookup — and
+ * so is a formula error, which is neither of the two logicals.
+ */
+export declare function isApproximateMatch(rangeLookup: CellValue): boolean;

package/dist/engine/functions/statistical-math.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure statistical rules, separated from the range-reading handlers so they can
+ * be unit-tested directly.
+ */
+import { type SpreadsheetError } from "../spreadsheet-errors";
+/**
+ * The arithmetic mean, or `#DIV/0!` when there is nothing to average.
+ *
+ * Excel divides by the count of NUMBERS, so a range of blanks or text leaves a
+ * zero denominator and reports the division rather than a 0 that reads like a
+ * genuine average of zeros.
+ */
+export declare function computeAverage(values: number[]): number | SpreadsheetError;
+/**
+ * The middle value (the mean of the middle two when the count is even), or
+ * `#NUM!` when there is no value to sit in the middle.
+ *
+ * Excel's code here is `#NUM!`, not AVERAGE's `#DIV/0!` — nothing is divided by
+ * zero, the median of an empty set simply does not exist. Sorts a copy so the
+ * caller's array keeps its order.
+ */
+export declare function computeMedian(values: number[]): number | SpreadsheetError;
+/**
+ * The most frequently occurring value, or `#N/A` when no value repeats.
+ *
+ * Excel's MODE is undefined for an all-distinct set, so returning the first
+ * element (as a naive "highest frequency wins" loop does when every count is 1)
+ * is a silent wrong answer. Ties resolve to the value that appears first, which
+ * Map insertion order preserves.
+ */
+export declare function computeMode(values: number[]): number | SpreadsheetError;
+/**
+ * Sample variance (Excel VAR): the mean squared deviation divided by `n - 1`,
+ * not `n`. Dividing by `n` is the POPULATION variance (Excel's VARP); using it
+ * for VAR understates the spread. Fewer than two values leave no `n - 1` to
+ * divide by, so Excel reports `#DIV/0!` rather than a silent 0.
+ */
+export declare function sampleVariance(values: number[]): number | SpreadsheetError;
+/** Sample standard deviation (Excel STDEV): the square root of the sample
+ *  variance, and `#DIV/0!` on the same fewer-than-two-values boundary. */
+export declare function sampleStdev(values: number[]): number | SpreadsheetError;

package/dist/engine/functions/text.d.ts

@@ -1,4 +1,20 @@
 /**
  * Text Functions
  */
-export {};
+import { type SpreadsheetError } from "../spreadsheet-errors";
+export declare const toProperCase: (text: string) => string;
+export declare const takeLeft: (text: string, count: number) => string | SpreadsheetError;
+export declare const takeRight: (text: string, count: number) => string | SpreadsheetError;
+export declare const substituteText: (text: string, oldText: string, newText: string, instance?: number) => string | SpreadsheetError;
+/** Excel MID: 1-based start, count of characters. `substring` SWAPS its bounds
+ *  when they are reversed, so a negative count read backwards from `start` and
+ *  returned earlier characters — `MID("Hello",3,-1)` gave "e" instead of an
+ *  error. Both arguments are validated here instead. */
+export declare const takeMid: (text: string, start: number, count: number) => string | SpreadsheetError;
+export declare const locateSubstring: (find: string, within: string, start: number, options: {
+    caseInsensitive: boolean;
+}) => number | SpreadsheetError;
+/** Excel VALUE: the WHOLE string must be a number once its currency symbols and
+ *  thousands separators are stripped; trailing text is an error, not a prefix to
+ *  salvage. */
+export declare const parseValueText: (raw: string) => number | SpreadsheetError;

package/dist/engine/guards.d.ts

@@ -0,0 +1,10 @@
+/** Narrow `unknown` to a plain object (not null, not array). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow `unknown` to any object (not null, arrays allowed).
+ *  Use `isRecord` when you need to access string keys. */
+export declare function isObj(value: unknown): value is object;
+/** The message to show for a thrown value. A non-Error object with a non-empty
+ *  string `details` (the gRPC convention) or `message` surfaces that field —
+ *  `details` wins — instead of the `[object Object]` a bare `String(err)`
+ *  would print. */
+export declare function errorMessage(err: unknown, fallback?: string): string;

package/dist/engine/index.d.ts

@@ -5,9 +5,20 @@
  */
 export * from "./types";
 export * from "./parser";
+export * from "./condition";
+export * from "./date-locale";
+export * from "./cellEmpty";
+export * from "./datedif";
 export * from "./formatter";
+export * from "./translateFormula";
+export * from "./formulaError";
+export * from "./spreadsheet-errors";
 export * from "./evaluator";
 export * from "./calculator";
+export * from "./formulaRefs";
+export * from "./cellBuilder";
+export * from "./responseDecoder";
+export * from "./jsonCellLocator";
 export * from "./registry";
 import "./functions";
 export { SpreadsheetEngine } from "./engine";

package/dist/engine/jsonCellLocator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Locate the start offset of a specific cell value inside a
+ * pretty-printed JSON spreadsheet document. Extracted from
+ * `handleTableClick` in `src/plugins/spreadsheet/View.vue` where the
+ * inline scanner pushed cognitive complexity to 163.
+ *
+ * The scanner walks the raw editor text character-by-character,
+ * tracking string boundaries, bracket depth, and object depth to
+ * find the n-th cell of the m-th row within a named sheet's `data`
+ * array. We deliberately do NOT parse the JSON — we need the
+ * character offset inside the user's text buffer (which may not be
+ * valid JSON mid-edit), so a positional scan is required.
+ *
+ * Pure — no refs, no DOM. Returns -1 if the cell can't be located.
+ * Tested in `test/plugins/spreadsheet/engine/test_jsonCellLocator.ts`.
+ */
+/**
+ * Given the pretty-printed JSON editor text, a sheet name, and
+ * (rowIndex, colIndex), return the character offset of that cell's
+ * JSON token. The returned offset can be fed into
+ * `textarea.setSelectionRange(offset, offset + cellJsonLength)` to
+ * highlight the cell.
+ *
+ * Returns -1 if the sheet isn't found or the (row, col) is out of
+ * range. Never throws.
+ */
+export declare function findCellJsonPosition(editorText: string, sheetName: string, rowIndex: number, colIndex: number): number;

package/dist/engine/math-ops.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Rounding, modulo and significance math for the mathematical functions.
+ *
+ * Pure number-in / (number | formula-error-value)-out helpers. The rounding
+ * direction and the domain rules are exactly where the engine diverged from
+ * Excel (rounding toward +∞ instead of away from zero, modulo taking the
+ * dividend's sign, negative bases and domains slipping through as NaN/∞), so
+ * they are worth testing apart from the argument-reading handlers.
+ */
+import { type SpreadsheetError } from "./spreadsheet-errors";
+/** Excel ROUND: half away from zero (JS `Math.round` breaks half toward +∞, so
+ *  `ROUND(-2.5, 0)` came back -2 instead of -3). */
+export declare function roundTo(value: number, digits: number): number;
+/** Excel ROUNDUP: away from zero. */
+export declare function roundUpTo(value: number, digits: number): number;
+/** Excel ROUNDDOWN: toward zero. */
+export declare function roundDownTo(value: number, digits: number): number;
+/** Excel FLOOR: nearest multiple of `significance` toward zero; opposite signs
+ *  are #NUM!, and a zero significance is #DIV/0! — the division by the
+ *  significance is what FLOOR reports, so it wins over the sign check. */
+export declare function floorToSignificance(value: number, significance: number): number | SpreadsheetError;
+/** Excel CEILING: nearest multiple of `significance` away from zero; opposite
+ *  signs are #NUM!, and a zero significance is 0 — deliberately NOT FLOOR's
+ *  #DIV/0!, an asymmetry Excel keeps and this engine has to match. */
+export declare function ceilingToSignificance(value: number, significance: number): number | SpreadsheetError;
+/** Excel MOD: result takes the divisor's sign (`MOD(-3, 2) === 1`); dividing by
+ *  zero is #DIV/0!, not a silent 0. */
+export declare function modulo(value: number, divisor: number): number | SpreadsheetError;
+/** Excel POWER: a negative base with a non-integer exponent has no real root, so
+ *  it is #NUM! rather than JS's NaN. */
+export declare function power(base: number, exponent: number): number | SpreadsheetError;
+/** Natural log guarded to its domain: `LN(x)` for `x <= 0` is #NUM!, not
+ *  -∞ / NaN. Reused by LN and LOG. */
+export declare function safeLog(value: number): number | SpreadsheetError;
+/** Excel LOG(value, base): the base must also be positive and not 1, or the
+ *  result is #NUM! rather than the ∞ / NaN a bare division would give. */
+export declare function logWithBase(value: number, base: number): number | SpreadsheetError;
+/** Base-10 log guarded to its domain (`LOG10(x)` for `x <= 0` is #NUM!). */
+export declare function safeLog10(value: number): number | SpreadsheetError;
+/** Square root guarded to its domain (`SQRT(x)` for `x < 0` is #NUM!, not NaN). */
+export declare function safeSqrt(value: number): number | SpreadsheetError;