@univerjs/engine-formula 1.0.0-alpha.2 → 1.0.0-alpha.4

package/lib/types/basics/common.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { ICellData, IColumnData, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IRange, IRowData, IUnitRange, Nullable, ObjectMatrix, Styles } from '@univerjs/core';
+import type { ICellData, IColumnData, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IRange, IRowData, IUnitRange, Nullable, ObjectMatrix, Styles, UniverInstanceType } from '@univerjs/core';
 import type { sequenceNodeType } from '../engine/utils/sequence';
 import type { IImageFormulaInfo } from '../engine/value-object/primitive-object';
 export declare const ERROR_VALUE_OBJECT_CLASS_TYPE = "errorValueObject";
@@ -75,6 +75,15 @@ export interface IUnitSheetNameMap {
         [sheetName: string]: string;
     }>;
 }
+export type FormulaUnitType = UniverInstanceType.UNIVER_SHEET | UniverInstanceType.UNIVER_BASE;
+export interface IFormulaUnitNameMapItem {
+    name: string;
+    unitType: FormulaUnitType;
+}
+/** Runtime Unit metadata keyed by stable unitId. */
+export interface IFormulaUnitNameMap {
+    [unitId: string]: IFormulaUnitNameMapItem;
+}
 export interface IUnitSheetIdToNameMap {
     [unitId: string]: Nullable<{
         [sheetId: string]: string;
@@ -193,6 +202,11 @@ export interface ISuperTable {
     sheetId: string;
     titleMap: Map<string, number>;
     range: IRange;
+    /**
+     * Whether the projected range contains a physical header row.
+     * Sheet tables default to true; Base virtual tables store records from row 0.
+     */
+    showHeader?: boolean;
 }
 export declare enum TableOptionType {
     ALL = "#All",
@@ -227,6 +241,7 @@ export interface IFormulaDatasetConfig {
     allUnitData?: IUnitData;
     unitStylesData?: IUnitStylesData;
     unitSheetNameMap?: IUnitSheetNameMap;
+    unitNameMap?: IFormulaUnitNameMap;
     maxIteration?: number;
     isCalculateTreeModel?: boolean;
     rowData?: IUnitRowData;

package/lib/types/basics/date.d.ts

@@ -42,8 +42,8 @@ export declare function formatDateDefault(date: Date): string;
  * TODO @Dushusir: Internationalization and more format support, can be reused when editing and saving cells, like "2020年1月1日"
  */
 export declare function isValidDateStr(dateStr: string): boolean;
-export declare function parseFormattedDate(value: string): numfmt.ParseData | null;
-export declare function parseFormattedTime(value: string): numfmt.ParseData | null;
+export declare function parseFormattedDate(value: string): numfmt.ParseData<number> | null;
+export declare function parseFormattedTime(value: string): numfmt.ParseData<number> | null;
 export declare function isDate(format: string): boolean;
 export declare function isValidWeekend(weekend: number | string): boolean;
 export declare function getWeekendArray(weekend: number | string): number[];

package/lib/types/basics/regex.d.ts

@@ -32,10 +32,10 @@ export declare const REFERENCE_REGEX_SINGLE_ROW = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\
 export declare const REFERENCE_REGEX_SINGLE_ROW_PRECOMPILING: RegExp;
 export declare const REFERENCE_REGEX_SINGLE_COLUMN = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[A-Za-z]+$";
 export declare const REFERENCE_REGEX_SINGLE_COLUMN_PRECOMPILING: RegExp;
-export declare const REFERENCE_TABLE_ALL_COLUMN_REGEX = "^(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+$";
-export declare const REFERENCE_TABLE_SINGLE_COLUMN_REGEX = "^(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[((?<!#).)*\\]|\\[\\[#.+\\]\\s*?,\\s*?\\[((?<!#).)*\\]\\])+$";
-export declare const REFERENCE_TABLE_MULTIPLE_COLUMN_REGEX = "^(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[\\[((?<!#).)*\\]\\s*?:\\s*?\\[((?<!#).)*\\]\\])?$|^((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[\\[#.+\\]\\s*?,\\s*?\\[((?<!#).)*\\]\\s*?:\\s*?\\[((?<!#).)*\\]\\])?$";
-export declare const REFERENCE_TABLE_TITLE_ONLY_ANY_HASH_REGEX = "^(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+\\[\\s*#([^\\]]+)\\s*\\]$";
+export declare const REFERENCE_TABLE_ALL_COLUMN_REGEX = "^(?:(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+$";
+export declare const REFERENCE_TABLE_SINGLE_COLUMN_REGEX = "^(?:(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[((?<!#)[\\s\\S])*\\]|\\[\\[#.+\\]\\s*?,\\s*?\\[((?<!#)[\\s\\S])*\\]\\])+$";
+export declare const REFERENCE_TABLE_MULTIPLE_COLUMN_REGEX = "^(?:(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[\\[((?<!#)[\\s\\S])*\\]\\s*?:\\s*?\\[((?<!#)[\\s\\S])*\\]\\])?$|^(?:(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[\\[#.+\\]\\s*?,\\s*?\\[((?<!#)[\\s\\S])*\\]\\s*?:\\s*?\\[((?<!#)[\\s\\S])*\\]\\])?$";
+export declare const REFERENCE_TABLE_TITLE_ONLY_ANY_HASH_REGEX = "^(?:(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?((?![~!@#$%^&*()_+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+\\[\\s*#([^\\]]+)\\s*\\]$";
 export declare const REFERENCE_TABLE_ALL_COLUMN_REGEX_PRECOMPILING: RegExp;
 export declare const REFERENCE_TABLE_SINGLE_COLUMN_REGEX_PRECOMPILING: RegExp;
 export declare const REFERENCE_TABLE_MULTIPLE_COLUMN_REGEX_PRECOMPILING: RegExp;

package/lib/types/commands/mutations/set-super-table.mutation.d.ts

@@ -20,6 +20,9 @@ export interface ISetSuperTableMutationSearchParam {
     unitId: string;
     tableName: string;
 }
+export interface IRemoveSuperTableMutationParam extends ISetSuperTableMutationSearchParam {
+    reference?: Pick<ISuperTable, 'sheetId' | 'range'>;
+}
 export interface ISetSuperTableMutationParam extends ISetSuperTableMutationSearchParam {
     oldTableName?: string;
     reference: ISuperTable;
@@ -29,5 +32,5 @@ export interface ISetSuperTableMutationParam extends ISetSuperTableMutationSearc
  * It requires setting local to true during execution.
  */
 export declare const SetSuperTableMutation: IMutation<ISetSuperTableMutationParam>;
-export declare const RemoveSuperTableMutation: IMutation<ISetSuperTableMutationSearchParam>;
+export declare const RemoveSuperTableMutation: IMutation<IRemoveSuperTableMutationParam>;
 export declare const SetSuperTableOptionMutation: IMutation<ISuperTableOptionParam>;

package/lib/types/controllers/formula-calculation-trigger.controller.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Disposable, LifecycleService } from '@univerjs/core';
+import { FormulaCalculationTriggerService } from '../services/formula-calculation-trigger.service';
+export declare class FormulaCalculationTriggerController extends Disposable {
+    constructor(formulaCalculationTriggerService: FormulaCalculationTriggerService, lifecycleService: LifecycleService);
+}

package/lib/types/controllers/super-table-active-dirty.controller.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Disposable } from '@univerjs/core';
+import { IActiveDirtyManagerService } from '../services/active-dirty-manager.service';
+export declare class SuperTableActiveDirtyController extends Disposable {
+    private readonly _activeDirtyManagerService;
+    constructor(_activeDirtyManagerService: IActiveDirtyManagerService);
+    private _initialize;
+}

package/lib/types/engine/analysis/lexer-node.d.ts

@@ -15,9 +15,9 @@
  */
 import type { Nullable } from '@univerjs/core';
 import type { LambdaPrivacyVarType } from '../ast-node/base-ast-node';
-interface LexerNodeJson {
+interface ILexerNodeJson {
     token: string;
-    children: Array<LexerNodeJson | string>;
+    children: Array<ILexerNodeJson | string>;
 }
 export declare class LexerNode {
     private _parent;
@@ -56,7 +56,7 @@ export declare class LexerNode {
         token: string;
         st: number;
         ed: number;
-        children: (string | LexerNodeJson)[];
+        children: (string | ILexerNodeJson)[];
     };
     private _getIndexInParent;
 }

package/lib/types/engine/analysis/lexer-tree-builder.d.ts

@@ -26,7 +26,8 @@ export declare const FormulaLexerNodeCache: FormulaAstLRU<LexerNode>;
 export declare const FormulaSequenceNodeCache: FormulaAstLRU<(string | ISequenceNode)[]>;
 interface IInjectDefinedNameParam {
     unitId: Nullable<string>;
-    getValueByName(unitId: string, name: string): Nullable<IDefinedNamesServiceParam>;
+    sheetId?: Nullable<string>;
+    getValueByName(unitId: string, name: string, sheetId?: Nullable<string>): Nullable<IDefinedNamesServiceParam>;
     getDirtyDefinedNameMap(): IDirtyUnitDefinedNameMap;
     getSheetName: (unitId: string, sheetId: string) => string;
 }

package/lib/types/engine/analysis/lexer.d.ts

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { Nullable } from '@univerjs/core';
 import { Disposable } from '@univerjs/core';
 import { IFormulaCurrentConfigService } from '../../services/current-data.service';
 import { IDefinedNamesService } from '../../services/defined-names.service';
@@ -22,5 +23,5 @@ export declare class Lexer extends Disposable {
     private readonly _lexerTreeBuilder;
     private readonly _formulaCurrentConfigService;
     constructor(_definedNamesService: IDefinedNamesService, _lexerTreeBuilder: LexerTreeBuilder, _formulaCurrentConfigService: IFormulaCurrentConfigService);
-    treeBuilder(formulaString: string, transformSuffix?: boolean): import("../..").ErrorType.VALUE | import("./lexer-node").LexerNode | (string | import("./lexer-node").LexerNode)[] | undefined;
+    treeBuilder(formulaString: string, transformSuffix?: boolean, unitId?: Nullable<string>): import("../..").ErrorType.VALUE | import("./lexer-node").LexerNode | (string | import("./lexer-node").LexerNode)[] | undefined;
 }

package/lib/types/engine/analysis/parser.d.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 import type { Nullable } from '@univerjs/core';
-import type { BaseAstNode } from '../ast-node/base-ast-node';
 import { Disposable } from '@univerjs/core';
 import { IFormulaRuntimeService } from '../../services/runtime.service';
 import { AstRootNodeFactory } from '../ast-node/ast-root-node';
+import { BaseAstNode } from '../ast-node/base-ast-node';
 import { FunctionNodeFactory } from '../ast-node/function-node';
 import { LambdaNodeFactory } from '../ast-node/lambda-node';
 import { LambdaParameterNodeFactory } from '../ast-node/lambda-parameter-node';
@@ -48,5 +48,6 @@ export declare class AstTreeBuilder extends Disposable {
     private _changeLetToLambda;
     private _parse;
     private _checkAstNode;
+    private _createGroupByAggregatorTokenNode;
     private _initializeAstNode;
 }

package/lib/types/engine/ast-node/function-node.d.ts

@@ -22,6 +22,7 @@ import { IFormulaCurrentConfigService } from '../../services/current-data.servic
 import { IDefinedNamesService } from '../../services/defined-names.service';
 import { IFunctionService } from '../../services/function.service';
 import { IFormulaRuntimeService } from '../../services/runtime.service';
+import { IFormulaUnitReferenceResolver } from '../../services/unit-reference-resolver.service';
 import { BaseAstNode } from './base-ast-node';
 import { BaseAstNodeFactory } from './base-ast-node-factory';
 import { NodeType } from './node-type';
@@ -31,15 +32,19 @@ export declare class FunctionNode extends BaseAstNode {
     private _runtimeService;
     private _definedNamesService;
     private _formulaDataModel;
-    constructor(token: string, _functionExecutor: BaseFunction, _currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, _definedNamesService: IDefinedNamesService, _formulaDataModel: FormulaDataModel);
+    private _unitReferenceResolver;
+    constructor(token: string, _functionExecutor: BaseFunction, _currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, _definedNamesService: IDefinedNamesService, _formulaDataModel: FormulaDataModel, _unitReferenceResolver: IFormulaUnitReferenceResolver);
     get nodeType(): NodeType;
     executeAsync(): Promise<AstNodePromiseType>;
     execute(): void;
+    private _collectVariants;
+    private _getChildVariant;
     isFunctionExecutorArgumentsIgnoreNumberPattern(): boolean;
     /**
      * If it contains an array formula, set the current cell to the cache and send itself as a ref outward
      */
     private _setEmbeddedArrayFormulaToResult;
+    private _normalizeTopLevelLegacyArrayResult;
     /**
      * Compatibility handling for special functions.
      */
@@ -59,6 +64,7 @@ export declare class FunctionNode extends BaseAstNode {
     private _handleAddressFunction;
     private _mapVariantsToValues;
     private _calculate;
+    private _calculateAst;
     private _calculateAsync;
     private _setDefinedNamesForFunction;
     private _setRefInfo;
@@ -80,7 +86,8 @@ export declare class FunctionNodeFactory extends BaseAstNodeFactory {
     private readonly _definedNamesService;
     private readonly _injector;
     private readonly _formulaDataModel;
-    constructor(_functionService: IFunctionService, _currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, _definedNamesService: IDefinedNamesService, _injector: Injector, _formulaDataModel: FormulaDataModel);
+    private readonly _unitReferenceResolver;
+    constructor(_functionService: IFunctionService, _currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, _definedNamesService: IDefinedNamesService, _injector: Injector, _formulaDataModel: FormulaDataModel, _unitReferenceResolver: IFormulaUnitReferenceResolver);
     get zIndex(): number;
     create(token: string): BaseAstNode;
     checkAndCreateNodeType(param: LexerNode | string): BaseAstNode | undefined;

package/lib/types/engine/ast-node/operator-node.d.ts

@@ -26,6 +26,7 @@ export declare class OperatorNode extends BaseAstNode {
     constructor(operatorString: string, _functionExecutor: BaseFunction, _runtimeService: IFormulaRuntimeService);
     get nodeType(): NodeType;
     execute(): void;
+    private _referenceToOperatorValue;
     /**
      * If it contains an array formula, set the current cell to the cache and send itself as a ref outward
      */

package/lib/types/engine/ast-node/prefix-node.d.ts

@@ -29,6 +29,7 @@ export declare class PrefixNode extends BaseAstNode {
     get nodeType(): NodeType;
     execute(): void;
     private _handlerAT;
+    private _preserveAtRangeForFormula2LookupArray;
 }
 export declare class PrefixNodeFactory extends BaseAstNodeFactory {
     private readonly _functionService;

package/lib/types/engine/ast-node/reference-node.d.ts

@@ -17,23 +17,31 @@ import { IFormulaCurrentConfigService } from '../../services/current-data.servic
 import { IFunctionService } from '../../services/function.service';
 import { IFormulaRuntimeService } from '../../services/runtime.service';
 import { ISuperTableService } from '../../services/super-table.service';
+import { IFormulaUnitReferenceResolver } from '../../services/unit-reference-resolver.service';
 import { LexerNode } from '../analysis/lexer-node';
-import { TableReferenceObject } from '../reference-object/table-reference-object';
 import { ReferenceObjectType } from '../utils/value-object';
 import { BaseAstNode } from './base-ast-node';
 import { BaseAstNodeFactory } from './base-ast-node-factory';
 import { NodeType } from './node-type';
+interface ITableReferenceDescriptor {
+    unitQualifier: string;
+    tableName: string;
+    columnStruct: string | undefined;
+}
 export declare class ReferenceNode extends BaseAstNode {
     private _currentConfigService;
     private _runtimeService;
     private _referenceObjectType;
+    private _unitReferenceResolver;
+    private _superTableService;
     private _isPrepareMerge;
-    private _tableReferenceObject?;
+    private _tableReference?;
     private _refOffsetX;
     private _refOffsetY;
-    constructor(_currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, operatorString: string, _referenceObjectType: ReferenceObjectType, _isPrepareMerge?: boolean, _tableReferenceObject?: TableReferenceObject | undefined);
+    constructor(_currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, operatorString: string, _referenceObjectType: ReferenceObjectType, _unitReferenceResolver: IFormulaUnitReferenceResolver, _superTableService: ISuperTableService, _isPrepareMerge?: boolean, _tableReference?: ITableReferenceDescriptor | undefined);
     get nodeType(): NodeType;
     execute(): void;
+    private _configureReferenceObject;
     setRefOffset(x?: number, y?: number): void;
     getRefOffset(): {
         x: number;
@@ -45,7 +53,8 @@ export declare class ReferenceNodeFactory extends BaseAstNodeFactory {
     private readonly _formulaRuntimeService;
     private readonly _functionService;
     private readonly _superTableService;
-    constructor(_currentConfigService: IFormulaCurrentConfigService, _formulaRuntimeService: IFormulaRuntimeService, _functionService: IFunctionService, _superTableService: ISuperTableService);
+    private readonly _unitReferenceResolver;
+    constructor(_currentConfigService: IFormulaCurrentConfigService, _formulaRuntimeService: IFormulaRuntimeService, _functionService: IFunctionService, _superTableService: ISuperTableService, _unitReferenceResolver: IFormulaUnitReferenceResolver);
     get zIndex(): number;
     checkAndCreateNodeType(param: LexerNode | string): ReferenceNode | undefined;
     private _getTableMap;
@@ -54,3 +63,4 @@ export declare class ReferenceNodeFactory extends BaseAstNodeFactory {
     private _checkTokenIsTableReference;
     private _checkParentIsUnionOperator;
 }
+export {};

package/lib/types/engine/interpreter/interpreter.d.ts

@@ -30,4 +30,15 @@ export declare class Interpreter extends Disposable {
     private _checkAsyncNode;
     private _executeAsync;
     private _execute;
+    private _executeLazyFunctionAsync;
+    private _executeLazyFunction;
+    private _executeLazyIfAsync;
+    private _executeLazyIf;
+    private _executeLazyIfErrorAsync;
+    private _executeLazyIfError;
+    private _toLazyIfErrorValue;
+    private _toLazyIfSelectedValue;
+    private _implicitLazyIfReferenceValue;
+    private _preserveLazyIfSelectedReferenceArray;
+    private _implicitLazyIfArrayValue;
 }

package/lib/types/engine/reference-object/base-reference-object.d.ts

@@ -34,6 +34,7 @@ export declare class BaseReferenceObject extends ObjectClassType {
     private _filteredOutRows;
     private _defaultUnitId;
     private _forcedUnitId;
+    private _unitQualifier;
     private _runtimeData;
     private _arrayFormulaCellData;
     private _arrayFormulaRange;
@@ -63,6 +64,8 @@ export declare class BaseReferenceObject extends ObjectClassType {
     getUnitId(): string;
     getSheetId(): string;
     setForcedUnitIdDirect(unitId: string): void;
+    setUnitQualifier(unitQualifier: string): void;
+    getUnitQualifier(): string;
     getForcedUnitId(): string;
     setForcedSheetId(sheetNameMap: IUnitSheetNameMap): void;
     setForcedSheetIdDirect(sheetId: string): void;

package/lib/types/engine/reference-object/cell-reference-object.d.ts

@@ -20,6 +20,7 @@ import { RangeReferenceObject } from './range-reference-object';
 export declare class CellReferenceObject extends BaseReferenceObject {
     constructor(token: string);
     isCell(): boolean;
+    isExceedRange(): boolean;
     unionBy(referenceObject: BaseReferenceObject): ErrorValueObject | RangeReferenceObject;
     unionRange(rangeData1: IRange, rangeData2: IRange): IRange;
     private _createRange;

package/lib/types/engine/reference-object/table-reference-object.d.ts

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { ICellData, Nullable } from '@univerjs/core';
 import type { ISuperTable, IUnitSheetNameMap } from '../../basics/common';
 import { TableOptionType } from '../../basics/common';
 import { BaseReferenceObject } from './base-reference-object';
@@ -55,6 +56,7 @@ export declare class TableReferenceObject extends BaseReferenceObject {
     /** Section text to enum mapping ('#All', '#Data', '#Headers', '#Totals', '#This Row') */
     _tableOptionMap: Map<string, TableOptionType>);
     getRangeData(): import("@univerjs/core").IRange;
+    getCellData(row: number, column: number): Nullable<ICellData>;
     getRefOffset(): {
         x: number;
         y: number;

package/lib/types/engine/utils/generate-ast-node.d.ts

@@ -21,5 +21,5 @@ import type { AstRootNode } from '../ast-node/ast-root-node';
 import type { IFormulaDependencyTree } from '../dependency/dependency-tree';
 import { FormulaAstLRU } from '../../basics/cache-lru';
 export declare const FORMULA_AST_CACHE: FormulaAstLRU<AstRootNode>;
-export declare function generateAstNode(unitId: string, formulaString: string, lexer: Lexer, astTreeBuilder: AstTreeBuilder, currentConfigService: IFormulaCurrentConfigService): AstRootNode;
+export declare function generateAstNode(unitId: string, formulaString: string, lexer: Lexer, astTreeBuilder: AstTreeBuilder, currentConfigService: IFormulaCurrentConfigService, subUnitId?: string): AstRootNode;
 export declare function includeDefinedName(tree: IFormulaDependencyTree, node: Nullable<AstRootNode>, currentConfigService: IFormulaCurrentConfigService): boolean;

package/lib/types/engine/utils/math-kit.d.ts

@@ -13,6 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Since Excel follows the IEEE 754 specification, it only handles precision issues when displaying cells. For example, =0.1+0.2, the stored value in XML is 0.30000000000000004, and the displayed value is 0.3. The accuracy of the calculation process does not need to be considered. We only focus on the accuracy of the calculation results. Any result is processed within 15 digits.
+
+ Reference https://en.wikipedia.org/wiki/Numeric_precision_in_Microsoft_Excel
+ */
 export declare function plus(a: number, b: number): number;
 export declare function minus(a: number, b: number): number;
 export declare function multiply(a: number, b: number): number;

package/lib/types/engine/utils/reference.d.ts

@@ -56,6 +56,8 @@ export declare function singleReferenceToGrid(refBody: string): {
 export declare function handleRefStringInfo(refString: string): {
     refBody: string;
     sheetName: string;
+    unitQualifier: string;
+    /** @deprecated Use unitQualifier. Kept for reference-grid compatibility. */
     unitId: string;
 };
 export declare function deserializeRangeWithSheet(refString: string): IUnitRangeName;
@@ -102,11 +104,7 @@ export declare function quoteSheetName(name: string): string;
  */
 export declare function unquoteSheetName(name: string): string;
 export declare function splitTableStructuredRef(ref: string): {
-    tableName: string;
-    struct: string;
-    columnStruct?: undefined;
-} | {
+    unitQualifier: string;
     tableName: string;
     columnStruct: string;
-    struct?: undefined;
 };

package/lib/types/engine/utils/unit-qualifier.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Refactors only parsed reference qualifiers and INDIRECT literal references, never arbitrary text. */
+export declare function refactorFormulaUnitQualifier(formula: string, oldName: string, newName: string): string;
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */

package/lib/types/engine/value-object/array-value-object.d.ts

@@ -41,6 +41,8 @@ export declare class ArrayValueObject extends BaseValueObject {
     private _sheetId;
     private _currentRow;
     private _currentColumn;
+    private _useInvertedIndexCache;
+    private _legacyImplicitForAggregate;
     private _sliceCache;
     private _flattenCache;
     /**
@@ -62,6 +64,9 @@ export declare class ArrayValueObject extends BaseValueObject {
     getSheetId(): string;
     getCurrentRow(): number;
     getCurrentColumn(): number;
+    usesInvertedIndexCache(): boolean;
+    usesLegacyImplicitForAggregate(): boolean;
+    setLegacyImplicitForAggregate(value: boolean): void;
     getArrayValue(): Nullable<BaseValueObject>[][];
     setArrayValue(value: BaseValueObject[][]): void;
     isArray(): boolean;

package/lib/types/engine/value-object/base-value-object.d.ts

@@ -28,6 +28,8 @@ export interface IArrayValueObject {
     sheetId: string;
     row: number;
     column: number;
+    legacyImplicitForAggregate?: boolean;
+    useInvertedIndexCache?: boolean;
 }
 export declare class BaseValueObject extends ObjectClassType {
     private _rawValue;
@@ -158,6 +160,8 @@ export declare class BaseValueObject extends ObjectClassType {
     convertToNumberObjectValue(): BaseValueObject;
     convertToBooleanObjectValue(): BaseValueObject;
 }
+export declare function formatValueForFormulaText(value: string | number | boolean | null): string;
+export declare function formatNumberForFormulaText(value: number): string;
 export declare const ErrorValueObjectCache: FormulaAstLRU<ErrorValueObject>;
 export declare class ErrorValueObject extends BaseValueObject {
     private _errorType;
@@ -169,4 +173,6 @@ export declare class ErrorValueObject extends BaseValueObject {
     getErrorContent(): string;
     isEqualType(object: ObjectClassType): boolean;
     isError(): boolean;
+    concatenateFront(_valueObject: BaseValueObject): BaseValueObject;
+    concatenateBack(_valueObject: BaseValueObject): BaseValueObject;
 }

package/lib/types/facade/f-formula.d.ts

@@ -119,10 +119,13 @@ export declare class FFormula extends FBase {
     calculationEnd(callback: (functionsExecutedState: FormulaExecutedStateType) => void): IDisposable;
     /**
      * @deprecated Use `onCalculationResultApplied` instead.
+     * @param {number} [timeout] The timeout in milliseconds. Defaults to 30000.
+     * @returns {Promise<boolean>} Whether computing completed before timeout.
      */
     whenComputingCompleteAsync(timeout?: number): Promise<boolean>;
     /**
      * @deprecated Use `onCalculationResultApplied` instead.
+     * @returns {Promise<void>} A promise that resolves when calculation ends.
      */
     onCalculationEnd(): Promise<void>;
     /**
@@ -249,11 +252,11 @@ export declare class FFormula extends FBase {
      * dependency-calculation command for the given unit, sheet, and cell location,
      * and returns the computed dependency tree when the calculation is completed.
      *
-     * @param param The target cell location:
-     *   - `unitId`  The workbook ID.
-     *   - `sheetId` The sheet ID.
-     *   - `row`     The zero-based row index.
-     *   - `column`  The zero-based column index.
+     * @param {object} param The target cell location.
+     * @param {string} param.unitId The workbook ID.
+     * @param {string} param.sheetId The sheet ID.
+     * @param {number} param.row The zero-based row index.
+     * @param {number} param.column The zero-based column index.
      *
      * @param {number} [timeout]
      *        Optional timeout in milliseconds. If no result is received within this
@@ -462,6 +465,7 @@ export declare class FFormula extends FBase {
      * ```
      *
      * @param formulaString The formula string to parse (with or without leading `=`)
+     * @param unitId The workbook unit id used to resolve defined names and tables.
      * @returns A formula expression tree describing the hierarchical structure of the formula
      */
     getFormulaExpressTree(formulaString: string, unitId: string): IExprTreeNode | null;

package/lib/types/functions/base-function.d.ts

@@ -15,6 +15,7 @@
  */
 import type { IRange, LocaleType, Nullable } from '@univerjs/core';
 import type { IFunctionNames } from '../basics/function';
+import type { BaseAstNode } from '../engine/ast-node/base-ast-node';
 import type { BaseReferenceObject, FunctionVariantType, NodeValueType } from '../engine/reference-object/base-reference-object';
 import type { ArrayBinarySearchType } from '../engine/utils/compare';
 import type { ArrayValueObject } from '../engine/value-object/array-value-object';
@@ -22,6 +23,7 @@ import type { BaseValueObject } from '../engine/value-object/base-value-object';
 import type { FormulaFunctionResultValueType, FormulaFunctionValueType } from '../engine/value-object/primitive-object';
 import type { FormulaDataModel } from '../models/formula-data.model';
 import type { IDefinedNameMapItem } from '../services/defined-names.service';
+import type { IFormulaUnitReferenceResolver } from '../services/unit-reference-resolver.service';
 import { ArrayOrderSearchType } from '../engine/utils/compare';
 import { ErrorValueObject } from '../engine/value-object/base-value-object';
 export declare class BaseFunction {
@@ -30,11 +32,14 @@ export declare class BaseFunction {
     private _subUnitId;
     private _row;
     private _column;
+    private _currentFormulaRowCount;
+    private _currentFormulaColumnCount;
     private _definedNames;
     private _locale;
     private _sheetOrder;
     private _sheetNameMap;
     protected _formulaDataModel: Nullable<FormulaDataModel>;
+    protected _unitReferenceResolver: Nullable<IFormulaUnitReferenceResolver>;
     protected _rowCount: number;
     protected _columnCount: number;
     /**
@@ -57,6 +62,8 @@ export declare class BaseFunction {
      * Whether the function needs function methods in FormulaDataModel
      */
     needsFormulaDataModel: boolean;
+    /** Whether the function resolves external Unit qualifiers. */
+    needsUnitReferenceResolver: boolean;
     /**
      * Whether the function needs the number of rows and columns in the sheet
      */
@@ -65,6 +72,15 @@ export declare class BaseFunction {
      * Whether the function needs to filter out rows
      */
     needsFilteredOutRows: boolean;
+    /**
+     * Whether the function needs unevaluated AST children.
+     */
+    needsAstChildren: boolean;
+    /**
+     * Legacy CSE-style array functions should write only the first result cell
+     * when they are used as a top-level normal formula.
+     */
+    returnsLegacyArrayAsScalar: boolean;
     /**
      * Minimum number of parameters
      */
@@ -79,6 +95,8 @@ export declare class BaseFunction {
     get subUnitId(): Nullable<string>;
     get row(): number;
     get column(): number;
+    get currentFormulaRowCount(): number;
+    get currentFormulaColumnCount(): number;
     dispose(): void;
     /**
      * In Excel, to inject a defined name into a function that has positioning capabilities,
@@ -103,14 +121,16 @@ export declare class BaseFunction {
         };
     }): void;
     setFormulaDataModel(_formulaDataModel: FormulaDataModel): void;
+    setUnitReferenceResolver(unitReferenceResolver: IFormulaUnitReferenceResolver): void;
     setSheetRowColumnCount(rowCount: number, columnCount: number): void;
     isAsync(): boolean;
     isAddress(): boolean;
     isCustom(): boolean;
     isArgumentsIgnoreNumberPattern(): boolean;
-    setRefInfo(unitId: string, subUnitId: string, row: number, column: number): void;
+    setRefInfo(unitId: string, subUnitId: string, row: number, column: number, rowCount?: number, columnCount?: number): void;
     calculateCustom(...arg: Array<FormulaFunctionValueType>): FormulaFunctionResultValueType | Promise<FormulaFunctionResultValueType>;
     calculate(...arg: BaseValueObject[]): NodeValueType;
+    calculateAst(_children: BaseAstNode[], _getVariant: (node: BaseAstNode) => Nullable<FunctionVariantType>): NodeValueType;
     checkArrayType(variant: FunctionVariantType): boolean;
     /**
      * Starting with 1