feat(docs): complete permission facade APIs

Author: DR-Univer

packages/docs/src/controllers/__tests__/doc-permission.controller.spec.ts

@@ -127,15 +127,15 @@ describe('DocPermissionController', () => {
         const firstParagraph = document.getParagraph('paragraph-one')!;
         const secondParagraph = document.getParagraph('paragraph-two')!;
 
-        await firstSection.getPermission().setEditable(false);
+        await firstSection.getPermission().setReadOnly();
 
         expect(firstSection.getPermission().canEdit()).toBe(false);
         expect(firstParagraph.getPermission().canEdit()).toBe(false);
         expect(secondParagraph.getPermission().canEdit()).toBe(true);
         expect(firstParagraph.setText('Denied')).toBe(false);
         expect(secondParagraph.setText('Allowed')).toBe(true);
 
-        await document.getSection(0)!.getPermission().setEditable(true);
+        await document.getSection(0)!.getPermission().setEditable();
         await document.getParagraph('paragraph-one')!.getPermission().setEditable(false);
         expect(document.getParagraph('paragraph-one')!.setText('Denied again')).toBe(false);
     });

packages/docs/src/facade/f-document-paragraph.ts

@@ -106,7 +106,16 @@ export class FDocumentParagraph extends FBaseInitialable {
         return this._segmentId;
     }
 
-    /** Returns the effective edit permission facade for this paragraph. */
+    /**
+     * Returns this Paragraph's permission facade.
+     * @returns {FDocumentObjectPermission} Permission facade combining Document, Section, and Paragraph Edit points.
+     * @example
+     * ```ts
+     * const paragraph = univerAPI.getActiveDocument()?.getParagraphs()[0];
+     * if (!paragraph) throw new Error('Paragraph not found.');
+     * await paragraph.getPermission().setReadOnly();
+     * ```
+     */
     getPermission(): FDocumentObjectPermission {
         return new FDocumentObjectPermission(
             this._document.getId(),

packages/docs/src/facade/f-document-permission.ts

@@ -19,13 +19,35 @@ import type { DocumentUnitPermissionAction } from '@univerjs/docs';
 import { canEditDocumentTargets, getDocumentPermissionValue, SetDocumentPermissionCommand } from '@univerjs/docs';
 import { UnitAction } from '@univerjs/protocol';
 
+/**
+ * Command-backed permissions for one Document unit.
+ * @hideconstructor
+ */
 export class FDocumentPermission {
     constructor(
         private readonly _unitId: string,
         private readonly _commandService: ICommandService,
         private readonly _permissionService: IPermissionService
     ) {}
 
+    /**
+     * Sets one Document unit permission through the command system.
+     *
+     * Supported actions are Edit, Copy, Print, Export, and Comment. Await the returned promise
+     * before reading the new value or performing an action that depends on it.
+     *
+     * @param {DocumentUnitPermissionAction} action Unit permission action to update.
+     * @param {boolean} value Whether the action is allowed.
+     * @returns {Promise<void>} Resolves after the permission command finishes.
+     * @example Disable copying while keeping the Document editable
+     * ```ts
+     * import { UnitAction } from '@univerjs/protocol';
+     *
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) throw new Error('No active Document.');
+     * await document.getPermission().setPoint(UnitAction.Copy, false);
+     * ```
+     */
     async setPoint(action: DocumentUnitPermissionAction, value: boolean): Promise<void> {
         await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
             unitId: this._unitId,
@@ -35,6 +57,19 @@ export class FDocumentPermission {
         });
     }
 
+    /**
+     * Returns the current value of one Document unit permission.
+     * @param {DocumentUnitPermissionAction} action Unit permission action to query.
+     * @returns {boolean} Whether the action is currently allowed.
+     * @example
+     * ```ts
+     * import { UnitAction } from '@univerjs/protocol';
+     *
+     * const document = univerAPI.getActiveDocument();
+     * const canPrint = document?.getPermission().getPoint(UnitAction.Print) ?? false;
+     * console.log(canPrint);
+     * ```
+     */
     getPoint(action: DocumentUnitPermissionAction): boolean {
         return getDocumentPermissionValue(
             this._permissionService,
@@ -44,19 +79,42 @@ export class FDocumentPermission {
         );
     }
 
-    async setEditable(editable: boolean): Promise<void> {
+    /**
+     * Enables or disables editing for the whole Document.
+     * @param {boolean} [editable] Whether editing is allowed. Defaults to true.
+     * @returns {Promise<void>} Resolves after the permission command finishes.
+     */
+    async setEditable(editable = true): Promise<void> {
         await this.setPoint(UnitAction.Edit, editable);
     }
 
+    /**
+     * Makes the whole Document read-only.
+     * @returns {Promise<void>} Resolves after the permission command finishes.
+     * @example
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) throw new Error('No active Document.');
+     * await document.getPermission().setReadOnly();
+     * ```
+     */
     async setReadOnly(): Promise<void> {
         await this.setEditable(false);
     }
 
+    /**
+     * Returns whether the whole Document is currently editable.
+     * @returns {boolean} Whether Document editing is allowed.
+     */
     canEdit(): boolean {
         return this.getPoint(UnitAction.Edit);
     }
 }
 
+/**
+ * Command-backed Edit permission for one stable Document object.
+ * @hideconstructor
+ */
 export class FDocumentObjectPermission {
     constructor(
         private readonly _unitId: string,
@@ -66,7 +124,23 @@ export class FDocumentObjectPermission {
         private readonly _getParentObjectIds: () => string[] = () => []
     ) {}
 
-    async setEditable(editable: boolean): Promise<void> {
+    /**
+     * Enables or disables editing for this stable Document object.
+     *
+     * This changes only the object's Edit point. `canEdit()` also applies the Document unit and
+     * parent Section or Paragraph ceilings.
+     *
+     * @param {boolean} [editable] Whether object editing is allowed. Defaults to true.
+     * @returns {Promise<void>} Resolves after the permission command finishes.
+     * @example Restore editing for a paragraph
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * const paragraph = document?.getParagraph('paragraph-1');
+     * if (!paragraph) throw new Error('Paragraph not found.');
+     * await paragraph.getPermission().setEditable();
+     * ```
+     */
+    async setEditable(editable = true): Promise<void> {
         await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
             unitId: this._unitId,
             objectId: this._objectId,
@@ -75,6 +149,25 @@ export class FDocumentObjectPermission {
         });
     }
 
+    /**
+     * Makes this stable Document object read-only.
+     * @returns {Promise<void>} Resolves after the permission command finishes.
+     * @example
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * const section = document?.getSection(0);
+     * if (!section) throw new Error('Section not found.');
+     * await section.getPermission().setReadOnly();
+     * ```
+     */
+    async setReadOnly(): Promise<void> {
+        await this.setEditable(false);
+    }
+
+    /**
+     * Returns the effective Edit result after applying the Document, parent, and object permissions.
+     * @returns {boolean} Whether the object is currently editable.
+     */
     canEdit(): boolean {
         return canEditDocumentTargets(
             this._permissionService,

packages/docs/src/facade/f-document-section.ts

@@ -109,7 +109,16 @@ export class FDocumentSection {
         return this._sectionId;
     }
 
-    /** Returns the effective edit permission facade for this section. */
+    /**
+     * Returns this Section's permission facade.
+     * @returns {FDocumentObjectPermission} Permission facade combining Document and Section Edit points.
+     * @example
+     * ```ts
+     * const section = univerAPI.getActiveDocument()?.getSection(0);
+     * if (!section) throw new Error('Section not found.');
+     * await section.getPermission().setReadOnly();
+     * ```
+     */
     getPermission(): FDocumentObjectPermission {
         return new FDocumentObjectPermission(
             this._document.getId(),

packages/docs/src/facade/f-document.ts

@@ -185,12 +185,35 @@ export class FDocument extends FBaseInitialable {
         return this.id;
     }
 
-    /** Returns the effective permission facade for this document. */
+    /**
+     * Returns the Document unit permission facade.
+     * @returns {FDocumentPermission} Permission facade for Edit, Copy, Print, Export, and Comment.
+     * @example
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) throw new Error('No active Document.');
+     * await document.getPermission().setReadOnly();
+     * ```
+     */
     getPermission(): FDocumentPermission {
         return new FDocumentPermission(this.id, this._commandService, this._permissionService);
     }
 
-    /** Returns an edit permission facade for a stable document entity id. */
+    /**
+     * Returns the permission facade for an entity with a stable id, such as a Table, Drawing, or Custom Block.
+     *
+     * Parent Section and Paragraph permission ceilings are resolved from the current Document model.
+     * @param {string} segmentId Segment id, or an empty string for the main body.
+     * @param {string} entityType Stable entity type used by the owning Doc feature.
+     * @param {string} entityId Stable entity id.
+     * @returns {FDocumentObjectPermission} Effective permission facade for the entity.
+     * @example Make one table read-only
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) throw new Error('No active Document.');
+     * await document.getEntityPermission('', 'table', 'table-1').setReadOnly();
+     * ```
+     */
     getEntityPermission(segmentId: string, entityType: string, entityId: string): FDocumentObjectPermission {
         return new FDocumentObjectPermission(
             this.id,