@speed-sheet/extension-formula 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+import { Sheet, Extension } from '@speed-sheet/core';
+import { CellAttributes } from '@speed-sheet/shared';
+
+interface FormulaContext {
+    readonly activeSheetId: string;
+    resolveSheetId(nameOrId: string | undefined): string | null;
+    getSheetName(sheetId: string): string;
+    resolveCellIds(sheetId: string, r: number, c: number): {
+        rowId: string;
+        colId: string;
+    } | null;
+    idsToDisplay(sheetId: string, rowId: string, colId: string): {
+        r: number;
+        c: number;
+    } | null;
+    expandIdRange(sheetId: string, rowId0: string, colId0: string, rowId1: string, colId1: string): Array<{
+        rowId: string;
+        colId: string;
+    }>;
+    /** Scalar by stable ids (canonical for evaluation). */
+    getScalarById(sheetId: string, rowId: string, colId: string, visiting: Set<string>): number | string | boolean | null;
+    /** Display-coordinate scalar (A1 boundary only). */
+    getScalar(sheetId: string, r: number, c: number, visiting: Set<string>): number | string | boolean | null;
+}
+declare function createFormulaContext(sheet: Sheet): FormulaContext;
+
+interface FormulaRangeHighlight {
+    sheetId: string;
+    row: [number, number];
+    column: [number, number];
+    color: string;
+}
+
+interface FormulaStorage {
+    evaluating: boolean;
+    dependents: Map<string, Set<string>>;
+    sheet: Sheet | null;
+}
+declare const FormulaExtension: Extension<FormulaStorage>;
+declare function getFormulaHighlights(sheet: Sheet, formula: string): FormulaRangeHighlight[];
+
+/** Excel 风格公式错误（显示值 + 提示文案） */
+type FormulaErrorCode = 'ERROR' | 'VALUE' | 'NAME' | 'REF' | 'DIV0' | 'NA' | 'NUM' | 'NULL';
+interface FormulaErrorDef {
+    code: FormulaErrorCode;
+    /** 单元格显示，如 #VALUE! */
+    display: string;
+    /** 悬停提示（中文） */
+    message: string;
+}
+declare const FORMULA_ERRORS: Record<FormulaErrorCode, FormulaErrorDef>;
+declare function formulaErrorResult(code: FormulaErrorCode): {
+    value: null;
+    m: string;
+    error: FormulaErrorCode;
+    errorMessage: string;
+};
+declare function isFormulaErrorDisplay(text: string): boolean;
+declare function getFormulaErrorMessage(code: string | undefined, fallback?: string): string;
+
+/**
+ * 公式编辑态字符串操作（headless，与 UI 框架无关）。
+ * 供 vue3 / 其他宿主在公式栏、单元格内联编辑、点选引用时复用。
+ */
+
+/**
+ * 是否处于「点选插入引用」态（而非仅公式编辑态）。
+ * @param refPickSession 已为 true 时等同 Luckysheet rangestart（上一次点选后保持到提交/取消）
+ */
+declare function canPickFormulaRefAtCaret(formula: string, caret: number): boolean;
+declare function canPickFormulaRef(formula: string, caret: number, refPickSession: boolean): boolean;
+declare function isFormulaInput(text: string): boolean;
+declare const isFormulaText: typeof isFormulaInput;
+declare function getCellFormulaInitialFromCell(cell: CellAttributes | null | undefined, sheet?: Sheet, sheetId?: string): string;
+/** 进入公式编辑时的初始文本：已有公式则保留，否则为 `=` */
+declare function getCellFormulaInitial(sheet: Sheet, r: number, c: number): string;
+declare function formatRangeA1(r0: number, c0: number, r1: number, c1: number): string;
+declare function buildSheetRefToken(sheet: Sheet, r0: number, c0: number, r1?: number, c1?: number, sheetId?: string): string;
+/** 在公式中插入/替换引用：运算符后拼接，否则替换光标处引用（或最后一个引用） */
+declare function patchFormulaWithRef(formula: string, caret: number, refToken: string): {
+    text: string;
+    caret: number;
+};
+
+interface FormulaResult {
+    value: number | string | boolean | null;
+    m: string;
+    error?: FormulaErrorCode;
+    errorMessage?: string;
+}
+declare function evaluateFormulaString(raw: string, ctx: FormulaContext, visiting?: Set<string>): FormulaResult;
+
+/** A1 风格引用解析（与 Excel / Luckysheet 子集对齐） */
+interface CellAddress {
+    r: number;
+    c: number;
+}
+interface RangeAddress {
+    row: [number, number];
+    column: [number, number];
+}
+interface SheetRef {
+    /** 工作表名（展示名）或 id */
+    sheet?: string;
+    cell?: CellAddress;
+    range?: RangeAddress;
+}
+/** 列字母 → 0-based 列号 */
+declare function letterToCol(letters: string): number;
+declare function colToLetter(c: number): string;
+declare function formatA1(r: number, c: number): string;
+/** 解析 A1 或 A1:B10 */
+declare function parseRefToken(token: string): SheetRef | null;
+/** 从公式文本中提取全部 A1 引用 token（跳过 `#r_…:c_…#` 内部区域） */
+declare function extractRefTokens(formula: string): string[];
+
+declare function hasInternalRefs(formula: string): boolean;
+
+/** User-facing A1 formula → canonical internal formula (stored in `f`). */
+declare function displayFormulaToInternal(displayFormula: string, ctx: FormulaContext, defaultSheetId: string): string;
+/** Stored internal formula → formula-bar A1 display. */
+declare function internalFormulaToDisplay(internalFormula: string, ctx: FormulaContext, defaultSheetId: string): string;
+
+declare const FORMULA_REF_COLORS: readonly ["#1a73e8", "#0d9d57", "#e37400", "#9c27b0", "#d93025"];
+interface FormulaRefSpan {
+    start: number;
+    end: number;
+    token: string;
+    color: string;
+}
+/** 公式内引用 token 着色区间 */
+declare function getFormulaRefSpans(formula: string): FormulaRefSpan[];
+
+/**
+ * 公式内置函数注册表类型。
+ * 函数名以 @formulajs/formulajs 为准；分类对齐 formulajs.info / Excel。
+ */
+type FormulaCategoryId = 'math' | 'statistical' | 'financial' | 'engineering' | 'text' | 'logical' | 'date' | 'lookup' | 'information' | 'database' | 'compatibility';
+interface FormulaCategoryMeta {
+    id: FormulaCategoryId;
+    /** 菜单/面板分类名（中文） */
+    label: string;
+    labelEn: string;
+    /** formulajs.info 原始分类名 */
+    formulajsCategory: string;
+}
+interface FormulaBuiltinEntry {
+    /** 规范函数名（大写） */
+    name: string;
+    aliases?: string[];
+    category: FormulaCategoryId;
+    /** 短标签，如「求和」 */
+    label: string;
+    labelEn?: string;
+    /** 语法摘要，如 SUM(数值1, [数值2], …) */
+    syntax: string;
+    /** 一行说明（帮助气泡） */
+    hint: string;
+    /** 详细定义（函数面板） */
+    description?: string;
+    /** 示例 */
+    example?: string;
+    /** 另请参阅 */
+    seeAlso?: string[];
+    /** speed-sheet 引擎已接入求值 */
+    implemented?: boolean;
+    /** @formulajs/formulajs 包内存在实现 */
+    formulajs?: boolean;
+    /** 常用函数区 */
+    featured?: boolean;
+}
+
+declare const FORMULA_BUILTIN_REGISTRY: readonly FormulaBuiltinEntry[];
+
+declare const FORMULA_CATEGORIES: readonly FormulaCategoryMeta[];
+declare function categoryLabel(id: FormulaCategoryId, locale?: 'zh' | 'en'): string;
+
+declare function resolveBuiltinName(name: string): string | undefined;
+declare function isRegisteredBuiltin(name: string): boolean;
+declare function getBuiltinEntry(name: string): FormulaBuiltinEntry | undefined;
+declare function getFeaturedBuiltins(): FormulaBuiltinEntry[];
+declare function getBuiltinsByCategory(category: FormulaCategoryId): FormulaBuiltinEntry[];
+/** 菜单用：有函数的分类（保持 FORMULA_CATEGORIES 顺序） */
+declare function getCategoriesWithBuiltins(): FormulaCategoryId[];
+declare function searchBuiltins(query: string): FormulaBuiltinEntry[];
+/** 从公式文本解析当前正在输入的函数名（=SUM( → SUM） */
+declare function parseActiveFunctionName(formula: string, caret: number): string | null;
+
+declare function cellPatchFromFormulaResult(formula: string, result: FormulaResult): Partial<CellAttributes>;
+
+export { FORMULA_BUILTIN_REGISTRY, FORMULA_CATEGORIES, FORMULA_ERRORS, FORMULA_REF_COLORS, type FormulaBuiltinEntry, type FormulaCategoryId, type FormulaErrorCode, FormulaExtension, type FormulaRangeHighlight, type FormulaRefSpan, type FormulaResult, type FormulaStorage, buildSheetRefToken, canPickFormulaRef, canPickFormulaRefAtCaret, categoryLabel, cellPatchFromFormulaResult, colToLetter, createFormulaContext, displayFormulaToInternal, evaluateFormulaString, extractRefTokens, formatA1, formatRangeA1, formulaErrorResult, getBuiltinEntry, getBuiltinsByCategory, getCategoriesWithBuiltins, getCellFormulaInitial, getCellFormulaInitialFromCell, getFeaturedBuiltins, getFormulaErrorMessage, getFormulaHighlights, getFormulaRefSpans, hasInternalRefs, internalFormulaToDisplay, isFormulaErrorDisplay, isFormulaInput, isFormulaText, isRegisteredBuiltin, letterToCol, parseActiveFunctionName, parseRefToken, patchFormulaWithRef, resolveBuiltinName, searchBuiltins };