declare module "@univerjs/core/facade" {
  import { CalculationMode } from "@univerjs/sheets-formula";

  import type { IFUniverSheetsFormulaMixin } from "@univerjs/sheets-formula/facade";

  interface IFSheetsFormulaEnumMixin {
      /**
       * Define the calculation mode during initialization
       */
      CalculationMode: typeof CalculationMode;
  }
}

declare module "@univerjs/sheets-formula" {
  enum CalculationMode {
      /**
       * Force calculation of all formulas
       */
      FORCED = 0,
      /**
       * Partial calculation, only cells with formulas but no v values are calculated
       */
      WHEN_EMPTY = 1,
      /**
       * All formulas are not calculated
       */
      NO_CALCULATION = 2
  }
}

declare module "@univerjs/sheets-formula/facade" {
  import type { ISetFormulaCalculationResultMutation } from "@univerjs/engine-formula";

  import type { CalculationMode } from "@univerjs/sheets-formula";

  // @ts-ignore: optional external type dependency may be absent in generated workspaces.
  import type { IDisposable } from "@univerjs/core";

  interface IFFormulaSheetsMixin {
      /**
       * Update the calculation mode of the formula. It will take effect the next time the Univer Sheet is constructed.
       * The calculation mode only handles formulas data when the workbook initializes data.
       * @param {CalculationMode} calculationMode - The calculation mode of the formula.
       * @example
       * ```ts
       * const formulaEngine = univerAPI.getFormula();
       * formulaEngine.setInitialFormulaComputing(0);
       * ```
       */
      setInitialFormulaComputing(calculationMode: CalculationMode): void;
      /**
       * Listens for the moment when formula-calculation results are applied.
       *
       * This event fires after the engine completes a calculation cycle and
       * dispatches a `SetFormulaCalculationResultMutation`.
       * The callback is invoked during an idle frame to avoid blocking UI updates.
       *
       * @param {Function} callback - A function called with the calculation result payload
       * once the result-application mutation is emitted.
       * @returns {IDisposable} A disposable used to unsubscribe from the event.
       *
       * @example
       * ```ts
       * const formulaEngine = univerAPI.getFormula();
       *
       * const dispose = formulaEngine.calculationResultApplied((result) => {
       *   console.log('Calculation results applied:', result);
       * });
       *
       * // Later…
       * dispose.dispose();
       * ```
       */
      calculationResultApplied(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable;
      /**
       * Waits for formula-calculation results to be applied.
       *
       * 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.
       *
       * @example
       * ```ts
       * const formulaEngine = univerAPI.getFormula();
       *
       * // Wait for formula updates to apply before reading values.
       * await formulaEngine.onCalculationResultApplied();
       *
       * const value = sheet.getRange("C24").getValue();
       * console.log("Updated value:", value);
       * ```
       */
      onCalculationResultApplied(timeout?: number): Promise<void>;
  }

  class FFormulaSheetsMixin {
      setInitialFormulaComputing(calculationMode: CalculationMode): void;
      calculationResultApplied(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable;
      onCalculationResultApplied(timeout?: number): Promise<void>;
  }

  interface IFUniverSheetsFormulaMixin {
  }

  class FUniverSheetsFormulaMixin {
  }
}

declare module "@univerjs/sheets/facade" {
  import type { ISheetFormulaError } from "@univerjs/engine-formula";

  interface IFRangeEngineFormulaMixin {
      /**
       * Get formula errors in the current range
       * @returns {ISheetFormulaError[]} Array of formula errors in the range
       * @example
       * ```typescript
       * 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);
       * ```
       */
      getFormulaError(): ISheetFormulaError[];
  }

  interface IFWorkbookEngineFormulaMixin {
      /**
       * Get all formula errors in the workbook
       * @returns {ISheetFormulaError[]} Array of formula errors
       * @example
       * ```typescript
       * const fWorkbook = univerAPI.getActiveWorkbook();
       * const errors = fWorkbook.getAllFormulaError();
       * console.log('Formula errors:', errors);
       * ```
       */
      getAllFormulaError(): ISheetFormulaError[];
  }
}

declare module "@univerjs/core/facade" {
  import { CalculationMode } from "@univerjs/sheets-formula";

  import type { IFUniverSheetsFormulaMixin } from "@univerjs/sheets-formula/facade";

  interface FEnum extends IFSheetsFormulaEnumMixin {
  }
}

declare module "@univerjs/engine-formula/facade" {
  import type { IFFormulaSheetsMixin } from "@univerjs/sheets-formula/facade";

  interface FFormula extends IFFormulaSheetsMixin {
  }
}

declare module "@univerjs/sheets/facade" {
  import type { ISheetFormulaError } from "@univerjs/engine-formula";

  interface FRange extends IFRangeEngineFormulaMixin {
  }
}

declare module "@univerjs/core/facade" {
  import { CalculationMode } from "@univerjs/sheets-formula";

  import type { IFUniverSheetsFormulaMixin } from "@univerjs/sheets-formula/facade";

  interface FUniver extends IFUniverSheetsFormulaMixin {
  }
}

declare module "@univerjs/sheets/facade" {
  import type { ISheetFormulaError } from "@univerjs/engine-formula";

  interface FWorkbook extends IFWorkbookEngineFormulaMixin {
  }
}
