@univerjs/engine-formula 0.11.0 → 0.12.0-nightly.202511220628

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

@@ -1,4 +1,5 @@
-import { BooleanNumber, ICellData, IColumnData, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IRange, IRowData, IUnitRange, Nullable, ObjectMatrix, Styles } from '@univerjs/core';
+import { ICellData, IColumnData, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IRange, IRowData, IUnitRange, Nullable, ObjectMatrix, Styles } from '@univerjs/core';
+import { IImageFormulaInfo } from '../engine/value-object/primitive-object';
 export declare const ERROR_VALUE_OBJECT_CLASS_TYPE = "errorValueObject";
 export declare const ASYNC_OBJECT_CLASS_TYPE = "asyncObject";
 export declare const REFERENCE_OBJECT_CLASS_TYPE = "referenceObject";
@@ -92,11 +93,27 @@ export interface IArrayFormulaRangeType {
         [sheetId: string]: IObjectMatrixPrimitiveType<IRange>;
     }>;
 }
+export interface IArrayFormulaEmbeddedMap {
+    [unitId: string]: Nullable<{
+        [sheetId: string]: IObjectMatrixPrimitiveType<boolean>;
+    }>;
+}
 export interface IFeatureDirtyRangeType {
     [unitId: string]: Nullable<{
         [sheetId: string]: IRange[];
     }>;
 }
+export interface IRuntimeImageFormulaDataType extends IImageFormulaInfo {
+    unitId: string;
+    sheetId: string;
+    row: number;
+    column: number;
+}
+export interface IUnitImageFormulaDataType {
+    [unitId: string]: Nullable<{
+        [sheetId: string]: ObjectMatrix<Nullable<IImageFormulaInfo>>;
+    }>;
+}
 export interface IArrayFormulaUnitCellType extends IRuntimeUnitDataPrimitiveType {
 }
 export interface IFormulaData {
@@ -139,7 +156,6 @@ export interface IOtherFormulaDataItem {
 }
 export interface ISuperTable {
     sheetId: string;
-    hasCustomTitle: BooleanNumber;
     titleMap: Map<string, number>;
     range: IRange;
 }
@@ -147,7 +163,8 @@ export declare enum TableOptionType {
     ALL = "#All",
     DATA = "#Data",
     HEADERS = "#Headers",
-    TOTALS = "#Totals"
+    TOTALS = "#Totals",
+    THIS_ROW = "#This Row"
 }
 export interface IUnitExcludedCell {
     [unitId: string]: Nullable<{

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

@@ -86,7 +86,11 @@ export declare enum FunctionType {
     /**
      * Defined name
      */
-    DefinedName = 16
+    DefinedName = 16,
+    /**
+     * Super Table name
+     */
+    Table = 17
 }
 export interface IFunctionParam {
     /**

package/lib/types/basics/inverted-index-cache.d.ts

@@ -1,4 +1,5 @@
 import { NumericTuple } from '@flatten-js/interval-tree';
+export declare const DEFAULT_EMPTY_CELL_KEY: unique symbol;
 export declare class InvertedIndexCache {
     /**
      * {
@@ -14,9 +15,9 @@ export declare class InvertedIndexCache {
      */
     private _cache;
     private _continueBuildingCache;
-    set(unitId: string, sheetId: string, column: number, value: string | number | boolean | null, row: number, isForceUpdate?: boolean): void;
-    getCellValuePositions(unitId: string, sheetId: string, column: number): Map<string | number | boolean | null, Set<number>> | undefined;
-    getCellPositions(unitId: string, sheetId: string, column: number, value: string | number | boolean, rowsInCache: NumericTuple[]): number[] | undefined;
+    set(unitId: string, sheetId: string, column: number, value: string | number | boolean | null | symbol, row: number, isForceUpdate?: boolean): void;
+    getCellValuePositions(unitId: string, sheetId: string, column: number): Map<string | number | boolean | symbol | null, Set<number>> | undefined;
+    getCellPositions(unitId: string, sheetId: string, column: number, value: string | number | boolean | null | symbol, rowsInCache: NumericTuple[]): number[] | undefined;
     setContinueBuildingCache(unitId: string, sheetId: string, column: number, startRow: number, endRow: number): void;
     shouldContinueBuildingCache(unitId: string, sheetId: string, column: number, row: number): boolean;
     canUseCache(unitId: string, sheetId: string, column: number, rangeStartRow: number, rangeEndRow: number): {

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

@@ -35,7 +35,12 @@ 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 SUPER_TABLE_COLUMN_REGEX = "[.*?]";
+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_PRECOMPILING: RegExp;
+export declare const REFERENCE_TABLE_SINGLE_COLUMN_REGEX_PRECOMPILING: RegExp;
+export declare const REFERENCE_TABLE_MULTIPLE_COLUMN_REGEX_PRECOMPILING: RegExp;
+export declare const REFERENCE_TABLE_TITLE_ONLY_ANY_HASH_REGEX_PRECOMPILING: RegExp;
+export declare const SUPER_TABLE_COLUMN_REGEX = "\\[[^\\]]*?]";
 export declare const SUPER_TABLE_COLUMN_REGEX_PRECOMPILING: RegExp;
 export declare const ARRAY_VALUE_REGEX = "{.*?}";
 export declare const ARRAY_VALUE_REGEX_PRECOMPILING: RegExp;
@@ -46,5 +51,9 @@ export declare function regexTestColumn(token: string): boolean;
 export declare function regexTestSingleRow(token: string): boolean;
 export declare function regexTestSingleColumn(token: string): boolean;
 export declare function regexTestSuperTableColumn(token: string): boolean;
+export declare function regexTestReferenceTableAllColumn(token: string): boolean;
+export declare function regexTestReferenceTableSingleColumn(token: string): boolean;
+export declare function regexTestReferenceTableMultipleColumn(token: string): boolean;
+export declare function regexTestReferenceTableTitleOnlyAnyHash(token: string): boolean;
 export declare function regexTestArrayValue(token: string): boolean;
 export declare function isReferenceString(refString: string): boolean;

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

@@ -1,4 +1,7 @@
+import { BaseReferenceObject, FunctionVariantType } from '../engine/reference-object/base-reference-object';
+import { MultiAreaReferenceObject } from '../engine/reference-object/multi-area-reference-object';
 import { BaseValueObject, ErrorValueObject } from '../engine/value-object/base-value-object';
+import { FormulaDataModel } from '../models/formula-data.model';
 export declare function betaCDF(x: number, alpha: number, beta: number): number;
 export declare function betaPDF(x: number, alpha: number, beta: number): number;
 export declare function betaINV(probability: number, alpha: number, beta: number): number;
@@ -67,3 +70,53 @@ export declare function getKnownsArrayCoefficients(knownYsValues: number[][], kn
     newX: number[][];
     XTXInverse: number[][];
 };
+/**
+ * Parse aggregate data references into multi-area refs and normal refs, currently only used in functions like SUBTOTAL and AGGREGATE.
+ * If there is any invalid reference, return isError as true.
+ */
+export declare function parseAggregateDataRefs(refs: FunctionVariantType[]): {
+    isError: boolean;
+    multiAreaRefs: MultiAreaReferenceObject[];
+    normalRefs: BaseReferenceObject[];
+};
+export declare enum AggregateFunctionType {
+    AVERAGE = "AVERAGE",
+    COUNT = "COUNT",
+    COUNTA = "COUNTA",
+    MAX = "MAX",
+    MIN = "MIN",
+    PRODUCT = "PRODUCT",
+    STDEV = "STDEV",
+    STDEV_S = "STDEV.S",
+    STDEVP = "STDEVP",
+    STDEV_P = "STDEV.P",
+    SUM = "SUM",
+    VAR = "VAR",
+    VAR_S = "VAR.S",
+    VARP = "VARP",
+    VAR_P = "VAR.P",
+    MEDIAN = "MEDIAN",
+    MODE_SNGL = "MODE.SNGL"
+}
+export type modeSnglValueCountMapType = Record<number, {
+    count: number;
+    order: number;
+}>;
+export declare function getModeSnglResult(valueCountMap: modeSnglValueCountMapType, valueMaxCount: number): BaseValueObject;
+export interface IAggregateIgnoreOptions {
+    ignoreRowHidden: boolean;
+    ignoreErrorValues: boolean;
+    ignoreNested: boolean;
+}
+export declare function getAggregateResult(options: {
+    type: AggregateFunctionType;
+    formulaDataModel: FormulaDataModel;
+} & IAggregateIgnoreOptions, refs: BaseReferenceObject[]): BaseValueObject;
+export declare function getArrayValuesByAggregateIgnoreOptions(array: FunctionVariantType, options?: IAggregateIgnoreOptions, formulaDataModel?: FormulaDataModel): number[] | ErrorValueObject;
+export declare function getMedianResult(array: number[]): BaseValueObject;
+export declare function getLargeResult(array: number[], k: number): BaseValueObject;
+export declare function getSmallResult(array: number[], k: number): BaseValueObject;
+export declare function getPercentileIncResult(array: number[], k: number): BaseValueObject;
+export declare function getPercentileExcResult(array: number[], k: number): BaseValueObject;
+export declare function getQuartileIncResult(array: number[], quart: number): BaseValueObject;
+export declare function getQuartileExcResult(array: number[], quart: number): BaseValueObject;

package/lib/types/commands/mutations/set-array-formula-data.mutation.d.ts

@@ -1,8 +1,9 @@
 import { IMutation } from '@univerjs/core';
-import { IArrayFormulaRangeType, IArrayFormulaUnitCellType } from '../../basics/common';
+import { IArrayFormulaEmbeddedMap, IArrayFormulaRangeType, IArrayFormulaUnitCellType } from '../../basics/common';
 export interface ISetArrayFormulaDataMutationParams {
     arrayFormulaRange: IArrayFormulaRangeType;
     arrayFormulaCellData: IArrayFormulaUnitCellType;
+    arrayFormulaEmbedded: IArrayFormulaEmbeddedMap;
 }
 /**
  * There is no need to process data here, it is used as the main thread to send data to the worker. The main thread has already updated the data in advance, and there is no need to update it again here.

package/lib/types/commands/mutations/set-defined-name.mutation.d.ts

@@ -9,6 +9,7 @@ export interface ISetDefinedNameMutationParam extends ISetDefinedNameMutationSea
     comment?: string;
     localSheetId?: string;
     hidden?: boolean;
+    formulaOrRefStringWithPrefix?: string;
 }
 /**
  * Generate undo mutation of a `SetDefinedNameMutation`

package/lib/types/commands/mutations/set-image-formula-data.mutation.d.ts

@@ -0,0 +1,9 @@
+import { IMutation } from '@univerjs/core';
+import { IRuntimeImageFormulaDataType } from '../../basics/common';
+export interface ISetImageFormulaDataMutationParams {
+    imageFormulaData: IRuntimeImageFormulaDataType[];
+}
+/**
+ * There is no need to process data here, it is used as the main thread to send data to the worker. The main thread has already updated the data in advance, and there is no need to update it again here.
+ */
+export declare const SetImageFormulaDataMutation: IMutation<ISetImageFormulaDataMutationParams>;

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

@@ -1,5 +1,6 @@
 import { Nullable, AbsoluteRefType, Disposable } from '@univerjs/core';
 import { IDirtyUnitSheetDefinedNameMap } from '../../basics/common';
+import { IFunctionNames } from '../../basics/function';
 import { IDefinedNamesServiceParam } from '../../services/defined-names.service';
 import { ISequenceArray, ISequenceNode } from '../utils/sequence';
 import { FormulaAstLRU } from '../../basics/cache-lru';
@@ -11,6 +12,7 @@ interface IInjectDefinedNameParam {
     unitId: Nullable<string>;
     getValueByName(unitId: string, name: string): Nullable<IDefinedNamesServiceParam>;
     getDirtyDefinedNameMap(): IDirtyUnitSheetDefinedNameMap;
+    getSheetName: (unitId: string, sheetId: string) => string;
 }
 export declare class LexerTreeBuilder extends Disposable {
     private _currentLexerNode;
@@ -54,6 +56,10 @@ export declare class LexerTreeBuilder extends Disposable {
      * =sum({}{})
      */
     private _formulaSpellCheck;
+    /**
+     * ={0,1,2,3,4,5,6} + {0;1;2;3;4;5;6}*7
+     */
+    private _passArrayOperator;
     getSequenceNode(sequenceArray: ISequenceArray[]): (string | ISequenceNode)[];
     private _processPushSequenceNode;
     private _getCurrentParamIndex;
@@ -71,6 +77,7 @@ export declare class LexerTreeBuilder extends Disposable {
     nodeMakerTest(formulaString: string): ErrorType.VALUE | (string | LexerNode)[] | undefined;
     treeBuilder(formulaString: string, transformSuffix?: boolean, injectDefinedNameParam?: IInjectDefinedNameParam): ErrorType.VALUE | LexerNode | (string | LexerNode)[] | undefined;
     private _handleDefinedName;
+    private _getHasSheetNameDefinedName;
     private _handleNestedDefinedName;
     private _simpleCheckDefinedName;
     private _checkDefinedNameDirty;
@@ -137,5 +144,6 @@ export declare class LexerTreeBuilder extends Disposable {
     private _nodeMaker;
     private _isScientificNotation;
     private _addSequenceArray;
+    getNewFormulaWithPrefix(formulaString: string, hasFunction: (functionToken: IFunctionNames) => boolean): string | null;
 }
 export {};

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

@@ -23,6 +23,7 @@ export declare class BaseAstNode {
     constructor(_token: string);
     dispose(): void;
     get nodeType(): NodeType;
+    resetCalculationState(): void;
     isAsync(): boolean;
     isAddress(): boolean;
     isForcedCalculateFunction(): boolean;

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

@@ -21,6 +21,10 @@ export declare class FunctionNode extends BaseAstNode {
     executeAsync(): Promise<AstNodePromiseType>;
     execute(): void;
     isFunctionExecutorArgumentsIgnoreNumberPattern(): boolean;
+    /**
+     * If it contains an array formula, set the current cell to the cache and send itself as a ref outward
+     */
+    private _setEmbeddedArrayFormulaToResult;
     /**
      * Compatibility handling for special functions.
      */

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

@@ -8,8 +8,9 @@ export declare class LambdaNode extends BaseAstNode {
     private _lambdaId;
     private _interpreter;
     private _lambdaPrivacyVarKeys;
+    private _runtimeService;
     private _isNotEmpty;
-    constructor(token: string, _lambdaId: string, _interpreter: Interpreter, _lambdaPrivacyVarKeys: string[]);
+    constructor(token: string, _lambdaId: string, _interpreter: Interpreter, _lambdaPrivacyVarKeys: string[], _runtimeService: IFormulaRuntimeService);
     get nodeType(): NodeType;
     setNotEmpty(state?: boolean): void;
     isEmptyParamFunction(): boolean;

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

@@ -1,18 +1,25 @@
 import { BaseFunction } from '../../functions/base-function';
 import { IFunctionService } from '../../services/function.service';
+import { IFormulaRuntimeService } from '../../services/runtime.service';
 import { LexerNode } from '../analysis/lexer-node';
 import { BaseAstNode } from './base-ast-node';
 import { BaseAstNodeFactory } from './base-ast-node-factory';
 import { NodeType } from './node-type';
 export declare class OperatorNode extends BaseAstNode {
     private _functionExecutor;
-    constructor(operatorString: string, _functionExecutor: BaseFunction);
+    private _runtimeService;
+    constructor(operatorString: string, _functionExecutor: BaseFunction, _runtimeService: IFormulaRuntimeService);
     get nodeType(): NodeType;
     execute(): void;
+    /**
+     * If it contains an array formula, set the current cell to the cache and send itself as a ref outward
+     */
+    private _setEmbeddedArrayFormulaToResult;
 }
 export declare class OperatorNodeFactory extends BaseAstNodeFactory {
     private readonly _functionService;
-    constructor(_functionService: IFunctionService);
+    private readonly _runtimeService;
+    constructor(_functionService: IFunctionService, _runtimeService: IFormulaRuntimeService);
     get zIndex(): number;
     create(param: string): BaseAstNode;
     checkAndCreateNodeType(param: LexerNode | string): BaseAstNode | undefined;

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

@@ -1,7 +1,9 @@
 import { IFormulaCurrentConfigService } from '../../services/current-data.service';
 import { IFunctionService } from '../../services/function.service';
 import { IFormulaRuntimeService } from '../../services/runtime.service';
+import { ISuperTableService } from '../../services/super-table.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';
@@ -11,9 +13,10 @@ export declare class ReferenceNode extends BaseAstNode {
     private _runtimeService;
     private _referenceObjectType;
     private _isPrepareMerge;
+    private _tableReferenceObject?;
     private _refOffsetX;
     private _refOffsetY;
-    constructor(_currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, operatorString: string, _referenceObjectType: ReferenceObjectType, _isPrepareMerge?: boolean);
+    constructor(_currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, operatorString: string, _referenceObjectType: ReferenceObjectType, _isPrepareMerge?: boolean, _tableReferenceObject?: TableReferenceObject | undefined);
     get nodeType(): NodeType;
     execute(): void;
     setRefOffset(x?: number, y?: number): void;
@@ -26,8 +29,14 @@ export declare class ReferenceNodeFactory extends BaseAstNodeFactory {
     private readonly _currentConfigService;
     private readonly _formulaRuntimeService;
     private readonly _functionService;
-    constructor(_currentConfigService: IFormulaCurrentConfigService, _formulaRuntimeService: IFormulaRuntimeService, _functionService: IFunctionService);
+    private readonly _superTableService;
+    constructor(_currentConfigService: IFormulaCurrentConfigService, _formulaRuntimeService: IFormulaRuntimeService, _functionService: IFunctionService, _superTableService: ISuperTableService);
     get zIndex(): number;
     checkAndCreateNodeType(param: LexerNode | string): ReferenceNode | undefined;
+    private _getTableMap;
+    private _getNode;
+    private _getTableReferenceNode;
+    private _splitTableStructuredRef;
+    private _checkTokenIsTableReference;
     private _checkParentIsUnionOperator;
 }

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

@@ -4,7 +4,6 @@ import { BaseValueObject } from '../value-object/base-value-object';
 import { FormulaAstLRU } from '../../basics/cache-lru';
 import { ObjectClassType } from '../../basics/object-class-type';
 import { ArrayValueObject } from '../value-object/array-value-object';
-import { StringValueObject } from '../value-object/primitive-object';
 export type NodeValueType = BaseValueObject | BaseReferenceObject | AsyncObject | AsyncArrayObject;
 export type FunctionVariantType = BaseValueObject | BaseReferenceObject;
 export declare const FORMULA_REF_TO_ARRAY_CACHE: FormulaAstLRU<ArrayValueObject>;
@@ -25,6 +24,8 @@ export declare class BaseReferenceObject extends ObjectClassType {
     private _runtimeFeatureCellData;
     private _refOffsetX;
     private _refOffsetY;
+    private _currentRow?;
+    private _currentColumn?;
     constructor(_token: string);
     dispose(): void;
     getToken(): string;
@@ -48,7 +49,7 @@ export declare class BaseReferenceObject extends ObjectClassType {
     };
     isReferenceObject(): boolean;
     iterator(callback: (valueObject: Nullable<BaseValueObject>, rowIndex: number, columnIndex: number) => Nullable<boolean>): Nullable<boolean>;
-    getFirstCell(): BaseValueObject | StringValueObject;
+    getFirstCell(): BaseValueObject;
     getRangeData(): IRange;
     setRangeData(range: IRange): void;
     getUnitId(): string;
@@ -93,12 +94,15 @@ export declare class BaseReferenceObject extends ObjectClassType {
     isRow(): boolean;
     isRange(): boolean;
     isTable(): boolean;
+    isCurrentRowForRange(): boolean;
+    isCurrentColumnForRange(): boolean;
+    isMultiArea(): boolean;
     unionBy(referenceObject: BaseReferenceObject): NodeValueType;
     unionRange(rangeData1: IRange, rangeData2: IRange): IRange;
-    getCellValueObject(cell: ICellData): BaseValueObject | StringValueObject;
+    getCellValueObject(cell: ICellData): BaseValueObject;
     private _getPatternByCell;
-    getCellByRow(row: number): BaseValueObject | StringValueObject;
-    getCellByColumn(column: number): BaseValueObject | StringValueObject;
+    getCellByRow(row: number): BaseValueObject;
+    getCellByColumn(column: number): BaseValueObject;
     getCurrentActiveSheetData(): import('../../basics/common').ISheetItem;
     getCurrentStylesData(): import('@univerjs/core').Styles;
     getCurrentRuntimeSheetData(): import('@univerjs/core').ObjectMatrix<Nullable<ICellData>> | undefined;
@@ -106,7 +110,10 @@ export declare class BaseReferenceObject extends ObjectClassType {
     getCurrentRuntimeActiveArrayFormulaCellData(): import('@univerjs/core').ObjectMatrix<Nullable<ICellData>> | undefined;
     getCellData(row: number, column: number): Nullable<ICellData>;
     getRuntimeFeatureCellValue(row: number, column: number): ICellData | undefined;
-    getCellByPosition(rowRaw?: number, columnRaw?: number): BaseValueObject | StringValueObject;
+    getCellByPosition(rowRaw?: number, columnRaw?: number): BaseValueObject;
+    setCurrentRowAndColumn(row: number, column: number): void;
+    getCurrentRow(): number | undefined;
+    getCurrentColumn(): number | undefined;
     /**
      * Get the pattern of the cell
      * @param unitId

package/lib/types/engine/reference-object/multi-area-reference-object.d.ts

@@ -0,0 +1,92 @@
+import { Nullable } from '@univerjs/core';
+import { ArrayValueObject } from '../value-object/array-value-object';
+import { BaseValueObject, ErrorValueObject } from '../value-object/base-value-object';
+import { BaseReferenceObject } from './base-reference-object';
+export type MultiAreaValue = BaseReferenceObject | ErrorValueObject;
+export declare class MultiAreaReferenceObject extends BaseReferenceObject {
+    /**
+     * 2D structure:
+     * - First dimension: stored by rows
+     * - Second dimension: each AreaValue within that row
+     */
+    private _areas;
+    constructor(token: string, areas?: MultiAreaValue[][]);
+    dispose(): void;
+    getAreas(): MultiAreaValue[][];
+    setAreas(areas: MultiAreaValue[][]): void;
+    /**
+     * Append an area:
+     * - If a single AreaValue is passed, it will be wrapped as one row.
+     * - If an AreaValue[] is passed, it will be inserted as an entire row.
+     */
+    addArea(area: MultiAreaValue | MultiAreaValue[]): void;
+    /** Flatten the 2D areas to reuse 1D logic */
+    private _flatAreas;
+    isMultiArea(): boolean;
+    isRange(): boolean;
+    isCell(): boolean;
+    isRow(): boolean;
+    isColumn(): boolean;
+    getRowCount(): number;
+    getColumnCount(): number;
+    isExceedRange(): boolean;
+    setRefOffset(x?: number, y?: number): void;
+    private _getReferenceArea;
+    /**
+     * Multi-area reference may span multiple sheets, but Excel requires
+     * them to be in the same sheet for most functions. We follow Excel semantics
+     * by returning the first area’s identifiers.
+     */
+    getUnitId(): string;
+    getSheetId(): string;
+    getActiveSheetRowCount(): number;
+    getActiveSheetColumnCount(): number;
+    /**
+     * Iterate through all areas in order, flattening the multi-area into
+     * a sequence of cells.
+     *
+     * Note: The order here is "row-major":
+     *   iterate by the row order of _areas, then within each row by the area order.
+     */
+    iterator(callback: (v: Nullable<BaseValueObject>, row: number, col: number) => Nullable<boolean>): void;
+    /**
+     * Excel defines the "first cell" of a multi-area reference
+     * as the first cell of the first area.
+     */
+    getFirstCell(): BaseValueObject;
+    /**
+     * For multi-area, we only take the *first cell* of each area and
+     * arrange them into a 2D ArrayValueObject:
+     *
+     * - outer `_areas` dimension => rows
+     * - inner `_areas[row]` dimension => columns
+     */
+    toArrayValueObject(): ArrayValueObject;
+    getRangePosition(): {
+        startRow: number;
+        endRow: number;
+        startColumn: number;
+        endColumn: number;
+        rangeType?: import('@univerjs/core').RANGE_TYPE;
+        startAbsoluteRefType?: import('@univerjs/core').AbsoluteRefType;
+        endAbsoluteRefType?: import('@univerjs/core').AbsoluteRefType;
+        unitId?: string;
+        sheetId?: string;
+    };
+    toUnitRange(): {
+        range: {
+            startRow: number;
+            endRow: number;
+            startColumn: number;
+            endColumn: number;
+            rangeType?: import('@univerjs/core').RANGE_TYPE;
+            startAbsoluteRefType?: import('@univerjs/core').AbsoluteRefType;
+            endAbsoluteRefType?: import('@univerjs/core').AbsoluteRefType;
+            unitId?: string;
+            sheetId?: string;
+        };
+        sheetId: string;
+        unitId: string;
+    };
+    getRangeData(): import('@univerjs/core').IRange;
+}

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

@@ -1,10 +1,92 @@
-import { ISuperTable, TableOptionType } from '../../basics/common';
+import { ISuperTable, IUnitSheetNameMap, TableOptionType } from '../../basics/common';
 import { BaseReferenceObject } from './base-reference-object';
+/**
+ * Table reference object compatible with Excel Structured References
+ *
+ * Supported (examples):
+ * - =Table[Column]                          // Single column (default DATA)
+ * - =Table[[ColumnA]:[ColumnB]]             // Column range (default DATA)
+ * - =Table[#All] / [#Data] / [#Headers] / [#Totals] / [#This Row]
+ * - =Table[[#All],[Column]]                 // Section + column/column range
+ * - =Table[[#Data],[ColA]:[ColB]]
+ * - =Table[[#This Row],[Column]]
+ *
+ * Not supported (invalid):
+ * - Multiple sections in parallel (e.g., [[#Headers],[#Data]])
+ * - Non-existent sections (e.g., #Title)
+ * - Column indices instead of column names (e.g., [[1]:[3]])
+ */
 export declare class TableReferenceObject extends BaseReferenceObject {
     private _tableData;
+    /**
+     * Structured reference body (with or without outer []):
+     *  - "#Data" / "#All"
+     *  - "[Col]" / "[[ColA]:[ColB]]"
+     *  - "[[#Data],[Col]]" / "[[#All],[ColA]:[ColB]]"
+     */
     private _columnDataString;
-    constructor(token: string, _tableData: ISuperTable, _columnDataString: string, tableOptionMap: Map<string, TableOptionType>);
+    /** Section text to enum mapping ('#All', '#Data', '#Headers', '#Totals', '#This Row') */
+    private _tableOptionMap;
+    private _isCurrentRowForRange;
+    constructor(token: string, _tableData: ISuperTable, 
+    /**
+     * Structured reference body (with or without outer []):
+     *  - "#Data" / "#All"
+     *  - "[Col]" / "[[ColA]:[ColB]]"
+     *  - "[[#Data],[Col]]" / "[[#All],[ColA]:[ColB]]"
+     */
+    _columnDataString: string | undefined, 
+    /** Section text to enum mapping ('#All', '#Data', '#Headers', '#Totals', '#This Row') */
+    _tableOptionMap: Map<string, TableOptionType>);
+    getRangeData(): import('@univerjs/core').IRange;
+    getRefOffset(): {
+        x: number;
+        y: number;
+    };
     isTable(): boolean;
-    private _stringToColumnData;
-    private _columnHandler;
+    isCurrentRowForRange(): boolean;
+    setForcedSheetId(sheetNameMap: IUnitSheetNameMap): void;
+    /**
+     * Parse structured reference body, returning column range and Section type.
+     * Determination rules:
+     *  - Whether it's a Section depends on "whether it starts with # after stripping", not whether it still has brackets.
+     *  - No comma: Either Section, or column/column range
+     *  - Has comma: Left is Section, right is column/column range
+     */
+    private _parseStructuredRef;
+    /** Strip one layer of outer brackets from "[...]" (return as-is if none) */
+    private _stripOuterBracketOnce;
+    /**
+     * Find first comma at depth=0 (used to split Section and column parts)
+     * Compatible with nesting like "[[#Data],[ColA]:[ColB]]".
+     */
+    private _findCommaAtTopLevel;
+    /**
+     * Parse Section, compatible with both "[#Data]" and "#Data" inputs
+     * Returns TableOptionType if matched; returns DATA if not (could throw error instead)
+     */
+    private _parseSectionMaybeBracketed;
+    /**
+     * Section mapping: Only accepts keywords starting with #.
+     * Returns undefined if not a valid Section (caller treats as column or fallback).
+     */
+    private _mapSection;
+    /**
+     * Parse column selection:
+     * - "[Col]" / "Col"               => Single column
+     * - "[[ColA]:[ColB]]" / "[ColA]:[ColB]" / "ColA:ColB"  => Column range
+     *
+     * Rules:
+     * - First find colon at top level, strip one layer of brackets from left and right sides (if present)
+     * - Returns -1 if column name not found (caller should handle as parse error)
+     */
+    private _parseColumnOrRange;
+    /** Strip one layer of outer brackets; return as-is if none (compatible with "[Col]" and "Col") */
+    private _stripOuterBracketIfAny;
+    /** Find range colon at depth=0 */
+    private _findColonAtTopLevel;
+    /** Column title → column index; returns -1 if not found (caller should handle as parse error) */
+    private _titleToIndex;
+    /** Resolve #This Row's row number; takes first data row (tableStartRow+1) when no context available */
+    private _resolveThisRow;
 }

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

@@ -172,6 +172,11 @@ export declare class ArrayValueObject extends BaseValueObject {
     atan2(valueObject: BaseValueObject): BaseValueObject;
     atan2Inverse(valueObject: BaseValueObject): BaseValueObject;
     mean(ddof?: number): BaseValueObject;
+    /**
+     * TODO: @DR-Univer
+     * This calculation method contains an error, please note.
+     * Please refer `getMedianResult` function in /engine-formula/src/basics/statistical.ts
+     */
     median(): BaseValueObject;
     /**
      * ┌──────────────┬────────────────────────────────┬───────────────────┐

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

@@ -40,9 +40,11 @@ export declare class BaseValueObject extends ObjectClassType {
     isNumber(): boolean;
     isBoolean(): boolean;
     isLambda(): boolean;
+    isDateFormat(): boolean;
     isError(): boolean;
     isNull(): boolean;
     isHyperlink(): boolean;
+    isImage(): boolean;
     sum(): BaseValueObject;
     max(): BaseValueObject;
     min(): BaseValueObject;
@@ -82,7 +84,7 @@ export declare class BaseValueObject extends ObjectClassType {
     multiplyBy(value: string | number | boolean): BaseValueObject;
     dividedBy(value: string | number | boolean): BaseValueObject;
     modInverse(valueObject: BaseValueObject): BaseValueObject;
-    compareBy(value: string | number | boolean, operator: compareToken): BaseValueObject;
+    compareBy(value: string | number | boolean, operator: compareToken, isDateCompare?: boolean): BaseValueObject;
     concatenate(value: string | number | boolean, concatenateType?: ConcatenateType): string;
     pow(valueObject: BaseValueObject): BaseValueObject;
     powInverse(valueObject: BaseValueObject): BaseValueObject;