@p10node/office-engine 0.0.0-stage → 0.1.0

package/dist/types/core/xlsx/formula/assist.d.ts

@@ -0,0 +1,35 @@
+import { type RefAddr } from './refs';
+export interface FormulaRef {
+    /** span in the full text (including the leading '=') */
+    s: number;
+    e: number;
+    text: string;
+    ref: RefAddr;
+}
+export interface FormulaContext {
+    /** identifier right before the caret (to autocomplete); span in the full text */
+    word?: {
+        s: number;
+        e: number;
+        text: string;
+        call: boolean;
+    };
+    /** innermost function call around the caret; arg is 0-based */
+    call?: {
+        name: string;
+        arg: number;
+    };
+    /** a reference can be inserted at the caret */
+    pointable: boolean;
+    refs: FormulaRef[];
+}
+export declare const isFormula: (text: string) => boolean;
+/** Context of the caret inside formula `text` (full cell text, starting with '='). */
+export declare function formulaContext(text: string, caret: number): FormulaContext;
+/** Reference text for a selected block (`A1`, `A1:B3`, `A:A`, `1:1`), sheet-qualified when `sheet` is given. */
+export declare function rangeText(r0: number, c0: number, r1: number, c1: number, sheet?: string): string;
+/**
+ * What Excel does on Enter: upper-cases function names, references and booleans,
+ * closes an unterminated string and open parentheses.
+ */
+export declare function closeFormula(text: string): string;

package/dist/types/core/xlsx/formula/catalog.d.ts

@@ -0,0 +1,14 @@
+export interface FnInfo {
+    name: string;
+    args: string[];
+    /** last argument repeats (`...`) */
+    variadic: boolean;
+    desc: string;
+}
+/** All functions offered to the user, sorted by name. */
+export declare function functionCatalog(): FnInfo[];
+export declare function functionInfo(name: string): FnInfo | undefined;
+/** Functions whose name starts with `prefix` (case-insensitive). */
+export declare function suggestFunctions(prefix: string, limit?: number): FnInfo[];
+/** Index of the signature argument to highlight for the `arg`-th (0-based) argument being typed. */
+export declare function argSlot(f: FnInfo, arg: number): number;

package/dist/types/core/xlsx/formula/dates.d.ts

@@ -0,0 +1,23 @@
+/** Date serials (1900 system with the Lotus leap-year bug, or 1904), date/time text parsing, TEXT() formatting. */
+export declare function getDate1904(): boolean;
+export declare function setDate1904(v: boolean): void;
+/** Serial for y/m/d (m 1-based; month/day overflow normalized like DATE()). */
+export declare function ymdToSerial(y: number, m: number, d: number): number;
+export interface DateParts {
+    y: number;
+    m: number;
+    d: number;
+    /** 0 = Sunday */
+    dow: number;
+}
+export declare function serialToYmd(serial: number): DateParts;
+/** Seconds of the day (rounded to the nearest second). */
+export declare function serialSeconds(serial: number): number;
+export declare function daysInMonth(y: number, m: number): number;
+/** Serial of a JS Date using its local calendar components. */
+export declare function dateToSerial(dt: Date): number;
+/** Parse date/time text: `yyyy-mm-dd [time]`, `m/d/yyyy [time]`, `hh:mm[:ss] [AM/PM]`. */
+export declare function parseDateText(s: string): number | null;
+export declare function splitSections(fmt: string): string[];
+export declare function isDateFormat(sec: string): boolean;
+export declare function formatDate(serial: number, sec: string): string;

package/dist/types/core/xlsx/formula/evaluate.d.ts

@@ -0,0 +1,33 @@
+import { type Ev } from './fn';
+import { type Ast, type BinOp } from './parser';
+import { type CellProvider, type EvalContext, type Value } from './types';
+import { RangeV, type Val } from './values';
+export declare function binop(op: BinOp, a: Value, b: Value): Value;
+type Operand = Value | Value[][];
+export declare class Evaluator implements Ev {
+    readonly provider: CellProvider;
+    readonly sheet: string | undefined;
+    readonly r: number;
+    readonly c: number;
+    constructor(ctx: EvalContext);
+    eval(ast: Ast, top: boolean): Val;
+    private ref;
+    private rangeOp;
+    private call;
+    hasSheet(name: string): boolean;
+    now(): Date;
+    cell(sheet: string | undefined, r: number, c: number): Value;
+    /** Clip whole-row/whole-column style ranges to the provider's used extent. */
+    private clip;
+    forEach(rg: RangeV, cb: (v: Value, i: number, j: number) => void): void;
+    toArray(v: Val): Value[][];
+    /** Implicit intersection of a range with the formula cell's row/column. */
+    intersect(rg: RangeV): Value;
+    scalar(v: Val): Value;
+    operand(v: Val, top: boolean): Operand;
+}
+/** Evaluate a parsed formula for the cell at ctx.{sheet,r,c}. Never throws; errors come back as FormulaError. */
+export declare function evaluate(ast: Ast, ctx: EvalContext): Value;
+/** Parse + evaluate. Syntax errors evaluate to #NAME?. */
+export declare function evaluateFormula(text: string, ctx: EvalContext): Value;
+export {};

package/dist/types/core/xlsx/formula/fn-date.d.ts

@@ -0,0 +1,2 @@
+import { type FnDef } from './fn';
+export declare const DATE: Record<string, FnDef>;

package/dist/types/core/xlsx/formula/fn-logic.d.ts

@@ -0,0 +1,3 @@
+/** Logical and information functions. */
+import { type FnDef } from './fn';
+export declare const LOGIC: Record<string, FnDef>;

package/dist/types/core/xlsx/formula/fn-lookup.d.ts

@@ -0,0 +1,3 @@
+/** Lookup & reference functions. */
+import { type FnDef } from './fn';
+export declare const LOOKUP: Record<string, FnDef>;

package/dist/types/core/xlsx/formula/fn-math.d.ts

@@ -0,0 +1,3 @@
+/** Math functions. */
+import { type FnDef } from './fn';
+export declare const MATH: Record<string, FnDef>;

package/dist/types/core/xlsx/formula/fn-stats.d.ts

@@ -0,0 +1,3 @@
+/** Aggregate, statistical and criteria (*IF/*IFS) functions. */
+import { type FnDef } from './fn';
+export declare const STATS: Record<string, FnDef>;

package/dist/types/core/xlsx/formula/fn-text.d.ts

@@ -0,0 +1,3 @@
+/** Text functions. */
+import { type FnDef } from './fn';
+export declare const TEXT: Record<string, FnDef>;

package/dist/types/core/xlsx/formula/fn.d.ts

@@ -0,0 +1,64 @@
+/** Function-definition plumbing: evaluator interface, arity, array lifting, argument visitors. */
+import type { Ast } from './parser';
+import { FormulaError, type Value } from './types';
+import { RangeV, type Val } from './values';
+/** What a function implementation may ask of the evaluator. */
+export interface Ev {
+    readonly sheet: string | undefined;
+    /** 0-based formula cell position */
+    readonly r: number;
+    readonly c: number;
+    eval(ast: Ast, top: boolean): Val;
+    cell(sheet: string | undefined, r: number, c: number): Value;
+    /** visit cells of a range (whole-row/col ranges clipped to the provider's bounds) */
+    forEach(rg: RangeV, cb: (v: Value, i: number, j: number) => void): void;
+    /** 2-D values of a range/array/scalar (clipped like forEach); unions -> #VALUE! thrown */
+    toArray(v: Val): Value[][];
+    /** single value: 1x1 range -> cell, larger range -> implicit intersection, array -> top-left */
+    scalar(v: Val): Value;
+    /** operator operand: scalar, or 2-D data when array-evaluated (top=false) */
+    operand(v: Val, top: boolean): Value | Value[][];
+    hasSheet(name: string): boolean;
+    now(): Date;
+}
+export type EagerFn = (args: Val[], ev: Ev, top: boolean) => Val;
+export type LazyFn = (args: Ast[], ev: Ev, top: boolean) => Val;
+export type FnDef = 
+/** args evaluated first; `scalarArgs` => args inherit the caller's top-level (implicit intersection) context */
+{
+    kind: 'eager';
+    min: number;
+    max: number;
+    scalarArgs: boolean;
+    fn: EagerFn;
+}
+/** receives unevaluated args (IF, IFERROR, CHOOSE, ...) */
+ | {
+    kind: 'lazy';
+    min: number;
+    max: number;
+    fn: LazyFn;
+};
+export declare const INF: number;
+/** Run f, converting a thrown FormulaError into a value. */
+export declare function guard<T>(f: () => T): T | FormulaError;
+/** Pick (i,j) from 2-D data with 1-row/1-col broadcasting; out of shape -> #N/A. */
+export declare function pick(d: Value[][], i: number, j: number): Value;
+/**
+ * Scalar function, lifted element-wise over array arguments (array formulas / SUMPRODUCT(LEN(A1:A3))).
+ * At the formula top level a multi-cell range argument is implicitly intersected instead.
+ */
+export declare function S(min: number, max: number, f: (a: Value[], ev: Ev) => Value): FnDef;
+/** Function taking ranges/arrays as-is (args evaluated in array context). */
+export declare function A(min: number, max: number, fn: EagerFn): FnDef;
+/** Lazy function (receives ASTs). */
+export declare function L(min: number, max: number, fn: LazyFn): FnDef;
+/** Visit every value of an argument: cells/array items via `inRange`, direct scalars via `direct`. */
+export declare function visit(a: Val, ev: Ev, inRange: (v: Value) => void, direct: (v: Value) => void): void;
+/** Numbers of aggregate args: ranges contribute numbers only, direct scalars coerce; errors throw. */
+export declare function eachNum(args: Val[], ev: Ev, cb: (n: number) => void): void;
+export declare function nums(args: Val[], ev: Ev): number[];
+/** Flatten a range/array to a row-major list. */
+export declare function flat(d: Value[][]): Value[];
+/** Optional numeric arg i (missing argument => 0 like Excel; absent => def). */
+export declare function opt(a: Value[], i: number, def: number): number;

package/dist/types/core/xlsx/formula/format.d.ts

@@ -0,0 +1,5 @@
+import { type Value } from './types';
+/** Round half away from zero to d decimals, removing binary noise first. */
+export declare function roundHalf(x: number, d: number): number;
+/** TEXT(value, format). Throws FormulaError on invalid input. */
+export declare function formatText(v: Value, fmt: string): string;

package/dist/types/core/xlsx/formula/functions.d.ts

@@ -0,0 +1,4 @@
+import type { FnDef } from './fn';
+export declare const FUNCTIONS: Readonly<Record<string, FnDef>>;
+/** Names of all supported functions. */
+export declare function supportedFunctions(): string[];

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

@@ -0,0 +1,17 @@
+/** Excel formula engine: parse, evaluate, rewrite (fill / insert-delete / rename) and dependency extraction. */
+export { ERROR_CODES, FormulaError, MAX_COL, MAX_ROW } from './types';
+export type { CellProvider, CellRef, ErrorCode, EvalContext, RangeRef, Value } from './types';
+export { FormulaSyntaxError } from './lexer';
+export { parseFormula } from './parser';
+export type { Ast, BinOp } from './parser';
+export type { RefAddr } from './refs';
+export { colIndex, colName, quoteSheet } from './refs';
+export { evaluate, evaluateFormula } from './evaluate';
+export { references, renameSheetInFormula, shiftFormula, translateFormula } from './transform';
+export type { ShiftOp } from './transform';
+export { supportedFunctions } from './functions';
+export { numToText, parseNumberText } from './values';
+export { closeFormula, formulaContext, isFormula, rangeText } from './assist';
+export type { FormulaContext, FormulaRef } from './assist';
+export { argSlot, functionCatalog, functionInfo, suggestFunctions } from './catalog';
+export type { FnInfo } from './catalog';

package/dist/types/core/xlsx/formula/lexer.d.ts

@@ -0,0 +1,54 @@
+/** Tokenizer for OOXML formula text (no leading '='). Tokens carry source spans so transforms can splice text. */
+import { type RefAddr } from './refs';
+import { type ErrorCode } from './types';
+export declare class FormulaSyntaxError extends Error {
+    readonly pos: number;
+    constructor(message: string, pos: number);
+}
+interface Span {
+    s: number;
+    e: number;
+}
+export type Token = Span & ({
+    t: 'num';
+    v: number;
+} | {
+    t: 'str';
+    v: string;
+} | {
+    t: 'bool';
+    v: boolean;
+} | {
+    t: 'err';
+    v: ErrorCode;
+    sheet?: string;
+} | {
+    t: 'ref';
+    ref: RefAddr;
+    sheetText?: string;
+} | {
+    t: 'func';
+    v: string;
+} | {
+    t: 'name';
+    v: string;
+    sheet?: string;
+} | {
+    t: 'op';
+    v: string;
+} | {
+    t: 'punc';
+    v: string;
+} | {
+    t: 'ws';
+});
+/** Try to read an A1 reference (cell, area, A:B, 1:2) at i. */
+export declare function readRef(src: string, i: number): {
+    ref: RefAddr;
+    end: number;
+} | null;
+export declare function stripFnPrefix(name: string): string;
+export declare function tokenize(src: string): Token[];
+/** Parse a plain reference string (INDIRECT): `A1`, `Sheet1!A1:B2`, `'x y'!C:C`, `3:3`. */
+export declare function parseRefText(text: string): RefAddr | null;
+export {};

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

@@ -0,0 +1,53 @@
+import type { RefAddr } from './refs';
+import type { ErrorCode, Value } from './types';
+export type BinOp = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '>' | '<=' | '>=';
+export type Ast = {
+    type: 'num';
+    value: number;
+} | {
+    type: 'str';
+    value: string;
+} | {
+    type: 'bool';
+    value: boolean;
+} | {
+    type: 'err';
+    code: ErrorCode;
+} | {
+    type: 'missing';
+} | {
+    type: 'ref';
+    ref: RefAddr;
+} | {
+    type: 'name';
+    name: string;
+    sheet?: string;
+} | {
+    type: 'array';
+    rows: Value[][];
+} | {
+    type: 'unary';
+    op: '-' | '+';
+    arg: Ast;
+} | {
+    type: 'percent';
+    arg: Ast;
+} | {
+    type: 'binary';
+    op: BinOp;
+    left: Ast;
+    right: Ast;
+} | {
+    type: 'range';
+    left: Ast;
+    right: Ast;
+} | {
+    type: 'union';
+    items: Ast[];
+} | {
+    type: 'call';
+    name: string;
+    args: Ast[];
+};
+/** Parse formula text (OOXML stored form, without '='; a leading '=' is tolerated). Throws FormulaSyntaxError. */
+export declare function parseFormula(text: string): Ast;

package/dist/types/core/xlsx/formula/refs.d.ts

@@ -0,0 +1,23 @@
+/** Parsed A1 reference as written in a formula (0-based, inclusive, normalized r0<=r1, c0<=c1). */
+export interface RefAddr {
+    sheet?: string;
+    kind: 'cell' | 'area' | 'cols' | 'rows';
+    r0: number;
+    c0: number;
+    r1: number;
+    c1: number;
+    ar0: boolean;
+    ac0: boolean;
+    ar1: boolean;
+    ac1: boolean;
+}
+export declare function colName(c: number): string;
+export declare function colIndex(letters: string): number;
+export declare function sameSheet(a: string | undefined, b: string | undefined): boolean;
+/** Sheet name as it must appear before '!' (quoted when needed). */
+export declare function quoteSheet(name: string): string;
+/** Reference text. `sheetText` (raw prefix without '!') is reused when given to preserve original quoting. */
+export declare function fmtRef(a: RefAddr, sheetText?: string): string;
+/** Swap ends (with their $ flags) so r0<=r1 and c0<=c1. Mutates. */
+export declare function normalizeRef(a: RefAddr): RefAddr;
+export declare function refInBounds(a: RefAddr): boolean;

package/dist/types/core/xlsx/formula/transform.d.ts

@@ -0,0 +1,21 @@
+import type { Ast } from './parser';
+import { type CellRef, type RangeRef } from './types';
+/** Copy/fill: shift relative parts of every reference by (dr, dc). Out-of-sheet results become #REF!. */
+export declare function translateFormula(text: string, dr: number, dc: number): string;
+export interface ShiftOp {
+    /** sheet whose rows/cols change (undefined: the formula's own sheet) */
+    sheet?: string;
+    /** sheet the formula lives on (unqualified refs belong to it; undefined: same as `sheet`) */
+    formulaSheet?: string;
+    axis: 'row' | 'col';
+    /** 0-based index of the first inserted/deleted row/col */
+    at: number;
+    /** >0 insert count, <0 delete count */
+    delta: number;
+}
+/** Rewrite references after inserting/deleting rows or columns. */
+export declare function shiftFormula(text: string, op: ShiftOp): string;
+/** Rename sheet qualifiers (`Old!A1`, `'Old'!A1:B2`, `Old!#REF!`, `Old!Name`). */
+export declare function renameSheetInFormula(text: string, oldName: string, newName: string): string;
+/** Every cell/range the formula reads directly (static references; INDIRECT/OFFSET targets are dynamic). */
+export declare function references(ast: Ast): (CellRef | RangeRef)[];

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

@@ -0,0 +1,59 @@
+/** Core value / reference / provider types of the formula engine. */
+export type ErrorCode = '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#N/A' | '#NUM!' | '#NULL!';
+/** ERROR.TYPE order (1-based). */
+export declare const ERROR_CODES: readonly ErrorCode[];
+export declare class FormulaError {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode);
+    toString(): string;
+}
+/** null = empty cell */
+export type Value = number | string | boolean | FormulaError | null;
+/** 0-based cell reference. */
+export interface CellRef {
+    sheet?: string;
+    r: number;
+    c: number;
+    absR: boolean;
+    absC: boolean;
+}
+/** 0-based inclusive range. Whole column A:A => r0=0, r1=MAX_ROW; whole row 1:1 => c0=0, c1=MAX_COL. */
+export interface RangeRef {
+    sheet?: string;
+    r0: number;
+    c0: number;
+    r1: number;
+    c1: number;
+}
+export interface CellProvider {
+    /** value of a cell; formula cells return their current computed value */
+    value(sheet: string | undefined, r: number, c: number): Value;
+    /** used extent of a sheet, to clip whole-row/column ranges (optional) */
+    bounds?(sheet: string | undefined): {
+        rows: number;
+        cols: number;
+    };
+    /** sheet exists? (unknown sheet -> #REF!) optional */
+    hasSheet?(name: string): boolean;
+    date1904?: boolean;
+    now?(): Date;
+}
+export interface EvalContext {
+    provider: CellProvider;
+    /** sheet the formula lives on (unqualified refs resolve here) */
+    sheet?: string;
+    /** 0-based position of the formula cell */
+    r: number;
+    c: number;
+}
+export declare const MAX_ROW = 1048575;
+export declare const MAX_COL = 16383;
+export declare const ERR: {
+    readonly DIV0: FormulaError;
+    readonly VALUE: FormulaError;
+    readonly REF: FormulaError;
+    readonly NAME: FormulaError;
+    readonly NA: FormulaError;
+    readonly NUM: FormulaError;
+    readonly NULL: FormulaError;
+};

package/dist/types/core/xlsx/formula/values.d.ts

@@ -0,0 +1,49 @@
+import { FormulaError, type Value } from './types';
+/** Reference to a rectangular block of cells (0-based inclusive). */
+export declare class RangeV {
+    readonly sheet: string | undefined;
+    readonly r0: number;
+    readonly c0: number;
+    readonly r1: number;
+    readonly c1: number;
+    constructor(sheet: string | undefined, r0: number, c0: number, r1: number, c1: number);
+    get h(): number;
+    get w(): number;
+}
+/** In-memory array (array constants and array-evaluated results). Always at least 1x1. */
+export declare class ArrayV {
+    readonly data: Value[][];
+    constructor(data: Value[][]);
+    get h(): number;
+    get w(): number;
+}
+/** Multi-area reference `(A1:B2,D4)`. */
+export declare class UnionV {
+    readonly areas: RangeV[];
+    constructor(areas: RangeV[]);
+}
+export type Val = Value | RangeV | ArrayV | UnionV;
+export declare const isErr: (v: unknown) => v is FormulaError;
+/** Numeric text -> number (plain, 1,234.5, 50%, $3, 1E3, dates, times); null when not numeric. */
+export declare function parseNumberText(s: string): number | null;
+/** Excel "General" text of a number (15 significant digits). */
+export declare function numToText(n: number): string;
+export declare function toNum(v: Value): number | FormulaError;
+export declare function toStr(v: Value): string | FormulaError;
+export declare function toBool(v: Value): boolean | FormulaError;
+export declare function num(v: Value): number;
+export declare function int(v: Value): number;
+export declare function str(v: Value): string;
+export declare function bool(v: Value): boolean;
+/** Throw if v is an error, else return it. */
+export declare function check<T extends Value>(v: T): Exclude<T, FormulaError>;
+export declare function numEq(a: number, b: number): boolean;
+/** Excel ordering: numbers < text < booleans; text case-insensitive; empty adopts the other side's type. Errors not allowed. */
+export declare function compare(a: Value, b: Value): number;
+/** Lookup equality: same type, text case-insensitive. */
+export declare function valueEq(a: Value, b: Value): boolean;
+export declare const hasWildcard: (s: string) => boolean;
+export declare function wildcardRe(pat: string, anchored?: boolean): RegExp;
+export type Matcher = (v: Value) => boolean;
+/** Criteria of COUNTIF/SUMIF/...: "<5", ">=10", "<>x", "=abc", "a*c", 3, TRUE, "" (blank). */
+export declare function criteria(crit: Value): Matcher;

package/dist/types/core/xlsx/numfmt.d.ts

@@ -0,0 +1,11 @@
+/** Excel number-format subset: General, fixed/grouped/percent/scientific/fraction, dates & times, sections & colors. */
+export declare const BUILTIN_FORMATS: Record<number, string>;
+export declare function isDateFormat(fmt: string): boolean;
+export declare function formatGeneral(v: number): string;
+export declare function serialToDate(serial: number, date1904?: boolean): Date;
+export interface Formatted {
+    text: string;
+    color?: string;
+}
+export declare function formatValue(v: number, fmt: string | undefined, date1904?: boolean): Formatted;
+export declare function formatText(s: string, fmt: string | undefined): string;

package/dist/types/core/xlsx/structure.d.ts

@@ -0,0 +1,31 @@
+import type { ColInfo, Merge, Range } from './types';
+import { type SheetData } from './workbook';
+export interface Snapshot {
+    rows: (unknown[] | undefined)[];
+    formulas: Map<number, string>;
+    merges: Merge[];
+    colInfo: ColInfo[];
+    rowAttrs: Map<number, {
+        ht?: number;
+        hidden?: boolean;
+    }>;
+    autoRowH: Map<number, number>;
+    maxRow: number;
+    maxCol: number;
+    frozen: {
+        rows: number;
+        cols: number;
+    };
+}
+export declare function snapshot(d: SheetData): Snapshot;
+export declare function restore(d: SheetData, s: Snapshot): void;
+/** shared formulas → explicit per-cell formulas (needed before rows/cols move) */
+export declare function materializeShared(d: SheetData): void;
+/** Moves rows or columns; delta > 0 inserts at `at`, delta < 0 deletes -delta starting at `at`. */
+export declare function shiftSheet(d: SheetData, sheetName: string, axis: 'row' | 'col', at: number, delta: number, others: {
+    name: string;
+    d: SheetData;
+}[]): void;
+export declare function setMerge(d: SheetData, range: Range, merge: boolean): void;
+export declare function setColWidth(d: SheetData, c0: number, c1: number, px: number): void;
+export declare function setRowHeight(d: SheetData, r0: number, r1: number, px: number): void;

package/dist/types/core/xlsx/styles.d.ts

@@ -0,0 +1,17 @@
+import type { Theme } from '../theme';
+import { type XEl } from '../xml';
+import type { CellCss } from './types';
+export interface XfInfo {
+    numFmt: string;
+    /** font size in pt */
+    fontPt: number;
+    css: CellCss;
+    /** explicit horizontal alignment */
+    hAlign?: string;
+    wrap: boolean;
+}
+export interface SheetStyles {
+    xfs: XfInfo[];
+    baseFont: CellCss;
+}
+export declare function parseSheetStyles(root: XEl | undefined, theme: Theme): SheetStyles;