@dou-ui/sheet 0.0.0-stage → 0.1.0-alpha.0

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

@@ -0,0 +1,47 @@
+import type { SheetAxis } from '../core/axis';
+import type { SheetBounds } from '../core/address';
+import { type SheetCellType, type SheetDrawContext } from '../core/cell-type';
+import type { SheetMerges } from '../core/merge';
+import type { SheetData } from '../core/model';
+import type { SheetRef } from '../core/transaction';
+import type { SheetExportOptions, SheetImageOptions, SheetPrintOptions } from '../types';
+import { type SheetDrawing } from './draw';
+/** A cell as the grid draws it, which images and pages draw the same way. */
+export interface ExportCellView {
+    text: string;
+    cls: string;
+    css: string;
+    render?: SheetCellType['render'];
+    props?: Record<string, unknown>;
+    /** A cell type's own drawing, as SVG markup. */
+    draw?: (draw: SheetDrawContext) => string;
+    label?: string;
+    hidden?: boolean;
+}
+/** A sheet as images and pages draw it: its data, laid out, and its cells as the grid draws them. */
+export interface SheetExportTarget {
+    data: SheetData;
+    rows: SheetAxis;
+    cols: SheetAxis;
+    frozen: {
+        rows: number;
+        cols: number;
+    };
+    merges: SheetMerges;
+    cellView: (row: number, col: number, line: SheetData['cells'][number], width: number, span?: SheetBounds) => ExportCellView;
+}
+/** What of the grid images and pages are drawn from. */
+export interface SheetExportSource {
+    root: () => HTMLElement | undefined;
+    /** The sheet shown, or the one named. */
+    target: (sheet?: SheetRef) => SheetExportTarget;
+    rowHeight: () => number;
+    gridlines: () => boolean;
+}
+/** `exportSVG`, `exportPNG` and `print` of a grid. */
+export declare function createSheetExport(src: SheetExportSource): {
+    exportSVG: (options?: SheetExportOptions) => string;
+    exportPNG: (options?: SheetImageOptions) => Promise<Blob>;
+    print: (options?: SheetPrintOptions) => void;
+    drawing: (options?: SheetExportOptions) => SheetDrawing;
+};

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

@@ -0,0 +1,62 @@
+import type { SheetBounds } from '../core/address';
+/** How many colors references cycle through while a formula is edited. */
+export declare const REF_COLORS = 7;
+/** A reference in a formula being edited, with the color it is marked in. */
+export interface SheetFormulaRefMark {
+    start: number;
+    end: number;
+    text: string;
+    /** The sheet it names, as written; `undefined` for the formula's own sheet. */
+    sheet?: string;
+    bounds: SheetBounds;
+    /** From 0; the same reference written twice has the same color. */
+    color: number;
+}
+/** The references of a formula being typed, each with a color. */
+export declare function formulaReferences(formula: string): SheetFormulaRefMark[];
+/**
+ * Whether a reference can be put at the caret of a formula being typed:
+ * right after `=`, an operator, `(` or `,`, and before nothing that is a
+ * value itself. There, the arrow keys and clicking cells write references.
+ */
+export declare function canPointAt(formula: string, caret: number): boolean;
+/** The function call the caret is in, innermost first, and which of its arguments, from 0. */
+export declare function callAt(formula: string, caret: number): {
+    name: string;
+    arg: number;
+    count: number;
+} | null;
+/**
+ * Which of a function's argument names the argument at `index` (of `count`)
+ * is, or -1. After `…` the names before it repeat as a group, such as the
+ * pairs of `SUMIFS` or `SWITCH`, numbered alike (`区域1, 条件1`); names after
+ * `…`, such as `SWITCH`'s default, are the last arguments when the pairs come out even.
+ */
+export declare function argNameAt(args: string[], index: number, count: number): number;
+/**
+ * The name being typed at the caret, to complete as a function: letters
+ * ending at the caret, not yet followed by `(`.
+ */
+export declare function nameAt(formula: string, caret: number): {
+    start: number;
+    end: number;
+    text: string;
+} | null;
+/** A piece of a formula being typed, as it is colored in the edit box and the formula bar. */
+export interface SheetFormulaPart {
+    text: string;
+    /** The reference's color, as in `SheetFormulaRefMark`. */
+    color?: number;
+    /** The syntax color (`dou-syntax-…`) of what isn't a reference. */
+    syntax?: 'function' | 'string' | 'number' | 'invalid' | 'keyword' | 'variable' | 'operator' | 'punctuation';
+}
+/**
+ * A formula cut into its colored pieces: references in their colors, and
+ * function names, "text", numbers, error values and operators in the
+ * syntax colors of `@dou-ui/code`, so the cell and either formula bar color
+ * it alike. Ends with a zero-width space, so a last line break still takes
+ * a line.
+ */
+export declare function formulaParts(formula: string, marks?: readonly SheetFormulaRefMark[]): SheetFormulaPart[];
+/** The class a piece of `formulaParts` is shown with. */
+export declare function partClass(part: SheetFormulaPart): string | undefined;

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

@@ -0,0 +1,99 @@
+import { type SheetWorkbook } from '../core/model';
+import { type SheetCellTarget } from '../core/address';
+import { type SheetStep } from '../core/transaction';
+import { type SheetFunction } from './functions';
+import { type SheetResult } from './values';
+export interface SheetFormulaEngineOptions {
+    /** More functions, or ones that replace built-in ones of the same name. */
+    functions?: readonly SheetFunction[];
+    /** The language `TEXT` writes dates in. */
+    locale?: string;
+    /** The time `TODAY()` and `NOW()` use; the current time by default. */
+    now?: () => Date;
+}
+/** A change for `update`: a `SheetTransaction` is one. */
+export interface SheetFormulaChange {
+    /** The workbook after the change. */
+    readonly doc: SheetWorkbook;
+    /** What changed. */
+    readonly steps: readonly SheetStep[];
+    /** The workbook before it: when it isn't the one the engine has, it starts over. */
+    readonly before: SheetWorkbook;
+}
+/**
+ * The formulas of a workbook and their results. Load a workbook, ask for
+ * results with `result`, and tell it about each change with `update`.
+ */
+export declare class SheetFormulaEngine {
+    private slots;
+    private byName;
+    private functions;
+    private parsed;
+    private volatiles;
+    private clock;
+    private epoch;
+    private context;
+    private now;
+    /** Where the formula running links to, once it called `HYPERLINK`. */
+    private linked;
+    /** The formulas the one running needed but had no results for. */
+    private missing;
+    private current;
+    /** The workbook it has. */
+    get doc(): SheetWorkbook;
+    constructor(doc?: SheetWorkbook, options?: SheetFormulaEngineOptions);
+    /** The functions formulas can call, built in and added, by name. */
+    functionList(): SheetFunction[];
+    /** Whether a function of this name can be called, built in or added. */
+    hasFunction(name: string): boolean;
+    /** Starts over with a workbook: every result is worked out again when asked for. */
+    load(doc: SheetWorkbook): void;
+    /**
+     * Catches up with a change, such as a `SheetTransaction`: changes to
+     * cells forget only the results depending on them; rows, columns or
+     * sheets added, removed, moved or renamed start over, and so does a
+     * change made to a workbook other than the one it has.
+     */
+    update(change: SheetFormulaChange): void;
+    /**
+     * What a cell comes to: its formula's result, or its value (`'=…` text
+     * without its `'`, empty text as nothing). `sheet` is a sheet's key
+     * (its `id`, or its name) or index; the cell is a name such as `'D7'`, a
+     * point, or a row and a column.
+     */
+    result(sheet: string | number, cell: SheetCellTarget): SheetResult;
+    result(sheet: string | number, row: number, col: number): SheetResult;
+    /**
+     * When the results in a row last changed, to redraw only rows whose
+     * results did; any change to the workbook that starts over changes all.
+     */
+    rowVersion(sheet: string | number, row: number): number;
+    /**
+     * Where a formula's cell links to, when the formula called `HYPERLINK`;
+     * the cell as in `result`.
+     */
+    link(sheet: string | number, cell: SheetCellTarget): string | undefined;
+    link(sheet: string | number, row: number, col: number): string | undefined;
+    /** Whether a cell holds a formula; the cell as in `result`. */
+    isFormula(sheet: string | number, cell: SheetCellTarget): boolean;
+    isFormula(sheet: string | number, row: number, col: number): boolean;
+    /** Works out a formula as if it were in a cell, without keeping it, e.g. for a preview while typing. */
+    evaluate(formula: string, sheet?: string | number): SheetResult;
+    private slotOf;
+    private parse;
+    private add;
+    private isVolatile;
+    private remove;
+    /** Forgets the results of these cells and of every formula depending on them. */
+    private forget;
+    /** A cell's value or result; `top` works out a result not kept yet, otherwise it is noted as missing. */
+    private read;
+    /** Works out a formula's result, and first those it needs, one after another. */
+    private compute;
+    private run;
+    private scalar;
+    private range;
+    private entries;
+    private ev;
+    private binary;
+}

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

@@ -0,0 +1,30 @@
+/** The error values a formula can give. */
+export declare const ERROR_CODES: readonly ["#DIV/0!", "#N/A", "#NAME?", "#NULL!", "#NUM!", "#REF!", "#VALUE!", "#CYCLE!", "#ERROR!"];
+/**
+ * - `#DIV/0!` dividing by zero
+ * - `#N/A` a lookup found nothing
+ * - `#NAME?` an unknown function or name
+ * - `#NUM!` a number out of range
+ * - `#REF!` a reference to cells or a sheet that are gone
+ * - `#VALUE!` a value of the wrong kind, such as text in a sum of two cells
+ * - `#CYCLE!` the formula depends on itself
+ * - `#ERROR!` the text isn't a formula
+ */
+export type SheetErrorCode = (typeof ERROR_CODES)[number];
+/** An error value; there is one of each, so they compare with `===`. */
+export declare class SheetError {
+    readonly code: SheetErrorCode;
+    private constructor();
+    static readonly all: Map<"#REF!" | "#DIV/0!" | "#N/A" | "#NAME?" | "#NULL!" | "#NUM!" | "#VALUE!" | "#CYCLE!" | "#ERROR!", SheetError>;
+    static of(code: SheetErrorCode): SheetError;
+    toString(): "#REF!" | "#DIV/0!" | "#N/A" | "#NAME?" | "#NULL!" | "#NUM!" | "#VALUE!" | "#CYCLE!" | "#ERROR!";
+}
+export declare const isSheetError: (value: unknown) => value is SheetError;
+export declare const DIV0: SheetError;
+export declare const NA: SheetError;
+export declare const NAME: SheetError;
+export declare const NUM: SheetError;
+export declare const REF: SheetError;
+export declare const VALUE: SheetError;
+export declare const CYCLE: SheetError;
+export declare const SYNTAX: SheetError;

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

@@ -0,0 +1,62 @@
+import { SheetError } from './error';
+import { type SheetArg, type SheetResult } from './values';
+/** What every function call is given besides its arguments. */
+export interface SheetFunctionContext {
+    /** When the calculation started; `TODAY()` and `NOW()` read it. */
+    now: Date;
+    /** The language dates are written in, for `TEXT`. */
+    locale?: string;
+    /**
+     * Makes the cell whose formula is running a link to `target`, as
+     * `HYPERLINK` does: an address as a cell's `link` takes.
+     */
+    link?: (target: string) => void;
+}
+interface FunctionBase {
+    /** The name formulas call it by; matched in any case. */
+    name: string;
+    /** The fewest and most arguments it takes; `#VALUE!` otherwise. */
+    minArgs?: number;
+    maxArgs?: number;
+    /** Gives a new result on every recalculation, like `TODAY()`. */
+    volatile?: boolean;
+    /**
+     * The arguments' names, shown while typing a call: `[name]` may be left
+     * out and `…` repeats the one before, e.g. `['金额', '[税率]']`.
+     */
+    args?: string[];
+    /** What it does, in a few words, shown in the list of functions. */
+    description?: string;
+}
+/**
+ * A formula function. `run` gets each argument as a value, or as a range
+ * for a reference to more than one cell (see `numbersOf`, `toNumber` and
+ * the other helpers), and returns the result, or a range as `CHOOSE` can.
+ * With `lazy`, it gets each argument as a function to call when needed, as
+ * `IF` does to work out only the branch it takes.
+ */
+export type SheetFunction = (FunctionBase & {
+    lazy?: false;
+    run: (args: SheetArg[], context: SheetFunctionContext) => SheetArg;
+}) | (FunctionBase & {
+    lazy: true;
+    run: (args: (() => SheetArg)[], context: SheetFunctionContext) => SheetArg;
+});
+/** Declares a formula function; only gives it a type. */
+export declare function defineSheetFunction<T extends SheetFunction>(definition: T): T;
+/** A single value from an argument: a range of one cell is that cell, a bigger one `#VALUE!`. */
+export declare function scalarOf(arg: SheetArg): SheetResult;
+/**
+ * The numbers in some arguments, the way sums count them: in ranges only
+ * numbers, dates and times count (other text, `TRUE` / `FALSE` and empty cells are skipped);
+ * given directly, text that reads as a number and `TRUE` / `FALSE` count
+ * too. The first error found is returned instead.
+ */
+export declare function numbersOf(args: SheetArg[]): number[] | SheetError;
+/**
+ * A condition as `SUMIF` and `COUNTIF` take it: a value to equal, or text
+ * such as `">5"`, `"<>完成"`, `"上海*"` (with `*` and `?`), `""` for empty.
+ */
+export declare function criteriaOf(criteria: SheetResult): (value: SheetResult) => boolean;
+export declare const builtinFunctions: SheetFunction[];
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * What a function takes and does, for completion and the argument hint
+ * while typing a formula. `args` are the argument names in order:
+ * `[name]` may be left out, and `…` means the one before can repeat.
+ */
+export interface SheetFunctionHelp {
+    args: string[];
+    description: string;
+}
+export declare const helpZhCN: Record<string, SheetFunctionHelp>;
+export declare const helpZhTW: Record<string, SheetFunctionHelp>;
+export declare const helpEn: Record<string, SheetFunctionHelp>;

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

@@ -0,0 +1,13 @@
+export { SheetFormulaEngine } from './engine';
+export type { SheetFormulaChange, SheetFormulaEngineOptions } from './engine';
+export { ERROR_CODES, isSheetError, SheetError } from './error';
+export type { SheetErrorCode } from './error';
+export { builtinFunctions, criteriaOf, defineSheetFunction, numbersOf, scalarOf } from './functions';
+export type { SheetFunction, SheetFunctionContext } from './functions';
+export { formulaTokens, functionsOf, parseFormula, referencesOf, SheetFormulaSyntaxError, } from './parse';
+export type { BinaryOp, SheetFormulaNode, SheetFormulaToken } from './parse';
+export { argNameAt, callAt, canPointAt, formulaReferences, nameAt } from './edit';
+export type { SheetFormulaRefMark } from './edit';
+export type { SheetFunctionHelp } from './help';
+export { compareValues, dateText, isDateText, isRange, serialOf, shownValue, toBoolean, toNumber, toText, } from './values';
+export type { SheetArg, SheetRangeArg, SheetResult } from './values';

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

@@ -0,0 +1,92 @@
+import { type SheetErrorCode } from './error';
+export type SheetFormulaNode = {
+    type: 'number';
+    value: number;
+} | {
+    type: 'text';
+    value: string;
+} | {
+    type: 'boolean';
+    value: boolean;
+} | {
+    type: 'error';
+    code: SheetErrorCode;
+}
+/**
+ * A reference, with its sheet as written (unquoted); whole columns run
+ * from row 0 to `Infinity`, whole rows likewise. `cell` is a single cell.
+ */
+ | {
+    type: 'ref';
+    sheet?: string;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    cell: boolean;
+}
+/** A function call; `name` in capitals. */
+ | {
+    type: 'call';
+    name: string;
+    args: SheetFormulaNode[];
+} | {
+    type: 'unary';
+    op: '-' | '+' | '%';
+    arg: SheetFormulaNode;
+} | {
+    type: 'binary';
+    op: BinaryOp;
+    left: SheetFormulaNode;
+    right: SheetFormulaNode;
+}
+/** An argument left out, as in `IF(A1,,1)`. */
+ | {
+    type: 'empty';
+};
+export type BinaryOp = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '>' | '<=' | '>=';
+/** Thrown for text that isn't a formula; it shows as `#ERROR!`. */
+export declare class SheetFormulaSyntaxError extends Error {
+    readonly at: number;
+    constructor(message: string, at: number);
+}
+/** A piece of a formula as written, with where it is in the text (counting the `=`). */
+export type SheetFormulaToken = {
+    kind: 'number' | 'text' | 'name' | 'op' | 'error';
+    start: number;
+    end: number;
+    text: string;
+} | {
+    kind: 'ref';
+    start: number;
+    end: number;
+    text: string;
+    ref: Extract<SheetFormulaNode, {
+        type: 'ref';
+    }>;
+};
+/**
+ * The pieces of a formula, also one being typed and not finished, e.g. for
+ * coloring it: numbers, "text", names (of functions), references,
+ * operators and brackets, and error values. Spaces are left out.
+ */
+export declare function formulaTokens(formula: string): SheetFormulaToken[];
+/**
+ * Reads a formula, with or without its `=`, into a tree. Throws
+ * `SheetFormulaSyntaxError` for text that isn't one.
+ */
+export declare function parseFormula(formula: string): SheetFormulaNode;
+/** Every reference in a formula tree. */
+export declare function referencesOf(node: SheetFormulaNode, out?: Extract<SheetFormulaNode, {
+    type: 'ref';
+}>[]): {
+    type: "ref";
+    sheet?: string;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    cell: boolean;
+}[];
+/** The functions a formula calls, in capitals. */
+export declare function functionsOf(node: SheetFormulaNode, out?: Set<string>): Set<string>;

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

@@ -0,0 +1,65 @@
+import type { SheetValue } from '../core/model';
+import { type SheetError } from './error';
+/**
+ * What a formula gives: a number, text, `TRUE` / `FALSE`, nothing (an
+ * empty cell), or an error. Dates are text written `2026-03-05` (or
+ * `2026-03-05 09:30`), as cells hold them.
+ */
+export type SheetResult = number | string | boolean | null | SheetError;
+/** A range a function is given: its cells, as their values or their formulas' results. */
+export interface SheetRangeArg {
+    readonly kind: 'range';
+    /** Its size, kept inside the sheet: `A:A` is as tall as the sheet. */
+    readonly rows: number;
+    readonly cols: number;
+    /** The cell at a row and column counted from the range's top left, from 0. */
+    at(row: number, col: number): SheetResult;
+    /**
+     * The cells with something in them, row by row, with where they are.
+     * Empty cells are left out, so a whole column costs only its data.
+     */
+    entries(): Iterable<[row: number, col: number, value: SheetResult]>;
+}
+/** What a function is given for each argument: a value, or a range for a reference to more than one cell. */
+export type SheetArg = SheetResult | SheetRangeArg;
+export declare const isRange: (arg: unknown) => arg is SheetRangeArg;
+/** Whether a value is a date (or date and time) as cells write them. */
+export declare const isDateText: (value: unknown) => value is string;
+/** Whether a value is a time of day as cells write it, such as `09:30`. */
+export declare const isTimeText: (value: unknown) => value is string;
+/** A date or time written in a cell as a day number (a time as part of a day); `null` when it isn't one. */
+export declare function serialOf(text: string): number | null;
+/** A day number as a date, with its time when it has a part of a day. */
+export declare function dateText(serial: number): string;
+/** A part of a day as `hh:mm`, or `hh:mm:ss` with seconds; a whole day and more wraps round. */
+export declare function timeText(fraction: number): string;
+/** A part of a day as a time; a whole day or more, or below nothing, stays a number of days. */
+export declare const timeOrDays: (days: number) => number | string;
+/** The parts of a date, from a date or a day number; `null` when it is neither. */
+export declare function dateParts(value: SheetResult): {
+    year: number;
+    month: number;
+    day: number;
+    serial: number;
+} | null;
+/**
+ * A value as a number: `TRUE` is 1, an empty cell 0, text that reads as a
+ * number (`12`, `1,280`, `12%`) or a date its number; other text is
+ * `#VALUE!`. Errors pass through.
+ */
+export declare function toNumber(value: SheetResult): number | SheetError;
+/** A value as text: numbers as a cell shows them without a format, `TRUE` / `FALSE`. */
+export declare function toText(value: SheetResult): string | SheetError;
+/** A value as `TRUE` / `FALSE`: numbers are true unless 0; text `TRUE` / `FALSE` reads as such. */
+export declare function toBoolean(value: SheetResult): boolean | SheetError;
+/**
+ * Compares two values the way formulas do: numbers by size, text by
+ * letters ignoring case, `FALSE` before `TRUE`; numbers come before text,
+ * and text before `TRUE` / `FALSE`. An empty cell is 0, or "" next to text.
+ */
+export declare function compareValues(a: SheetResult, b: SheetResult): number;
+/**
+ * A cell's value as it shows: for a formula, its result from `result`
+ * (an error as its code, such as `#N/A`), when given.
+ */
+export declare function shownValue(value: SheetValue, result: ((row: number, col: number) => SheetResult) | undefined, row: number, col: number): SheetValue;

package/dist/types/formulas.d.ts

@@ -0,0 +1,32 @@
+import { type MaybeRefOrGetter } from 'vue';
+import type { SheetCellTarget } from './core/address';
+import type { SheetWorkbook } from './core/model';
+import { SheetFormulaEngine, type SheetFormulaChange, type SheetFormulaEngineOptions } from './formula/engine';
+import type { SheetResult } from './formula/values';
+/** The results of a workbook's formulas, read reactively. */
+export interface SheetFormulas {
+    /**
+     * A cell's result, as `SheetFormulaEngine.result` gives it. Read in a
+     * `computed` or a template, it is read again when the workbook changes.
+     */
+    result: {
+        (sheet: string | number, cell: SheetCellTarget): SheetResult;
+        (sheet: string | number, row: number, col: number): SheetResult;
+    };
+    /** Works out a formula without writing it into a cell, reactively too. */
+    evaluate: (formula: string, sheet?: string | number) => SheetResult;
+    /**
+     * Catches up with a change of the grid: pass it the `transaction` event
+     * (`@transaction="formulas.update"`), and only the formulas the change
+     * reaches are worked out again. Without it, every change of the workbook
+     * works all of them out again.
+     */
+    update: (change: SheetFormulaChange) => void;
+    /** The engine underneath. */
+    readonly engine: SheetFormulaEngine;
+}
+/**
+ * Works out a workbook's formulas outside the grid, such as for totals
+ * shown above it. `book` is the workbook bound to the grid's `v-model`.
+ */
+export declare function useSheetFormulas(book: MaybeRefOrGetter<SheetWorkbook>, options?: SheetFormulaEngineOptions): SheetFormulas;