@univerjs/sheets 0.12.2 → 0.12.3-experimental.20251205-e439e48

package/lib/locale/ja-JP.js

@@ -1,14 +1,14 @@
 const e = {
   sheets: {
     tabs: {
-      sheetCopy: "(복사본{0})",
-      sheet: "시트"
+      sheetCopy: "(コピー{0})",
+      sheet: "シート"
     },
     info: {
-      overlappingSelections: "겹치는 영역에서는 해당 명령을 사용할 수 없습니다.",
-      acrossMergedCell: "병합된 셀을 가로지름",
-      partOfCell: "병합된 셀의 일부만 선택됨",
-      hideSheet: "이 시트를 숨기면 표시되는 시트가 없습니다."
+      overlappingSelections: "そのコマンドは、重なり合う選択範囲に対しては使用できません。",
+      acrossMergedCell: "結合セルをまたいでいます",
+      partOfCell: "結合セルの一部が選択されています",
+      hideSheet: "表示されるシートがなくなるため、このシートを非表示にできません。"
     }
   }
 };

package/lib/types/commands/commands/util.d.ts

@@ -4,3 +4,4 @@ export declare function getSuitableRangesInView(ranges: IRange[], skeleton: Null
     suitableRanges: IRange[];
     remainingRanges: IRange[];
 };
+export declare function countCells(cellMatrix: ObjectMatrix<unknown>): number;

package/lib/types/commands/mutations/copy-worksheet-end.mutation.d.ts

@@ -0,0 +1,10 @@
+import { IMutation } from '@univerjs/core';
+export interface ICopyWorksheetEndMutationParams {
+    unitId: string;
+    subUnitId: string;
+}
+/**
+ * This mutation is used to mark the end of a copy worksheet operation that was split into chunks.
+ * When this mutation is applied on the server, it should trigger a snapshot save.
+ */
+export declare const CopyWorksheetEndMutation: IMutation<ICopyWorksheetEndMutationParams, boolean>;

package/lib/types/controllers/config.schema.d.ts

@@ -1,6 +1,21 @@
 import { DependencyOverride } from '@univerjs/core';
 export declare const SHEETS_PLUGIN_CONFIG_KEY = "sheets.config";
 export declare const configSymbol: unique symbol;
+export interface ILargeSheetOperationConfig {
+    /**
+     * The minimum number of cells that defines a "large sheet".
+     * When a sheet has more cells than this threshold:
+     * - Copy sheet: the mutation will be split into multiple batches
+     * - Remove sheet: undo/redo will not be supported
+     * @default 6000
+     */
+    largeSheetCellCountThreshold?: number;
+    /**
+     * The maximum number of cells per batch when splitting mutations for large sheets.
+     * @default 3000
+     */
+    batchSize?: number;
+}
 export interface IUniverSheetsConfig {
     notExecuteFormula?: boolean;
     override?: DependencyOverride;
@@ -22,5 +37,13 @@ export interface IUniverSheetsConfig {
      * @default true
      */
     freezeSync?: boolean;
+    /**
+     * Configuration for large sheet operations.
+     * When a sheet has more cells than the threshold:
+     * - Copy sheet: the mutation will be split into multiple batches
+     * - Remove sheet: undo/redo will not be supported
+     */
+    largeSheetOperation?: ILargeSheetOperationConfig;
 }
+export declare const defaultLargeSheetOperationConfig: Required<ILargeSheetOperationConfig>;
 export declare const defaultPluginConfig: IUniverSheetsConfig;

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

@@ -1,4 +1,5 @@
 import { SheetSkeletonChangeType, SheetValueChangeType, SplitDelimiterEnum } from '@univerjs/sheets';
+import { RangePermissionPoint, UnitRole, WorkbookPermissionPoint, WorksheetPermissionPoint } from './permission';
 /**
  * @ignore
  */
@@ -17,11 +18,31 @@ export interface IFSheetsEnum {
      * Split delimiter types.
      */
     SplitDelimiterType: typeof SplitDelimiterEnum;
+    /**
+     * Unit roles.
+     */
+    UnitRole: typeof UnitRole;
+    /**
+     * Workbook permission points.
+     */
+    WorkbookPermissionPoint: typeof WorkbookPermissionPoint;
+    /**
+     * Worksheet permission points.
+     */
+    WorksheetPermissionPoint: typeof WorksheetPermissionPoint;
+    /**
+     * Range permission points.
+     */
+    RangePermissionPoint: typeof RangePermissionPoint;
 }
 export declare class FSheetsEnum implements IFSheetsEnum {
     get SheetValueChangeType(): typeof SheetValueChangeType;
     get SheetSkeletonChangeType(): typeof SheetSkeletonChangeType;
     get SplitDelimiterType(): typeof SplitDelimiterEnum;
+    get UnitRole(): typeof UnitRole;
+    get WorkbookPermissionPoint(): typeof WorkbookPermissionPoint;
+    get WorksheetPermissionPoint(): typeof WorksheetPermissionPoint;
+    get RangePermissionPoint(): typeof RangePermissionPoint;
 }
 declare module '@univerjs/core/facade' {
     interface FEnum extends IFSheetsEnum {

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

@@ -1,6 +1,7 @@
 import { RangePermissionPointConstructor, WorkbookPermissionPointConstructor, WorkSheetPermissionPointConstructor, IAuthzIoService, ICommandService, Injector, IPermissionService } from '@univerjs/core';
 import { Observable } from 'rxjs';
 import { FRange } from './f-range';
+import { IRangeProtectionOptions, IWorksheetProtectionOptions } from './permission/permission-types';
 import { FBase } from '@univerjs/core/facade';
 import { RangeProtectionRuleModel, WorkbookEditablePermission, WorkbookPermissionService, WorksheetEditPermission, WorksheetProtectionPointModel, WorksheetProtectionRuleModel, WorksheetViewPermission } from '@univerjs/sheets';
 /**
@@ -148,6 +149,7 @@ export declare class FPermission extends FBase {
      * you need to modify the permission points with the permissionId returned by this function.
      * @param {string} unitId - The unique identifier of the workbook for which the permission is being set.
      * @param {string} subUnitId - The unique identifier of the worksheet for which the permission is being set.
+     * @param {IWorksheetProtectionOptions} options - Optional protection options including allowed users and name.
      * @returns {Promise<string | undefined>} - Returns the `permissionId` if the permission is successfully added. If the operation fails or no result is returned, it resolves to `undefined`.
      *
      * @example
@@ -159,12 +161,15 @@ export declare class FPermission extends FBase {
      * const subUnitId = worksheet.getSheetId();
      * // Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
      * // For details, please see the example of the **`setWorksheetPermissionPoint`** API.
-     * const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId)
+     * const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId, {
+     *   allowedUsers: ['user1', 'user2'],
+     *   name: 'My Protection'
+     * })
      * // Can still edit and read it.
      * console.log('debugger', permissionId)
      * ```
      */
-    addWorksheetBasePermission(unitId: string, subUnitId: string): Promise<string | undefined>;
+    addWorksheetBasePermission(unitId: string, subUnitId: string, options?: IWorksheetProtectionOptions): Promise<string | undefined>;
     /**
      * Delete the entire table protection set for the worksheet and reset the point permissions of the worksheet to true
      * @param {string} unitId - The unique identifier of the workbook for which the permission is being set.
@@ -232,6 +237,7 @@ export declare class FPermission extends FBase {
      * @param {string} unitId - The unique identifier of the workbook.
      * @param {string} subUnitId - The unique identifier of the worksheet.
      * @param {FRange[]} ranges - The ranges to be protected.
+     * @param {IRangeProtectionOptions} options - Optional protection options including allowed users and name.
      * @returns {Promise<{ permissionId: string, ruleId: string } | undefined>} - Returns an object containing the `permissionId` and `ruleId` if the range protection is successfully added. If the operation fails or no result is returned, it resolves to `undefined`. permissionId is used to stitch permission point ID，ruleId is used to store permission rules
      *
      * @example
@@ -245,7 +251,10 @@ export declare class FPermission extends FBase {
      * const range = worksheet.getRange('A1:B2');
      * const ranges = [];
      * ranges.push(range);
-     * const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
+     * const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges, {
+     *   name: 'Protected Area',
+     *   allowEdit: false
+     * });
      * const {permissionId, ruleId} = res;
      * console.log('debugger', permissionId, ruleId);
      *
@@ -259,10 +268,20 @@ export declare class FPermission extends FBase {
      * }]);
      * ```
      */
-    addRangeBaseProtection(unitId: string, subUnitId: string, ranges: FRange[]): Promise<{
+    addRangeBaseProtection(unitId: string, subUnitId: string, ranges: FRange[], options?: IRangeProtectionOptions): Promise<{
         permissionId: string;
         ruleId: string;
     } | undefined>;
+    /**
+     * Determine view state from range protection options
+     * @private
+     */
+    private _determineRangeViewState;
+    /**
+     * Determine edit state from range protection options
+     * @private
+     */
+    private _determineRangeEditState;
     /**
      * Removes the range protection from the worksheet.
      * @deprecated Use `worksheet.getWorksheetPermission().unprotectRules()` instead

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

@@ -1,16 +1,17 @@
 import { Observable } from 'rxjs';
 import { FRange } from '../f-range';
 import { FWorksheet } from '../f-worksheet';
-import { IRangeProtectionRule as IFRangeProtectionRule, IRangePermission, IRangeProtectionOptions, RangePermissionSnapshot, RangePermissionPoint } from './permission-types';
+import { IRangeProtectionOptions, RangePermissionSnapshot, RangePermissionPoint } from './permission-types';
 import { IAuthzIoService, ICommandService, Injector, IPermissionService } from '@univerjs/core';
 import { RangeProtectionRuleModel } from '@univerjs/sheets';
+import { FRangeProtectionRule } from './f-range-protection-rule';
 /**
  * Implementation class for RangePermission
  * Manages range-level permissions
  *
  * @hideconstructor
  */
-export declare class FRangePermission implements IRangePermission {
+export declare class FRangePermission {
     private readonly _unitId;
     private readonly _subUnitId;
     private readonly _range;
@@ -22,6 +23,7 @@ export declare class FRangePermission implements IRangePermission {
     private readonly _rangeProtectionRuleModel;
     private readonly _permissionSubject;
     private readonly _subscriptions;
+    private readonly _fPermission;
     /**
      * Observable stream of permission snapshot changes
      * @returns Observable that emits when permission snapshot changes
@@ -33,7 +35,7 @@ export declare class FRangePermission implements IRangePermission {
      */
     readonly protectionChange$: Observable<{
         type: 'protected';
-        rule: IFRangeProtectionRule;
+        rule: FRangeProtectionRule;
     } | {
         type: 'unprotected';
         ruleId: string;
@@ -65,7 +67,7 @@ export declare class FRangePermission implements IRangePermission {
      * ```ts
      * const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2');
      * const permission = range?.getRangePermission();
-     * const canEdit = permission?.getPoint(RangePermissionPoint.Edit);
+     * const canEdit = permission?.getPoint(univerAPI.Enum.RangePermissionPoint.Edit);
      * console.log(canEdit);
      * ```
      */
@@ -147,46 +149,54 @@ export declare class FRangePermission implements IRangePermission {
      */
     canDelete(): boolean;
     /**
-     * Set a specific permission point for the range (low-level API for local runtime control).
-     * This method directly sets the permission point value for the current range protection rule.
-     * If no protection rule exists, it will create permission points without a rule (local-only mode).
+     * Set a specific permission point for the range (low-level API).
+     *
+     * **Important:** This method only updates the permission point value for an existing protection rule.
+     * It does NOT create permission checks that will block actual editing operations.
+     * You must call `protect()` first to create a protection rule before using this method.
+     *
+     * This method is useful for:
+     * - Fine-tuning permissions after creating a protection rule with `protect()`
+     * - Dynamically adjusting permissions based on runtime conditions
+     * - Advanced permission management scenarios
+     *
      * @param {RangePermissionPoint} point The permission point to set.
      * @param {boolean} value The value to set (true = allowed, false = denied).
      * @returns {Promise<void>} A promise that resolves when the point is set.
+     * @throws {Error} If no protection rule exists for this range.
+     *
      * @example
      * ```ts
      * const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2');
      * const permission = range?.getRangePermission();
-     * // Can set permission points without calling protect() first (local-only mode)
-     * await permission?.setPoint(RangePermissionPoint.Edit, false); // Disable edit
-     * await permission?.setPoint(RangePermissionPoint.View, true);  // Enable view
+     *
+     * // First, create a protection rule
+     * await permission?.protect({ name: 'My Range', allowEdit: true });
+     *
+     * // Then you can dynamically update permission points
+     * await permission?.setPoint(univerAPI.Enum.RangePermissionPoint.Edit, false); // Now disable edit
+     * await permission?.setPoint(univerAPI.Enum.RangePermissionPoint.View, true);  // Ensure view is enabled
      * ```
      */
     setPoint(point: RangePermissionPoint, value: boolean): Promise<void>;
-    /**
-     * Get a local-only permission ID for this range (used when no protection rule exists)
-     * @private
-     */
-    private _getLocalPermissionId;
     /**
      * Protect the current range.
      * @param {IRangeProtectionOptions} options Protection options.
-     * @returns {Promise<IFRangeProtectionRule>} The created protection rule.
+     * @returns {Promise<FRangeProtectionRule>} The created protection rule.
      * @example
      * ```ts
      * const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2');
      * const permission = range?.getRangePermission();
      * const rule = await permission?.protect({
      *   name: 'My protected range',
-     *   allowEdit: false,
-     *   allowView: true,
-     *   allowManageCollaborator: false,
-     *   allowDeleteRule: false
+     *   allowEdit: true,
+     *   allowedUsers: ['user1', 'user2'],
+     *   allowViewByOthers: false,
      * });
      * console.log(rule);
      * ```
      */
-    protect(options?: IRangeProtectionOptions): Promise<IFRangeProtectionRule>;
+    protect(options?: IRangeProtectionOptions): Promise<FRangeProtectionRule>;
     /**
      * Determine view state from options
      * @private
@@ -220,7 +230,7 @@ export declare class FRangePermission implements IRangePermission {
     unprotect(): Promise<void>;
     /**
      * List all protection rules.
-     * @returns {Promise<IFRangeProtectionRule[]>} Array of protection rules.
+     * @returns {Promise<FRangeProtectionRule[]>} Array of protection rules.
      * @example
      * ```ts
      * const range = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getRange('A1:B2');
@@ -229,7 +239,7 @@ export declare class FRangePermission implements IRangePermission {
      * console.log(rules);
      * ```
      */
-    listRules(): Promise<IFRangeProtectionRule[]>;
+    listRules(): Promise<FRangeProtectionRule[]>;
     /**
      * Subscribe to permission changes (simplified interface).
      * @param {Function} listener Callback function to be called when permissions change.

package/lib/types/facade/permission/f-range-protection-rule.d.ts

@@ -1,5 +1,5 @@
 import { FRange } from '../f-range';
-import { IRangeProtectionOptions, IRangeProtectionRule } from './permission-types';
+import { IRangeProtectionOptions } from './permission-types';
 import { ICommandService, Injector } from '@univerjs/core';
 import { RangeProtectionRuleModel } from '@univerjs/sheets';
 /**
@@ -8,7 +8,7 @@ import { RangeProtectionRuleModel } from '@univerjs/sheets';
  *
  * @hideconstructor
  */
-export declare class FRangeProtectionRule implements IRangeProtectionRule {
+export declare class FRangeProtectionRule {
     private readonly _unitId;
     private readonly _subUnitId;
     private readonly _ruleId;
@@ -25,7 +25,7 @@ export declare class FRangeProtectionRule implements IRangeProtectionRule {
      * @example
      * ```ts
      * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
-     * const permission = worksheet?.permission();
+     * const permission = worksheet?.getWorksheetPermission();
      * const rules = await permission?.listRangeProtectionRules();
      * const ruleId = rules?.[0]?.id;
      * console.log(ruleId);
@@ -38,7 +38,7 @@ export declare class FRangeProtectionRule implements IRangeProtectionRule {
      * @example
      * ```ts
      * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
-     * const permission = worksheet?.permission();
+     * const permission = worksheet?.getWorksheetPermission();
      * const rules = await permission?.listRangeProtectionRules();
      * const ranges = rules?.[0]?.ranges;
      * console.log(ranges);
@@ -51,7 +51,7 @@ export declare class FRangeProtectionRule implements IRangeProtectionRule {
      * @example
      * ```ts
      * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
-     * const permission = worksheet?.permission();
+     * const permission = worksheet?.getWorksheetPermission();
      * const rules = await permission?.listRangeProtectionRules();
      * const options = rules?.[0]?.options;
      * console.log(options);
@@ -65,34 +65,20 @@ export declare class FRangeProtectionRule implements IRangeProtectionRule {
      * @example
      * ```ts
      * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
-     * const permission = worksheet?.permission();
+     * const permission = worksheet?.getWorksheetPermission();
      * const rules = await permission?.listRangeProtectionRules();
      * const rule = rules?.[0];
      * await rule?.updateRanges([worksheet.getRange('A1:C3')]);
      * ```
      */
     updateRanges(ranges: FRange[]): Promise<void>;
-    /**
-     * Update protection options.
-     * @param {Partial<IRangeProtectionOptions>} options Partial options to update (will be merged with existing options).
-     * @returns {Promise<void>} A promise that resolves when the options are updated.
-     * @example
-     * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
-     * const permission = worksheet?.permission();
-     * const rules = await permission?.listRangeProtectionRules();
-     * const rule = rules?.[0];
-     * await rule?.updateOptions({ name: 'New Protection Name', allowEdit: true });
-     * ```
-     */
-    updateOptions(options: Partial<IRangeProtectionOptions>): Promise<void>;
     /**
      * Delete the current protection rule.
      * @returns {Promise<void>} A promise that resolves when the rule is removed.
      * @example
      * ```ts
      * const worksheet = univerAPI.getActiveWorkbook()?.getActiveSheet();
-     * const permission = worksheet?.permission();
+     * const permission = worksheet?.getWorksheetPermission();
      * const rules = await permission?.listRangeProtectionRules();
      * const rule = rules?.[0];
      * await rule?.remove();

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

@@ -38,6 +38,7 @@ export declare class FWorkbookPermission implements IWorkbookPermission {
         collaborator: ICollaborator;
     }>;
     private _subscriptions;
+    private readonly _fPermission;
     constructor(_unitId: string, _injector: Injector, _permissionService: IPermissionService, _authzIoService: IAuthzIoService);
     /**
      * Create permission snapshot stream from IPermissionService
@@ -126,7 +127,7 @@ export declare class FWorkbookPermission implements IWorkbookPermission {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const permission = workbook?.getWorkbookPermission();
-     * await permission?.setPoint(WorkbookPermissionPoint.Print, false);
+     * await permission?.setPoint(univerAPI.Enum.WorkbookPermissionPoint.Print, false);
      * ```
      */
     setPoint(point: WorkbookPermissionPoint, value: boolean): Promise<void>;
@@ -138,7 +139,7 @@ export declare class FWorkbookPermission implements IWorkbookPermission {
      * ```ts
      * const workbook = univerAPI.getActiveWorkbook();
      * const permission = workbook?.getWorkbookPermission();
-     * const canPrint = permission?.getPoint(WorkbookPermissionPoint.Print);
+     * const canPrint = permission?.getPoint(univerAPI.Enum.WorkbookPermissionPoint.Print);
      * console.log(canPrint);
      * ```
      */
@@ -166,11 +167,11 @@ export declare class FWorkbookPermission implements IWorkbookPermission {
      * await permission?.setCollaborators([
      *   {
      *     user: { userID: 'user1', name: 'John Doe', avatar: 'https://...' },
-     *     role: UnitRole.Editor
+     *     role: univerAPI.Enum.UnitRole.Editor
      *   },
      *   {
      *     user: { userID: 'user2', name: 'Jane Smith', avatar: '' },
-     *     role: UnitRole.Reader
+     *     role: univerAPI.Enum.UnitRole.Reader
      *   }
      * ]);
      * ```
@@ -190,7 +191,7 @@ export declare class FWorkbookPermission implements IWorkbookPermission {
      * const permission = workbook?.getWorkbookPermission();
      * await permission?.addCollaborator(
      *   { userID: 'user1', name: 'John Doe', avatar: 'https://...' },
-     *   UnitRole.Editor
+     *   univerAPI.Enum.UnitRole.Editor
      * );
      * ```
      */
@@ -206,7 +207,7 @@ export declare class FWorkbookPermission implements IWorkbookPermission {
      * const permission = workbook?.getWorkbookPermission();
      * await permission?.updateCollaborator(
      *   { userID: 'user1', name: 'John Doe Updated', avatar: 'https://...' },
-     *   UnitRole.Reader
+     *   univerAPI.Enum.UnitRole.Reader
      * );
      * ```
      */