@univerjs/sheets-formula 0.24.0 → 0.25.0

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

@@ -27,6 +27,7 @@ export declare class ActiveDirtyController extends Disposable {
     private _initialHideRow;
     private _initialSheet;
     private _initialDefinedName;
+    private _initialSuperTable;
     private _getDefinedNameMutation;
     private _getSetRangeValuesMutationDirtyRange;
     private _getMoveRangeMutationDirtyRange;

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

@@ -0,0 +1,24 @@
+/**
+ * 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, ICommandService } from '@univerjs/core';
+import { FormulaCalculationSessionService } from '../services/formula-calculation-session.service';
+export declare class FormulaCalculationSessionController extends Disposable {
+    private readonly _commandService;
+    private readonly _sessionService;
+    constructor(_commandService: ICommandService, _sessionService: FormulaCalculationSessionService);
+    private _initialize;
+    private _hasFormulaResultToApply;
+}

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

@@ -62,7 +62,7 @@ export declare class TriggerCalculationController extends Disposable {
      * @param dirtyRanges
      */
     private _mergeDirtyRanges;
-    private _mergeDirtyNameMap;
+    private _mergeDirtyUnitStringMap;
     private _mergeDirtyUnitFeatureOrOtherFormulaMap;
     private _initialExecuteFormulaProcessListener;
     private _resetExecutingDirtyData;

package/lib/types/controllers/utils/ref-range-formula.d.ts

@@ -30,7 +30,10 @@ export declare enum FormulaReferenceMoveType {
     SetName = 11,
     RemoveSheet = 12,
     SetDefinedName = 13,// update defined name
-    RemoveDefinedName = 14
+    RemoveDefinedName = 14,// remove defined name
+    SetSuperTableName = 15,// update super table name
+    RemoveSuperTableName = 16,// remove super table name
+    RemoveSuperTableColumn = 17
 }
 export interface IFormulaReferenceMoveParam {
     type: FormulaReferenceMoveType;
@@ -51,6 +54,9 @@ export interface IFormulaReferenceMoveParam {
      * new defined name
      */
     definedName?: string;
+    oldTableName?: string;
+    tableName?: string;
+    tableColumnNames?: string[];
     /**
      * The filtered rows contained in the range, used for remove rows operation, etc.
      */

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

@@ -50,7 +50,8 @@ export interface IFFormulaSheetsMixin {
      *
      * // Use the function in a cell
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const cellA1 = fWorksheet.getRange('A1');
      * cellA1.setValue('World');
      * const cellA2 = fWorksheet.getRange('A2');
@@ -75,7 +76,8 @@ export interface IFFormulaSheetsMixin {
      *
      * // Use the function in a cell
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const cellA1 = fWorksheet.getRange('A1');
      * cellA1.setValue(100);
      * const cellA2 = fWorksheet.getRange('A2');
@@ -115,7 +117,8 @@ export interface IFFormulaSheetsMixin {
      *
      * // Use the function in a cell
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const cellA1 = fWorksheet.getRange('A1');
      * cellA1.setValue(1);
      * const cellA2 = fWorksheet.getRange('A2');
@@ -170,7 +173,8 @@ export interface IFFormulaSheetsMixin {
      *
      * // Use the function in a cell
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const cellA1 = fWorksheet.getRange('A1');
      * cellA1.setValue('World');
      * const cellA2 = fWorksheet.getRange('A2');
@@ -208,7 +212,8 @@ export interface IFFormulaSheetsMixin {
      *
      * // Use the function in a cell
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const cellA1 = fWorksheet.getRange('A1');
      * cellA1.setValue({ f: '=RANDOM_DELAYED()' });
      *
@@ -258,7 +263,8 @@ export interface IFFormulaSheetsMixin {
      *
      * // Use the function in a cell
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const cellA1 = fWorksheet.getRange('A1');
      * cellA1.setValue({ f: '=FETCH_USER_SCORE(42)' });
      *
@@ -296,17 +302,13 @@ export interface IFFormulaSheetsMixin {
     /**
      * Waits for formula-calculation results to be applied.
      *
-     * This method resolves under three conditions:
-     * 1. A real calculation runs and the engine emits a "calculation started" signal,
-     *    followed by a "calculation result applied" signal.
-     * 2. No calculation actually starts within 500 ms — the method assumes there is
-     *    nothing to wait for and resolves automatically.
-     * 3. A global 30 s timeout triggers, in which case the promise rejects.
-     *
-     * The API internally listens to both “calculation in progress” events and
-     * “calculation result applied” events, ensuring it behaves correctly whether
-     * formulas are recalculated or skipped due to cache/state.
+     * The API follows the latest formula-calculation session. If a running
+     * calculation is stopped and immediately restarted, the promise waits for
+     * the restarted session to apply its results.
      *
+     * @param {number} [timeout] Optional timeout in milliseconds. If omitted,
+     * the promise waits until calculation results are applied or no calculation
+     * occurs within the start-detection window.
      * @returns {Promise<void>} A promise that resolves when calculation results are applied
      * or when no calculation occurs within the start-detection window.
      *
@@ -321,7 +323,7 @@ export interface IFFormulaSheetsMixin {
      * console.log("Updated value:", value);
      * ```
      */
-    onCalculationResultApplied(): Promise<void>;
+    onCalculationResultApplied(timeout?: number): Promise<void>;
 }
 export declare class FFormulaSheetsMixin extends FFormula implements IFFormulaSheetsMixin {
     /**
@@ -339,8 +341,7 @@ export declare class FFormulaSheetsMixin extends FFormula implements IFFormulaSh
     registerAsyncFunction(name: string, func: IRegisterAsyncFunction): IDisposable;
     registerAsyncFunction(name: string, func: IRegisterAsyncFunction, description: string): IDisposable;
     calculationResultApplied(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable;
-    private _hasFormulaResultToApply;
-    onCalculationResultApplied(): Promise<void>;
+    onCalculationResultApplied(timeout?: number): Promise<void>;
 }
 declare module '@univerjs/engine-formula/facade' {
     interface FFormula extends IFFormulaSheetsMixin {

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

@@ -24,9 +24,9 @@ export interface IFRangeEngineFormulaMixin {
      * @returns {ISheetFormulaError[]} Array of formula errors in the range
      * @example
      * ```typescript
-     * const range = univerAPI.getActiveWorkbook()
-     *   .getActiveSheet()
-     *   .getRange('A1:B10');
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const range = fWorksheet.getRange('A1:B10');
      * const errors = range.getFormulaError();
      * console.log('Formula errors in range:', errors);
      * ```

package/lib/types/index.d.ts

@@ -18,6 +18,7 @@ export { QuickSumCommand } from './commands/commands/quick-sum.command';
 export { CalculationMode, PLUGIN_CONFIG_KEY_BASE } from './config/config';
 export type { IUniverSheetsFormulaBaseConfig, IUniverSheetsFormulaRemoteConfig } from './config/config';
 export { FormulaAutoFillController } from './controllers/formula-auto-fill.controller';
+export { FormulaCalculationSessionController } from './controllers/formula-calculation-session.controller';
 export { ImageFormulaCellInterceptorController } from './controllers/image-formula-cell-interceptor.controller';
 export { TriggerCalculationController } from './controllers/trigger-calculation.controller';
 export { UpdateDefinedNameController } from './controllers/update-defined-name.controller';
@@ -25,6 +26,8 @@ export { UpdateFormulaController } from './controllers/update-formula.controller
 export { UniverRemoteSheetsFormulaPlugin, UniverSheetsFormulaPlugin } from './plugin';
 export { DescriptionService, IDescriptionService } from './services/description.service';
 export type { ISearchItem, ISearchItemWithType } from './services/description.service';
+export { FormulaCalculationSessionService } from './services/formula-calculation-session.service';
+export type { IFormulaCalculationSessionState } from './services/formula-calculation-session.service';
 export { FormulaRefRangeService } from './services/formula-ref-range.service';
 export type { IRegisterAsyncFunction, IRegisterFunction, ISingleFunctionRegisterParams } from './services/register-function.service';
 export type { IRegisterFunctionParams, IUnregisterFunctionParams } from './services/register-function.service';

package/lib/types/locale/ar-SA.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type enUS from './en-US';
+declare const locale: typeof enUS;
+export default locale;

package/lib/types/locale/de-DE.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type enUS from './en-US';
+declare const locale: typeof enUS;
+export default locale;