@univerjs/sheets 1.0.0-rc.0 → 1.0.0

package/lib/types/commands/commands/set-worksheet-hide.command.d.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 import type { ICommand } from '@univerjs/core';
+import { WorksheetHiddenState } from '@univerjs/core';
 export interface ISetWorksheetHiddenCommandParams {
+    unitId?: string;
     subUnitId?: string;
+    /** Defaults to ordinary hiding; VERY_HIDDEN is available to API callers. */
+    hidden?: WorksheetHiddenState;
 }
 export declare const SetWorksheetHideCommand: ICommand;

package/lib/types/commands/mutations/set-range-values.mutation.d.ts

@@ -13,7 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IAccessor, ICellData, IMutation, IMutationCommonParams, IObjectMatrixPrimitiveType, IRange, Nullable } from '@univerjs/core';
+import type { IAccessor, ICellData, IMutation, IMutationCommonParams, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable } from '@univerjs/core';
+import { ObjectMatrix, Styles } from '@univerjs/core';
 /** Params of `SetRangeValuesMutation` */
 export interface ISetRangeValuesMutationParams extends IMutationCommonParams {
     subUnitId: string;
@@ -31,6 +32,16 @@ export interface ISetRangeValuesMutationParams extends IMutationCommonParams {
 export interface ISetRangeValuesRangeMutationParams extends ISetRangeValuesMutationParams {
     range: IRange[];
 }
+/**
+ * Read-only native value preparation for caller-owned atomic model staging. The resulting style IDs
+ * must travel with the prepared cells; replay installs them and must not allocate replacement IDs.
+ * This does not execute handlers, publish notifications, or own style garbage collection.
+ */
+export declare function prepareSetRangeValuesMutation(cells: ObjectMatrix<Nullable<ICellData>>, styles: Styles, params: Pick<ISetRangeValuesMutationParams, 'cellValue' | 'isOverrideStyle'>): {
+    before: IObjectMatrixPrimitiveType<Nullable<ICellData>>;
+    after: IObjectMatrixPrimitiveType<Nullable<ICellData>>;
+    styles: Record<string, IStyleData>;
+};
 /**
  * Generate undo mutation of a `SetRangeValuesMutation`
  *

package/lib/types/commands/mutations/set-worksheet-hide.mutation.d.ts

@@ -14,8 +14,9 @@
  * limitations under the License.
  */
 import type { BooleanNumber, IAccessor, IMutation } from '@univerjs/core';
+import { WorksheetHiddenState } from '@univerjs/core';
 export interface ISetWorksheetHideMutationParams {
-    hidden: BooleanNumber;
+    hidden: WorksheetHiddenState | BooleanNumber;
     unitId: string;
     subUnitId: string;
 }

package/lib/types/controllers/calculate-result-apply.controller.d.ts

@@ -24,7 +24,7 @@ export declare class CalculateResultApplyController extends Disposable {
      * @param unitId
      * @param sheetId
      * @param cellData
-     * @returns
+     * @returns Calculated cell data merged with number formats.
      */
     private _getMergedCellData;
 }

package/lib/types/facade/f-defined-name.d.ts

@@ -44,7 +44,7 @@ export declare class FDefinedNameBuilder {
     setName(name: string): FDefinedNameBuilder;
     /**
      * Sets the formula of the defined name builder.
-     * @param {string }formula The formula of the defined name.
+     * @param {string} formula The formula without the leading `=`; this method prepends it.
      * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
      * @example
      * ```ts
@@ -232,7 +232,7 @@ export declare class FDefinedName extends FBase {
     setName(name: string): void;
     /**
      * Sets the formula of the defined name.
-     * @param {string} formula The formula of the defined name.
+     * @param {string} formula The formula without the leading `=`; this method prepends it.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();

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

@@ -154,8 +154,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getLastColumn(): number;
     /**
-     * Gets the width of the applied area
-     * @returns {number} The width of the area
+     * Returns the number of columns in this range.
+     * @returns {number} The column count, not a size in pixels.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -167,8 +167,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getWidth(): number;
     /**
-     * Gets the height of the applied area
-     * @returns {number} The height of the area
+     * Returns the number of rows in this range.
+     * @returns {number} The row count, not a size in pixels.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -180,8 +180,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getHeight(): number;
     /**
-     * Return range whether this range is merged
-     * @returns {boolean} if true is merged
+     * Checks whether this range exactly matches a merged cell range.
+     * @returns {boolean} `true` only for an exact merged range match. Use `isPartOfMerge()` to check overlap.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -199,7 +199,7 @@ export declare class FRange extends FBaseInitialable {
      * Return first cell style data in this range. Please note that if there are row styles, col styles and (or)
      * worksheet style, they will be merged into the cell style. You can use `type` to specify the type of the style to get.
      *
-     * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+     * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
      * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
      * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
      * Default is 'row'.
@@ -218,7 +218,7 @@ export declare class FRange extends FBaseInitialable {
     /**
      * Get the font family of the cell.
      *
-     * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+     * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
      * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
      * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
      * Default is 'row'.
@@ -237,7 +237,7 @@ export declare class FRange extends FBaseInitialable {
     /**
      * Get the font size of the cell.
      *
-     * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+     * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
      * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
      * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
      * Default is 'row'.
@@ -256,7 +256,7 @@ export declare class FRange extends FBaseInitialable {
     /**
      * Return first cell style in this range.
      *
-     * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+     * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
      * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
      * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
      * Default is 'row'.
@@ -275,7 +275,7 @@ export declare class FRange extends FBaseInitialable {
     /**
      * Returns the cell styles for the cells in the range.
      *
-     * @param {GetStyleType} type - The type of the style to get. 'row' means get the composed style of row, col and
+     * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
      * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
      * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
      * Default is 'row'.
@@ -310,7 +310,7 @@ export declare class FRange extends FBaseInitialable {
     getValue(): CellValue | null;
     /**
      * Return first cell value in this range
-     * @param {boolean} includeRichText Should the returns of this func to include rich text
+     * @param {true} includeRichText Pass `true` to return a `RichTextValue` for rich-text content instead of plain text.
      * @returns {CellValue | RichTextValue | null} The cell value
      * @example
      * ```ts
@@ -388,7 +388,7 @@ export declare class FRange extends FBaseInitialable {
     getValues(): Nullable<CellValue>[][];
     /**
      * Returns the cell values for the cells in the range.
-     * @param {boolean} includeRichText Should the returns of this func to include rich text
+     * @param {true} includeRichText Pass `true` to return `RichTextValue` entries for rich-text content instead of plain text.
      * @returns {Nullable<RichTextValue | CellValue>[][]} A two-dimensional array of cell values.
      * @example
      * ```ts
@@ -580,7 +580,10 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     getWrap(): boolean;
-    /** Gets whether the top-left cell shrinks its font size to fit the cell width. */
+    /**
+     * Gets whether the top-left cell shrinks its font size to fit the cell width.
+     * @returns {boolean} Whether shrink-to-fit is enabled for the top-left cell.
+     */
     getShrinkToFit(): boolean;
     /**
      * Gets whether text wrapping is enabled for cells in the range.
@@ -592,6 +595,7 @@ export declare class FRange extends FBaseInitialable {
      * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A1:B2');
      * console.log(fRange.getWraps());
+     * ```
      */
     getWraps(): boolean[][];
     /**
@@ -608,7 +612,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getWrapStrategy(): WrapStrategy;
     /**
-     * Returns the horizontal alignment of the text (left/center/right) of the top-left cell in the range.
+     * Returns the horizontal alignment of the top-left cell as `left`, `center`, or `normal` (right alignment).
+     * Default and other core alignment values return `general`, which is not accepted by `setHorizontalAlignment()`.
      * @returns {string} The horizontal alignment of the text in the cell.
      * @example
      * ```ts
@@ -621,7 +626,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getHorizontalAlignment(): string;
     /**
-     * Returns the horizontal alignments of the cells in the range.
+     * Returns a two-dimensional array of horizontal alignments: `left`, `center`, or `normal` (right alignment).
+     * Default and other core alignment values return `general`, which is not accepted by `setHorizontalAlignment()`.
      * @returns {string[][]} A two-dimensional array of horizontal alignments of text associated with cells in the range.
      * @example
      * ```ts
@@ -634,7 +640,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getHorizontalAlignments(): string[][];
     /**
-     * Returns the vertical alignment (top/middle/bottom) of the top-left cell in the range.
+     * Returns `top`, `middle`, or `bottom` for the top-left cell; unspecified alignment returns `general`.
+     * `general` is a getter result and is not accepted by `setVerticalAlignment()`.
      * @returns {string} The vertical alignment of the text in the cell.
      * @example
      * ```ts
@@ -647,7 +654,8 @@ export declare class FRange extends FBaseInitialable {
      */
     getVerticalAlignment(): string;
     /**
-     * Returns the vertical alignments of the cells in the range.
+     * Returns a two-dimensional array of `top`, `middle`, or `bottom` values; unspecified alignment returns `general`.
+     * `general` is a getter result and is not accepted by `setVerticalAlignment()`.
      * @returns {string[][]} A two-dimensional array of vertical alignments of text associated with cells in the range.
      * @example
      * ```ts
@@ -663,6 +671,7 @@ export declare class FRange extends FBaseInitialable {
      * Set custom meta data for first cell in current range.
      * @param {CustomData} data The custom meta data
      * @returns {FRange} This range, for chaining
+     * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -677,6 +686,7 @@ export declare class FRange extends FBaseInitialable {
      * Set custom meta data for current range.
      * @param {CustomData[][]} datas The custom meta data
      * @returns {FRange} This range, for chaining
+     * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -694,7 +704,7 @@ export declare class FRange extends FBaseInitialable {
      * Returns the custom meta data for the cell at the start of this range.
      * @returns {CustomData | null} The custom meta data
      * @example
-     * ```
+     * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
      * if (!fWorksheet) return;
@@ -705,9 +715,9 @@ export declare class FRange extends FBaseInitialable {
     getCustomMetaData(): CustomData | null;
     /**
      * Returns the custom meta data for the cells in the range.
-     * @returns {CustomData[][]} A two-dimensional array of custom meta data
+     * @returns {Nullable<CustomData>[][]} A two-dimensional array of custom metadata, with `null` for cells without metadata.
      * @example
-     * ```
+     * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
      * if (!fWorksheet) return;
@@ -801,25 +811,64 @@ export declare class FRange extends FBaseInitialable {
      */
     setTextRotation(rotation: number): FRange;
     /**
-     * Sets the value of the range.
-     * @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
+     * Sets the value or specified cell properties for every cell in this range.
+     *
+     * There are two input modes:
+     *
+     * - `CellValue` (`number`, `string`, or `boolean`): replaces the cell content. A string starting
+     *   with `=` and containing at least one more character is written as a formula (`f`), clearing
+     *   the previous value (`v`) and rich text (`p`). Other values clear the previous formula and
+     *   rich text. Strings recognized as formatted numbers (for example, percentages, dates, or
+     *   currencies) are converted to numeric values and apply the parsed number format. Existing
+     *   formatting is otherwise preserved.
+     * - `ICellData`: updates cell-data fields directly, for explicit control over `v` (value),
+     *   `f` (formula), `p` (rich text), `t` (value type), and `s` (style). The object bypasses the
+     *   formula and formatted-number parsing above: `{ v: '=SUM(A1:A2)' }` does not set a formula;
+     *   use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Omitted content fields are not
+     *   automatically cleared, so use `f: null` and `p: null` when replacing a formula or rich text
+     *   with `v`. Use `v: null` to clear the stored value. Supplied style properties are merged into
+     *   the existing style; `s: null` clears the style.
+     *
+     * In both modes, the stored value is converted according to its cell type. Unless an `ICellData`
+     * input supplies `t`, the type is inferred from the value, number format, and existing cell type.
+     * Consequently, passing `{ v: '00123' }` alone does not guarantee that the value stays a string;
+     * supply `t: CellValueType.STRING` to store it as text.
+     *
+     * @param {CellValue | ICellData} value The scalar content or cell-data update to apply throughout the range.
      * @returns {FRange} This range, for chaining
+     * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
      * if (!fWorksheet) return;
-     * const fRange = fWorksheet.getRange('B2');
+     * const fRange = fWorksheet.getRange('B2:B3');
+     *
+     * // Replace the content of both cells, preserving their formatting.
      * fRange.setValue(123);
      *
-     * // or
-     * fRange.setValue({ v: 234, s: { bg: { rgb: '#ff0000' } } });
+     * // Parse a percentage and apply its number format to both cells.
+     * fRange.setValue('25%');
+     *
+     * // Write the same formula to both cells.
+     * fRange.setValue('=SUM(A1:A2)');
+     *
+     * // Explicitly replace content and update the background color.
+     * fRange.setValue({ v: 234, f: null, p: null, s: { bg: { rgb: '#ff0000' } } });
+     *
+     * // Store numeric-looking text (CellValueType is imported from '@univerjs/core').
+     * fRange.setValue({ v: '00123', t: CellValueType.STRING, f: null, p: null });
+     *
+     * // Clear value, formula, and rich text while preserving formatting.
+     * fRange.setValue({ v: null, f: null, p: null });
      * ```
      */
     setValue(value: CellValue | ICellData): FRange;
     /**
-     * Set new value for current cell, first cell in this range.
-     * @param {CellValue | ICellData} value  The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
+     * Sets the value or specified cell properties of the top-left cell in this range.
+     * Uses the same scalar parsing and cell-data update rules as {@link FRange.setValue}.
+     * @param {CellValue | ICellData} value  The scalar content or cell-data update to apply to the top-left cell only.
      * @returns {FRange} This range, for chaining
+     * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -837,7 +886,7 @@ export declare class FRange extends FBaseInitialable {
      * @param {RichTextValue | IDocumentData} value The rich text value
      * @returns {FRange} The range
      * @example
-     * ```
+     * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
      * if (!fWorksheet) return;
@@ -856,7 +905,7 @@ export declare class FRange extends FBaseInitialable {
     setRichTextValueForCell(value: RichTextValue | IDocumentData): FRange;
     /**
      * Set the rich text value for the cells in the range.
-     * @param {RichTextValue[][]} values The rich text value
+     * @param {(RichTextValue | IDocumentData)[][]} values A two-dimensional array of rich-text values or document data matching this range's dimensions.
      * @returns {FRange} The range
      * @example
      * ```ts
@@ -873,7 +922,7 @@ export declare class FRange extends FBaseInitialable {
      *   .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
      * fRange.setRichTextValues([
      *   [richText, richText],
-     *   [null, null]
+     *   [richText, richText]
      * ]);
      * console.log(fRange.getValue(true).toPlainText()); // Hello World
      * ```
@@ -881,7 +930,8 @@ export declare class FRange extends FBaseInitialable {
     setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRange;
     /**
      * Set the cell wrap of the given range.
-     * Cells with wrap enabled (the default) resize to display their full content. Cells with wrap disabled display as much as possible in the cell without resizing or running to multiple lines.
+     * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
+     * Use `setWrapStrategy()` to explicitly select clipping or overflow behavior.
      * @param {boolean} isWrapEnabled Whether to enable wrap
      * @returns {FRange} this range, for chaining
      * @example
@@ -895,7 +945,15 @@ export declare class FRange extends FBaseInitialable {
      * ```
      */
     setWrap(isWrapEnabled: boolean): FRange;
-    /** Sets whether cells shrink their font size to fit the cell width. */
+    /**
+     * Sets whether cells shrink their font size to fit the cell width.
+     * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
+     * @returns {FRange} This range, for chaining.
+     * @example
+     * ```ts
+     * univerAPI.getActiveWorkbook()?.getActiveSheet().getRange('A1:B2').setShrinkToFit(true);
+     * ```
+     */
     setShrinkToFit(enabled: boolean): FRange;
     /**
      * Sets the text wrapping strategy for the cells in the range.
@@ -914,7 +972,7 @@ export declare class FRange extends FBaseInitialable {
     setWrapStrategy(strategy: WrapStrategy): FRange;
     /**
      * Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
-     * @param {"top" | "middle" | "bottom"} alignment The vertical alignment
+     * @param {FVerticalAlignment} alignment The vertical alignment
      * @returns {FRange} this range, for chaining
      * @example
      * ```ts
@@ -927,8 +985,9 @@ export declare class FRange extends FBaseInitialable {
      */
     setVerticalAlignment(alignment: FVerticalAlignment): FRange;
     /**
-     * Set the horizontal (left to right) alignment for the given range (left/center/right).
-     * @param {"left" | "center" | "normal"} alignment The horizontal alignment
+     * Sets the horizontal alignment for the range using `left`, `center`, or `normal`.
+     * These parameter names follow Google Apps Script. In Univer, `normal` means right alignment; `right` is not accepted.
+     * @param {FHorizontalAlignment} alignment The horizontal alignment: `left`, `center`, or `normal` (right alignment).
      * @returns {FRange} this range, for chaining
      * @example
      * ```ts
@@ -936,13 +995,18 @@ export declare class FRange extends FBaseInitialable {
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
      * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A1:B2');
-     * fRange.setHorizontalAlignment('left');
+     * fRange.setHorizontalAlignment('normal'); // Align right
      * ```
      */
     setHorizontalAlignment(alignment: FHorizontalAlignment): FRange;
     /**
-     * Sets a different value for each cell in the range. The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats. If a value begins with `=`, it is interpreted as a formula.
-     * @param {CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>} value The value can be a two-dimensional array or a standard range matrix (must match the dimensions of this range), consisting of numbers, strings, Boolean values or Composed of standard cell formats.
+     * Sets cell values or specified cell properties using an array or a sparse matrix.
+     * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
+     *
+     * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
+     * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
+     * are updated; matrix coordinates are not offset by or clipped to this range.
+     * @param {CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>} value An array relative to this range, or a sparse matrix using absolute worksheet coordinates.
      * @returns {FRange} This range, for chaining
      * @example
      * ```ts
@@ -954,6 +1018,12 @@ export declare class FRange extends FBaseInitialable {
      *   [1, { v: 2, s: { bg: { rgb: '#ff0000' } } }],
      *   [3, 4]
      * ]);
+     *
+     * // Update only B2 and C3 using absolute worksheet coordinates.
+     * fWorksheet.getRange('B2:C3').setValues({
+     *   1: { 1: 'B2' },
+     *   2: { 2: { v: 10, f: null, p: null } },
+     * });
      * ```
      */
     setValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>): FRange;
@@ -1179,6 +1249,7 @@ export declare class FRange extends FBaseInitialable {
      * @param {number} callback.row the row number of the cell
      * @param {number} callback.col the column number of the cell
      * @param {ICellData} callback.cell the cell data
+     * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -1196,6 +1267,7 @@ export declare class FRange extends FBaseInitialable {
      * @param {AbsoluteRefType} [startAbsoluteRefType] - The absolute reference type for the start cell.
      * @param {AbsoluteRefType} [endAbsoluteRefType] - The absolute reference type for the end cell.
      * @returns {string} The A1 notation of the range.
+     * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
@@ -1382,11 +1454,12 @@ export declare class FRange extends FBaseInitialable {
      */
     getUsedThemeStyle(): string | undefined;
     /**
-     * Clears content and formatting information of the range. Or Optionally clears only the contents or only the formatting.
+     * Clears the range content and formatting, or only one of them as specified by the options.
+     * Both content and formatting are cleared when both flags are true or both are false.
      * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
-     * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. If false, the contents and formatting are cleared. Default is false.
-     * @param {boolean} [options.formatOnly] - If true, the formatting of the range is cleared. If false, the contents and formatting are cleared. Default is false.
-     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+     * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
+     * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
+     * @returns {FRange} This range, for chaining.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1404,7 +1477,7 @@ export declare class FRange extends FBaseInitialable {
     clear(options?: IFacadeClearOptions): FRange;
     /**
      * Clears content of the range, while preserving formatting information.
-     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+     * @returns {FRange} This range, for chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1419,7 +1492,7 @@ export declare class FRange extends FBaseInitialable {
     clearContent(): FRange;
     /**
      * Clears formatting information of the range, while preserving contents.
-     * @returns {FWorksheet} Returns the current worksheet instance for method chaining
+     * @returns {FRange} This range, for chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();

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

@@ -71,7 +71,7 @@ export declare class FSelection {
     getActiveRangeList(): FRange[];
     /**
      * Represents the current select cell in the sheet.
-     * @returns {ISelectionCell} The current select cell info.Pay attention to the type of the return value.
+     * @returns {Nullable<ISelectionCell>} The primary cell of the current selection, or `null` when none exists.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();

package/lib/types/facade/f-sheet-hooks.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 { Injector } from '@univerjs/core';
+import { FBase } from '@univerjs/core/facade';
+/**
+ * @hideconstructor
+ */
+export declare class FSheetHooks extends FBase {
+    protected readonly _injector: Injector;
+    constructor(_injector: Injector);
+}

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

@@ -24,7 +24,7 @@ export interface IFUniverSheetsMixin {
     /**
      * Create a new spreadsheet and get the API handler of that spreadsheet.
      * @param {Partial<IWorkbookData>} data The snapshot of the spreadsheet.
-     * @param {ICreateUnitOptions} options The options of creating the spreadsheet.
+     * @param {ICreateUnitOptions} [options] The options of creating the spreadsheet.
      * @returns {FWorkbook} The spreadsheet API instance.
      * @example
      * ```ts
@@ -63,13 +63,12 @@ export interface IFUniverSheetsMixin {
     getWorkbook(id: string): FWorkbook | null;
     /**
      * Get the target of the sheet.
-     * @param {ICommandInfo<object>} commandInfo - The commandInfo of the command.
-     * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} - The target of the sheet.
+     * @param {{ unitId?: string; subUnitId?: string; sheetId?: string }} [params] Target IDs from the command parameters. Omitted IDs use the current workbook and active sheet.
+     * @returns {{ workbook: FWorkbook; worksheet: FWorksheet; unitId: string; subUnitId: string } | null} The resolved workbook, worksheet, and their IDs, or `null` if the target cannot be resolved.
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {
-     *   const { options, ...commandInfo } = event;
-     *   const target = univerAPI.getSheetCommandTarget(commandInfo.params);
+     *   const target = univerAPI.getSheetCommandTarget(event.params);
      *   if (!target) return;
      *   const { workbook, worksheet } = target;
      *   console.log(workbook, worksheet);

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

@@ -16,7 +16,6 @@
 import type { CommandListener, CustomData, IDisposable, IRange, IStyleData, IWorkbookData, IWorksheetData, Workbook } from '@univerjs/core';
 import type { ISetDefinedNameMutationParam } from '@univerjs/engine-formula';
 import type { IRangeThemeStyleJSON } from '@univerjs/sheets';
-import type { FontLine as _FontLine } from './f-range';
 import { ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService } from '@univerjs/core';
 import { FBaseInitialable } from '@univerjs/core/facade';
 import { IDefinedNamesService } from '@univerjs/engine-formula';
@@ -39,6 +38,9 @@ export declare class FWorkbook extends FBaseInitialable {
     protected readonly _permissionService: IPermissionService;
     protected readonly _logService: ILogService;
     protected readonly _definedNamesService: IDefinedNamesService;
+    /**
+     * The workbook unit id used to identify this workbook in commands and snapshots.
+     */
     readonly id: string;
     constructor(_workbook: Workbook, _injector: Injector, _resourceLoaderService: IResourceLoaderService, _selectionManagerService: SheetsSelectionsService, _univerInstanceService: IUniverInstanceService, _commandService: ICommandService, _permissionService: IPermissionService, _logService: ILogService, _definedNamesService: IDefinedNamesService);
     /**
@@ -53,6 +55,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     getWorkbook(): Workbook;
+    /** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
     dispose(): void;
     /**
      * Get the id of the workbook.
@@ -267,7 +270,7 @@ export declare class FWorkbook extends FBaseInitialable {
     deleteSheet(sheet: FWorksheet | string): boolean;
     /**
      * Undo the last action.
-     * @returns {FWorkbook} A promise that resolves to true if the undo was successful, false otherwise.
+     * @returns {FWorkbook} This workbook, for chaining.
      * @example
      * ```ts
      * // The code below undoes the last action
@@ -278,7 +281,7 @@ export declare class FWorkbook extends FBaseInitialable {
     undo(): FWorkbook;
     /**
      * Redo the last undone action.
-     * @returns {FWorkbook} A promise that resolves to true if the redo was successful, false otherwise.
+     * @returns {FWorkbook} This workbook, for chaining.
      * @example
      * ```ts
      * // The code below redoes the last undone action
@@ -537,7 +540,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * const definedNameParam = fWorkbook.newDefinedNameBuilder()
      *   .setRef('Sheet1!$A$1')
      *   .setName('MyDefinedName')
-     *   .setComment('This is a comment');
+     *   .setComment('This is a comment')
      *   .build();
      * console.log(definedNameParam);
      * fWorkbook.insertDefinedNameBuilder(definedNameParam);
@@ -648,7 +651,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Create a range theme style.
      * @param {string} themeName - The name of the theme to register
-     * @param {Omit<IRangeThemeStyleJSON, 'name'>} themeStyleJson - The theme style json to register
+     * @param {Omit<IRangeThemeStyleJSON, 'name'>} [themeStyleJson] - The theme style json to register
      * @returns {RangeThemeStyle} - The created range theme style
      * @example
      * ```ts
@@ -761,11 +764,3 @@ export declare class FWorkbook extends FBaseInitialable {
      */
     removeStyles(styleKeys: string[]): void;
 }
-/**
- * @ignore
- */
-export declare namespace FWorkbook {
-    type FontLine = _FontLine;
-    type FontStyle = _FontLine;
-    type FontWeight = _FontLine;
-}