@univerjs/sheets 1.0.0-rc.0 → 1.0.1

package/lib/facade.js

@@ -1,4 +1,4 @@
-import { BooleanNumber, CanceledError, DEFAULT_STYLES, Dimension, Direction, HorizontalAlign, IAuthzIoService, ICommandService, ILogService, IPermissionService, IResourceLoaderService, IUniverInstanceService, Inject, Injector, LocaleService, ObjectMatrix, RANGE_TYPE, Rectangle, RedoCommand, RichTextValue, TextStyleValue, Tools, UndoCommand, UniverInstanceType, VerticalAlign, WrapStrategy, cellToRange, covertCellValue, covertCellValues, generateIntervalsByPoints, generateRandomId, getDisplayValueFromCell, getOriginCellValue, isNullCell, mergeWorksheetSnapshotWithDefault, toDisposable } from "@univerjs/core";
+import { BooleanNumber, CanceledError, DEFAULT_STYLES, Dimension, Direction, HorizontalAlign, IAuthzIoService, ICommandService, ILogService, IPermissionService, IResourceLoaderService, IUniverInstanceService, Inject, Injector, LocaleService, ObjectMatrix, RANGE_TYPE, Rectangle, RedoCommand, RichTextValue, TextStyleValue, Tools, UndoCommand, UniverInstanceType, VerticalAlign, WorksheetHiddenState, WrapStrategy, cellToRange, covertCellValue, covertCellValues, generateIntervalsByPoints, generateRandomId, getDisplayValueFromCell, getOriginCellValue, isNullCell, mergeWorksheetSnapshotWithDefault, toDisposable } from "@univerjs/core";
 import { FBase, FBaseInitialable, FEnum, FEventName, FUniver } from "@univerjs/core/facade";
 import { AddRangeProtectionMutation, AddWorksheetProtectionMutation, AppendRowCommand, AutoFillCommand, COMMAND_LISTENER_VALUE_CHANGE, CancelFrozenCommand, ClearSelectionAllCommand, ClearSelectionContentCommand, ClearSelectionFormatCommand, CopySheetCommand, DeleteRangeMoveLeftCommand, DeleteRangeMoveUpCommand, DeleteRangeProtectionMutation, DeleteWorksheetProtectionMutation, DeleteWorksheetRangeThemeStyleCommand, EditStateEnum, InsertColByRangeCommand, InsertRangeMoveDownCommand, InsertRangeMoveRightCommand, InsertRowByRangeCommand, InsertSheetCommand, MoveColsCommand, MoveRowsCommand, RangeProtectionPermissionDeleteProtectionPoint, RangeProtectionPermissionEditPoint, RangeProtectionPermissionManageCollaPoint, RangeProtectionPermissionViewPoint, RangeProtectionRuleModel, RangeThemeStyle, RegisterWorksheetRangeThemeStyleCommand, RemoveColByRangeCommand, RemoveDefinedNameCommand, RemoveRowByRangeCommand, RemoveSheetCommand, RemoveWorksheetMergeCommand, SCOPE_WORKBOOK_VALUE_DEFINED_NAME, SetBorderBasicCommand, SetColDataCommand, SetColHiddenCommand, SetColWidthCommand, SetDefinedNameCommand, SetFrozenCommand, SetGridlinesColorCommand, SetHorizontalTextAlignCommand, SetRangeCustomMetadataCommand, SetRangeProtectionMutation, SetRangeValuesCommand, SetRowDataCommand, SetRowHeightCommand, SetRowHiddenCommand, SetSelectionsOperation, SetShrinkToFitCommand, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetStyleCommand, SetTabColorCommand, SetTabColorMutation, SetTextRotationCommand, SetTextWrapCommand, SetVerticalTextAlignCommand, SetWorkbookNameCommand, SetWorksheetActiveOperation, SetWorksheetColumnCountCommand, SetWorksheetDefaultStyleMutation, SetWorksheetHideCommand, SetWorksheetHideMutation, SetWorksheetNameCommand, SetWorksheetOrderCommand, SetWorksheetOrderMutation, SetWorksheetRangeThemeStyleCommand, SetWorksheetRowCountCommand, SetWorksheetRowIsAutoHeightCommand, SetWorksheetRowIsAutoHeightMutation, SetWorksheetShowCommand, SheetRangeThemeService, SheetSkeletonChangeType, SheetValueChangeType, SheetsFreezeSyncController, SheetsSelectionsService, SplitDelimiterEnum, SplitTextToColumnsCommand, ToggleGridlinesCommand, UnregisterWorksheetRangeThemeStyleCommand, ViewStateEnum, WorkbookCommentPermission, WorkbookCopyPermission, WorkbookCopySheetPermission, WorkbookCreateProtectPermission, WorkbookCreateSheetPermission, WorkbookDeleteColumnPermission, WorkbookDeleteRowPermission, WorkbookDeleteSheetPermission, WorkbookDuplicatePermission, WorkbookEditablePermission, WorkbookExportPermission, WorkbookHideSheetPermission, WorkbookInsertColumnPermission, WorkbookInsertRowPermission, WorkbookManageCollaboratorPermission, WorkbookMoveSheetPermission, WorkbookPrintPermission, WorkbookRecoverHistoryPermission, WorkbookRenameSheetPermission, WorkbookSharePermission, WorkbookViewHistoryPermission, WorkbookViewPermission, WorksheetCopyPermission, WorksheetDeleteColumnPermission, WorksheetDeleteProtectionPermission, WorksheetDeleteRowPermission, WorksheetEditExtraObjectPermission, WorksheetEditPermission, WorksheetFilterPermission, WorksheetInsertColumnPermission, WorksheetInsertHyperlinkPermission, WorksheetInsertRowPermission, WorksheetManageCollaboratorPermission, WorksheetPivotTablePermission, WorksheetProtectionPointModel, WorksheetProtectionRuleModel, WorksheetSelectProtectedCellsPermission, WorksheetSelectUnProtectedCellsPermission, WorksheetSetCellStylePermission, WorksheetSetCellValuePermission, WorksheetSetColumnStylePermission, WorksheetSetRowStylePermission, WorksheetSortPermission, WorksheetViewPermission, addMergeCellsUtil, copyRangeStyles, getAddMergeMutationRangeByType, getAllWorksheetPermissionPoint, getAllWorksheetPermissionPointByPointPanel, getNextPrimaryCell, getPrimaryForRange, getValueChangedEffectedRange, validateDefinedName } from "@univerjs/sheets";
 import { FormulaDataModel, IDefinedNamesService, IFunctionService, ISuperTableService, deserializeRangeWithSheet, serializeRange, serializeRangeWithSheet } from "@univerjs/engine-formula";
@@ -23,7 +23,7 @@ import { ObjectScope, UnitAction, UnitObject, UnitRole } from "@univerjs/protoco
 const SHEETS_CUSTOM_FIELD_WARNING_MESSAGE = "[Facade]: The sheets custom field is not recommended for external use. Use it at your own risk.";
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -34,7 +34,7 @@ function _typeof(o) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -47,14 +47,14 @@ function toPrimitive(t, r) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -65,7 +65,7 @@ function _defineProperty(e, r, t) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorateParam.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);
@@ -73,7 +73,7 @@ function __decorateParam(paramIndex, decorator) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -136,7 +136,7 @@ let FDefinedNameBuilder = class 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
@@ -377,7 +377,7 @@ let FDefinedName = class FDefinedName extends FBase {
 	}
 	/**
 	* 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();
@@ -633,7 +633,7 @@ let FSelection = _FSelection = class FSelection {
 	}
 	/**
 	* 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();
@@ -1082,7 +1082,7 @@ let FRangeProtectionRule = class FRangeProtectionRule {
 	/**
 	* Update the protected ranges.
 	* @param {FRange[]} ranges New ranges to protect.
-	* @returns {Promise<void>} A promise that resolves when the ranges are updated.
+	* @returns {Promise<boolean>} A promise resolving to whether the protected ranges were updated.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1119,7 +1119,7 @@ let FRangeProtectionRule = class FRangeProtectionRule {
 	}
 	/**
 	* Delete the current protection rule.
-	* @returns {Promise<void>} A promise that resolves when the rule is removed.
+	* @returns {Promise<boolean>} A promise resolving to whether the rule was removed.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1370,7 +1370,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
 	/**
 	* Create worksheet protection with collaborators support.
 	* This must be called before setting permission points for collaboration to work.
-	* @param {IWorksheetProtectionOptions} options Protection options including allowed users.
+	* @param {IWorksheetProtectionOptions} [options] Protection options including allowed users.
 	* @returns {Promise<string>} The permissionId for the created protection.
 	* @example
 	* ```ts
@@ -1450,7 +1450,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
 	/**
 	* Remove worksheet protection.
 	* This deletes the protection rule and resets all permission points to allowed.
-	* @returns {Promise<void>} A promise that resolves when protection is removed.
+	* @returns {Promise<boolean>} A promise resolving to whether protection was removed; also resolves to `true` if already unprotected.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1511,7 +1511,6 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
 				pointsToSet["WorksheetView"] = true;
 				pointsToSet["WorksheetSort"] = true;
 				pointsToSet["WorksheetFilter"] = true;
-				break;
 		}
 		return pointsToSet;
 	}
@@ -1635,6 +1634,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
 	* if (fWorksheet.getWorksheetPermission().canView()) {
 	*   console.log('Worksheet is viewable');
 	* }
+	* ```
 	*/
 	canView() {
 		return this.getPoint("WorksheetView");
@@ -1830,7 +1830,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
 	/**
 	* Remove multiple protection rules at once.
 	* @param {string[]} ruleIds Array of rule IDs to remove.
-	* @returns {Promise<void>} A promise that resolves when the rules are removed.
+	* @returns {Promise<boolean>} A promise resolving to whether the rules were removed; also resolves to `true` for an empty ID list.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1879,7 +1879,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
 	* Debug cell permission information.
 	* @param {number} row Row index.
 	* @param {number} col Column index.
-	* @returns {FRangeProtectionRule | undefined} Debug information about which rules affect this cell, or null if no rules apply.
+	* @returns {Promise<FRangeProtectionRule | undefined>} A promise resolving to the protection rule affecting this cell, or `undefined` if no range protection rule applies.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2058,6 +2058,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 			this.setActiveRange
 		);
 	}
+	/** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
 	dispose() {
 		super.dispose();
 		delete this._fWorkbook;
@@ -2136,7 +2137,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	}
 	/**
 	* Get the current selection of the worksheet.
-	* @returns {FSelection} return the current selections of the worksheet or null if there is no selection.
+	* @returns {FSelection | null} The current selections, or `null` when no selection data is available.
 	* @example
 	* ```typescript
 	* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
@@ -2152,7 +2153,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	}
 	/**
 	* Get the default style of the worksheet.
-	* @returns {IStyleData} Default style of the worksheet.
+	* @returns {Nullable<IStyleData> | string} The default style object or style ID, or a nullish value when no default style is set.
 	* @example
 	* ```typescript
 	* const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
@@ -2206,7 +2207,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	}
 	/**
 	* Set the default style of the worksheet
-	* @param {string} style - The style to set
+	* @param {string | Nullable<IStyleData>} style - A style ID or style object, or `null` to clear the default style.
 	* @returns {FWorksheet} This worksheet instance for chaining
 	* @example
 	* ```typescript
@@ -2229,8 +2230,8 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* Set the default style of the worksheet row
-	* @param {number} index - The row index
+	* Set the default style of the worksheet column
+	* @param {number} index - The zero-based column index
 	* @param {string | Nullable<IStyleData>} style - The style name or style data
 	* @returns {FWorksheet} This sheet, for chaining.
 	* @example
@@ -2253,8 +2254,8 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* Set the default style of the worksheet column
-	* @param {number} index - The column index
+	* Set the default style of the worksheet row
+	* @param {number} index - The zero-based row index
 	* @param {string | Nullable<IStyleData>} style - The style name or style data
 	* @returns {FWorksheet} This sheet, for chaining.
 	* @example
@@ -2375,7 +2376,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	/**
 	* Inserts one or more consecutive blank rows in a sheet starting at the specified location.
 	* @param {number} rowIndex - The existing row before which rows are inserted. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
-	* @param {number} numRows - The positive number of rows to insert.
+	* @param {number} [numRows] - The positive number of rows to insert.
 	* @returns {FWorksheet} This sheet, for chaining.
 	* @example
 	* ```typescript
@@ -2600,7 +2601,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	/**
 	* Hides one or more consecutive rows starting at the given index. Use 0-index for this method
 	* @param {number} rowIndex - The starting index of the rows to hide
-	* @param {number} numRow - The number of rows to hide
+	* @param {number} [numRow] - The number of rows to hide
 	* @returns {FWorksheet} This sheet, for chaining.
 	* @example
 	* ```typescript
@@ -2657,9 +2658,9 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* Scrolling sheet to make specific rows visible.
+	* Unhides one or more consecutive rows starting at the given zero-based index.
 	* @param {number} rowIndex - The starting index of the rows
-	* @param {number} numRows - The number of rows
+	* @param {number} [numRows] - The number of rows
 	* @returns {FWorksheet} This worksheet instance for chaining
 	* @example
 	* ```typescript
@@ -2709,7 +2710,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	/**
 	* Make certain row wrap and auto height.
 	* @param {number} rowPosition - The row position to change.
-	* @param {BooleanNumber} auto - Whether to auto fit the row height.
+	* @param {BooleanNumber} [auto] - Whether to auto fit the row height.
 	* @returns {FWorksheet} This worksheet instance for chaining
 	* @example
 	* ```ts
@@ -2952,7 +2953,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	/**
 	* Inserts one or more consecutive blank columns in a sheet starting at the specified location.
 	* @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
-	* @param {number} numColumns - The number of columns to insert
+	* @param {number} [numColumns] - The number of columns to insert
 	* @returns {FWorksheet} This sheet, for chaining
 	* @example
 	* ```typescript
@@ -3174,7 +3175,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	/**
 	* Hides one or more consecutive columns starting at the given index. Use 0-index for this method
 	* @param {number} columnIndex - The starting index of the columns to hide
-	* @param {number} numColumn - The number of columns to hide
+	* @param {number} [numColumn] - The number of columns to hide
 	* @returns {FWorksheet} This sheet, for chaining
 	* @example
 	* ```typescript
@@ -3233,7 +3234,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	/**
 	* Show one or more consecutive columns starting at the given index. Use 0-index for this method
 	* @param {number} columnIndex - The starting index of the columns to unhide
-	* @param {number} numColumns - The number of columns to unhide
+	* @param {number} [numColumns] - The number of columns to unhide
 	* @returns {FWorksheet} This sheet, for chaining
 	* @example
 	* ```typescript
@@ -3324,7 +3325,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	* fRange.setValue('Whenever it is a damp, drizzly November in my soul...');
 	*
 	* // Set the column A to a width which fits the text
-	* fWorksheet.autoResizeColumn(0);
+	* fWorksheet.autoResizeColumns(0);
 	*
 	* // Get the width of the column A
 	* console.log(fWorksheet.getColumnWidth(0));
@@ -3710,7 +3711,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	}
 	/**
 	* Sets the sheet tab color.
-	* @param {string|null|undefined} color - A color code in CSS notation (like '#ffffff' or 'white'), or null to reset the tab color.
+	* @param {string} color - A color in CSS notation, such as '#ffffff' or 'white'.
 	* @returns {FWorksheet} Returns the current worksheet instance for method chaining
 	* @example
 	* ```ts
@@ -3731,8 +3732,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	}
 	/**
 	* Get the tab color of the sheet.
-	* @returns {string} The tab color of the sheet or undefined.
-	* The default color is css style property 'unset'.
+	* @returns {string | undefined} The tab color, or `undefined` when no color is set.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -3758,13 +3758,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 	* ```
 	*/
 	hideSheet() {
-		const commandService = this._injector.get(ICommandService);
-		if (this._workbook.getSheets().filter((sheet) => sheet.isSheetHidden() !== BooleanNumber.TRUE).length <= 1) throw new Error("Cannot hide the only visible sheet");
-		commandService.syncExecuteCommand(SetWorksheetHideCommand.id, {
-			unitId: this._workbook.getUnitId(),
-			subUnitId: this._worksheet.getSheetId()
-		});
-		return this;
+		return this.isSheetHidden() ? this : this.setHiddenState(WorksheetHiddenState.HIDDEN);
 	}
 	/**
 	* Shows this sheet. Has no effect if the sheet is already visible.
@@ -3785,7 +3779,7 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* Returns true if the sheet is currently hidden.
+	* Returns true for both HIDDEN and VERY_HIDDEN sheets.
 	* @returns {boolean} True if the sheet is hidden; otherwise, false.
 	* @example
 	* ```ts
@@ -3799,6 +3793,33 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return Boolean(this._worksheet.isSheetHidden() === BooleanNumber.TRUE);
 	}
 	/**
+	* Returns 0 (visible), 1 (hidden), or 2 (very hidden).
+	* @example fWorksheet.getHiddenState() === univerAPI.Enum.WorksheetHiddenState.VERY_HIDDEN
+	*/
+	getHiddenState() {
+		return this._worksheet.getHiddenState();
+	}
+	/**
+	* Changes the persisted hiding state through an undoable command.
+	* VERY_HIDDEN removes the sheet from Unhide UI; showSheet() can reveal it through the API.
+	* The last visible sheet cannot be hidden. Existing isSheetHidden() stays a boolean predicate.
+	* @example fWorksheet.setHiddenState(univerAPI.Enum.WorksheetHiddenState.VERY_HIDDEN)
+	*/
+	setHiddenState(hidden) {
+		if (hidden === WorksheetHiddenState.VISIBLE) return this.showSheet();
+		if (hidden !== WorksheetHiddenState.HIDDEN && hidden !== WorksheetHiddenState.VERY_HIDDEN) throw new RangeError(`Unsupported worksheet hidden state: ${String(hidden)}`);
+		if (this._worksheet.getHiddenState() === hidden) return this;
+		if (this._worksheet.getHiddenState() === WorksheetHiddenState.VISIBLE) {
+			if (this._workbook.getSheets().filter((sheet) => !sheet.isSheetHidden()).length <= 1) throw new Error("Cannot hide the only visible sheet");
+		}
+		this._injector.get(ICommandService).syncExecuteCommand(SetWorksheetHideCommand.id, {
+			unitId: this._workbook.getUnitId(),
+			subUnitId: this._worksheet.getSheetId(),
+			hidden
+		});
+		return this;
+	}
+	/**
 	* Sets the sheet name.
 	* @param {string} name - The new name for the sheet.
 	* @returns {FWorksheet} Returns the current worksheet instance for method chaining
@@ -3851,10 +3872,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this._workbook.getSheetIndex(this._worksheet);
 	}
 	/**
-	* Clears the sheet of content and formatting information.Or Optionally clears only the contents or only the formatting.
+	* Clears the sheet 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 sheet. If not provided, the contents and formatting are cleared both.
-	* @param {boolean} [options.contentsOnly] - If true, the contents of the sheet are cleared. If false, the contents and formatting are cleared. Default is false.
-	* @param {boolean} [options.formatOnly] - If true, the formatting of the sheet is cleared. If false, the contents and formatting are cleared. Default is false.
+	* @param {boolean} [options.contentsOnly] - If true, the contents of the sheet 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 {FWorksheet} Returns the current worksheet instance for method chaining
 	* @example
 	* ```ts
@@ -3965,8 +3987,8 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this.getRange(startRow, startColumn, endRow - startRow + 1, endColumn - startColumn + 1);
 	}
 	/**
-	* Returns the column index of the last column that contains content.
-	* @returns {number} the column index of the last column that contains content.
+	* Returns the zero-based index of the last column with stored cell data, including formatting-only cells.
+	* @returns {number} The last stored column index, or 0 for an empty sheet.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -3982,8 +4004,8 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
 		return this._worksheet.getLastColumnWithContent();
 	}
 	/**
-	* Returns the row index of the last row that contains content.
-	* @returns {number} the row index of the last row that contains content.
+	* Returns the zero-based index of the last row with stored cell data, including formatting-only cells.
+	* @returns {number} The last stored row index, or 0 for an empty sheet.
 	* @example
 	* ```ts
 	* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -4301,7 +4323,7 @@ let FRangePermission = class FRangePermission extends FBase {
 	}
 	/**
 	* Protect the current range.
-	* @param {IRangeProtectionOptions} options Protection options.
+	* @param {IRangeProtectionOptions} [options] Protection options.
 	* @returns {Promise<FRangeProtectionRule>} The created protection rule.
 	* @example
 	* ```ts
@@ -4566,8 +4588,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this._range.endColumn;
 	}
 	/**
-	* 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();
@@ -4581,8 +4603,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this._range.endColumn - this._range.startColumn + 1;
 	}
 	/**
-	* 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();
@@ -4596,8 +4618,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this._range.endRow - this._range.startRow + 1;
 	}
 	/**
-	* 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();
@@ -4618,7 +4640,7 @@ let FRange = _FRange = 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'.
@@ -4640,7 +4662,7 @@ let FRange = _FRange = 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'.
@@ -4662,7 +4684,7 @@ let FRange = _FRange = 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'.
@@ -4684,7 +4706,7 @@ let FRange = _FRange = 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'.
@@ -4706,7 +4728,7 @@ let FRange = _FRange = 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'.
@@ -4754,7 +4776,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	* ```
 	*/
 	getRawValue() {
-		return getOriginCellValue(this._worksheet.getCellMatrix().getValue(this._range.startRow, this._range.startColumn));
+		const cell = this._worksheet.getCellMatrix().getValue(this._range.startRow, this._range.startColumn);
+		return getOriginCellValue(cell);
 	}
 	/**
 	* Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string.
@@ -4777,7 +4800,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	* ```
 	*/
 	getDisplayValue() {
-		return getDisplayValueFromCell(this._worksheet.getCell(this._range.startRow, this._range.startColumn));
+		const cell = this._worksheet.getCell(this._range.startRow, this._range.startColumn);
+		return getDisplayValueFromCell(cell);
 	}
 	getValues(includeRichText) {
 		if (includeRichText) return this.getValueAndRichTextValues();
@@ -4843,7 +4867,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		for (let r = startRow; r <= endRow; r++) {
 			const row = [];
 			for (let c = startColumn; c <= endColumn; c++) {
-				const rawValue = getOriginCellValue(cellMatrix.getValue(r, c));
+				const cell = cellMatrix.getValue(r, c);
+				const rawValue = getOriginCellValue(cell);
 				row.push(rawValue);
 			}
 			values.push(row);
@@ -4899,7 +4924,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		for (let r = startRow; r <= endRow; r++) {
 			const row = [];
 			for (let c = startColumn; c <= endColumn; c++) {
-				const displayValue = getDisplayValueFromCell(this._worksheet.getCell(r, c));
+				const cell = this._worksheet.getCell(r, c);
+				const displayValue = getDisplayValueFromCell(cell);
 				row.push(displayValue);
 			}
 			values.push(row);
@@ -5084,7 +5110,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	getWrap() {
 		return this._worksheet.getRange(this._range).getWrap() === BooleanNumber.TRUE;
 	}
-	/** 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() {
 		var _this$_worksheet$getC3;
 		const { startRow, startColumn } = this._range;
@@ -5100,6 +5129,7 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	* if (!fWorksheet) return;
 	* const fRange = fWorksheet.getRange('A1:B2');
 	* console.log(fRange.getWraps());
+	* ```
 	*/
 	getWraps() {
 		const cells = this.getCellDatas();
@@ -5125,7 +5155,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this._worksheet.getRange(this._range).getWrapStrategy();
 	}
 	/**
-	* 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
@@ -5137,10 +5168,12 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	* ```
 	*/
 	getHorizontalAlignment() {
-		return transformCoreHorizontalAlignment(this._worksheet.getRange(this._range).getHorizontalAlignment());
+		const coreHorizontalAlignment = this._worksheet.getRange(this._range).getHorizontalAlignment();
+		return transformCoreHorizontalAlignment(coreHorizontalAlignment);
 	}
 	/**
-	* 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
@@ -5155,7 +5188,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this._worksheet.getRange(this._range).getHorizontalAlignments().map((row) => row.map((alignment) => transformCoreHorizontalAlignment(alignment)));
 	}
 	/**
-	* 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
@@ -5170,7 +5204,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return transformCoreVerticalAlignment(this._worksheet.getRange(this._range).getVerticalAlignment());
 	}
 	/**
-	* 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
@@ -5188,6 +5223,7 @@ let FRange = _FRange = 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');
@@ -5212,6 +5248,7 @@ let FRange = _FRange = 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');
@@ -5239,7 +5276,7 @@ let FRange = _FRange = 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;
@@ -5254,9 +5291,9 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	}
 	/**
 	* 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;
@@ -5396,18 +5433,55 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* 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) {
@@ -5422,9 +5496,11 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* 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');
@@ -5457,7 +5533,7 @@ let FRange = _FRange = 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;
@@ -5491,7 +5567,7 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	}
 	/**
 	* 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
@@ -5508,13 +5584,14 @@ let FRange = _FRange = 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
 	* ```
 	*/
 	setRichTextValues(values) {
-		const realValue = covertCellValues(values.map((row) => row.map((item) => item && { p: item instanceof RichTextValue ? item.getData() : item })), this._range);
+		const cellDatas = values.map((row) => row.map((item) => item && { p: item instanceof RichTextValue ? item.getData() : item }));
+		const realValue = covertCellValues(cellDatas, this._range);
 		const params = {
 			unitId: this._workbook.getUnitId(),
 			subUnitId: this._worksheet.getSheetId(),
@@ -5526,7 +5603,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	}
 	/**
 	* 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
@@ -5548,7 +5626,15 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		});
 		return this;
 	}
-	/** 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) {
 		this._commandService.syncExecuteCommand(SetShrinkToFitCommand.id, {
 			unitId: this._workbook.getUnitId(),
@@ -5583,7 +5669,7 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	}
 	/**
 	* 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
@@ -5604,8 +5690,9 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* 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
@@ -5613,7 +5700,7 @@ let FRange = _FRange = 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) {
@@ -5626,8 +5713,13 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		return this;
 	}
 	/**
-	* 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
@@ -5639,6 +5731,12 @@ let FRange = _FRange = 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) {
@@ -6010,6 +6108,7 @@ let FRange = _FRange = 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');
@@ -6032,6 +6131,7 @@ let FRange = _FRange = 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');
@@ -6247,11 +6347,12 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 		});
 	}
 	/**
-	* 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();
@@ -6279,7 +6380,7 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	}
 	/**
 	* 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();
@@ -6301,7 +6402,7 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	}
 	/**
 	* 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();
@@ -6549,8 +6650,8 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
 	* Returns a new range that is relative to the current range, whose upper left point is offset from the current range by the given rows and columns, and with the given height and width in cells.
 	* @param {number} rowOffset - The number of rows down from the range's top-left cell; negative values represent rows up from the range's top-left cell.
 	* @param {number} columnOffset - The number of columns right from the range's top-left cell; negative values represent columns left from the range's top-left cell.
-	* @param {number} numRows - The height in rows of the new range.
-	* @param {number} numColumns - The width in columns of the new range.
+	* @param {number} [numRows] - The height in rows of the new range.
+	* @param {number} [numColumns] - The width in columns of the new range.
 	* @returns {FRange} The new range.
 	* @example
 	* ```ts
@@ -6781,7 +6882,6 @@ let FWorkbookPermission = class FWorkbookPermission extends FBase {
 				pointsToSet["WorkbookView"] = true;
 				pointsToSet["WorkbookComment"] = true;
 				pointsToSet["WorkbookPrint"] = true;
-				break;
 		}
 		return pointsToSet;
 	}
@@ -6896,7 +6996,7 @@ let FWorkbookPermission = class FWorkbookPermission extends FBase {
 	}
 	/**
 	* Set multiple collaborators at once (replaces existing collaborators).
-	* @param {Array<{ user: IUser; role: UnitRole }>} collaborators Array of collaborators with user information and role.
+	* @param {Array<{ user: ICollaboratorUser; role: UnitRole }>} collaborators Array of collaborators with user information and role.
 	* @returns {Promise<void>} A promise that resolves when the collaborators are set.
 	* @example
 	* ```ts
@@ -6928,7 +7028,7 @@ let FWorkbookPermission = class FWorkbookPermission extends FBase {
 	}
 	/**
 	* Add a single collaborator.
-	* @param {IUser} user The user information (userID, name, avatar).
+	* @param {ICollaboratorUser} user The user information (userID, name, avatar).
 	* @param {UnitRole} role The role to assign.
 	* @returns {Promise<void>} A promise that resolves when the collaborator is added.
 	* @example
@@ -6954,7 +7054,7 @@ let FWorkbookPermission = class FWorkbookPermission extends FBase {
 	}
 	/**
 	* Update an existing collaborator's role and information.
-	* @param {IUser} user The updated user information (userID, name, avatar).
+	* @param {ICollaboratorUser} user The updated user information (userID, name, avatar).
 	* @param {UnitRole} role The new role to assign.
 	* @returns {Promise<void>} A promise that resolves when the collaborator is updated.
 	* @example
@@ -7075,6 +7175,7 @@ let FWorkbook = class FWorkbook extends FBaseInitialable {
 	getWorkbook() {
 		return this._workbook;
 	}
+	/** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
 	dispose() {
 		super.dispose();
 		this._workbook = null;
@@ -7365,7 +7466,7 @@ let FWorkbook = class FWorkbook extends FBaseInitialable {
 	}
 	/**
 	* 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
@@ -7380,7 +7481,7 @@ let FWorkbook = class FWorkbook extends FBaseInitialable {
 	}
 	/**
 	* 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
@@ -7744,7 +7845,7 @@ let FWorkbook = 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);
@@ -7884,7 +7985,7 @@ let FWorkbook = 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