@univerjs/docs 1.0.0-insiders.20260813-7c9aa50 → 1.0.0

package/lib/types/commands/commands/core-editing.command.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { ICommand, IDocumentBody, IDocumentData, ITextRange, UpdateDocsAttributeType } from '@univerjs/core';
+import type { ICommand, IDocumentBody, IDocumentData, ITextRange, Nullable, UpdateDocsAttributeType } from '@univerjs/core';
 import type { ITextRangeWithStyle } from '@univerjs/engine-render';
 import { DeleteDirection } from '@univerjs/core';
 export interface IInsertTextCommandParams {
@@ -22,6 +22,10 @@ export interface IInsertTextCommandParams {
     range: ITextRange;
     segmentId?: string;
     cursorOffset?: number;
+    debounce?: boolean;
+    textRanges?: Nullable<ITextRangeWithStyle[]>;
+    noNeedSetTextRange?: boolean;
+    isEditing?: boolean;
 }
 /**
  * The command to insert text. The changed range could be non-collapsed, mainly use in line break and normal input.

package/lib/types/commands/commands/set-document-permission.command.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 type { ICommand, IObjectPermissionPolicy } from '@univerjs/core';
+import type { DocumentUnitPermissionAction } from '../../services/permission/document-permission';
+export interface ISetDocumentPermissionCommandParams {
+    unitId: string;
+    objectId: string;
+    action: DocumentUnitPermissionAction;
+    value: boolean;
+    policy?: IObjectPermissionPolicy;
+    /** Remove the child permission rule and restore inherited rights; never deletes content. */
+    remove?: boolean;
+}
+export declare const SetDocumentPermissionCommand: ICommand<ISetDocumentPermissionCommandParams>;

package/lib/types/commands/commands/set-document-permissions.command.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { ICommand, IObjectPermissionBatchResult, ISetObjectPermissionsCommandParams } from '@univerjs/core';
+export declare const SetDocumentPermissionsCommand: ICommand<ISetObjectPermissionsCommandParams, IObjectPermissionBatchResult>;

package/lib/types/commands/mutations/core-editing.mutation-id.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export declare const RICH_TEXT_EDITING_MUTATION_ID = "doc.mutation.rich-text-editing";

package/lib/types/commands/mutations/core-editing.mutation.d.ts

@@ -13,10 +13,25 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IMutation, IMutationCommonParams, JSONXActions, Nullable } from '@univerjs/core';
+import type { IMutation, IMutationCommonParams, JSONXActions, Nullable, TPriority } from '@univerjs/core';
 import type { ITextRangeWithStyle } from '@univerjs/engine-render';
+export declare enum DocHistoryAction {
+    DeleteChart = "delete-chart",
+    DeleteDivider = "delete-divider",
+    DeleteImage = "delete-image",
+    DeleteShape = "delete-shape",
+    EditTableCell = "edit-table-cell",
+    FormatParagraph = "format-paragraph",
+    InsertCustomRange = "insert-custom-range",
+    UpdateImage = "update-image",
+    UpdatePageLayout = "update-page-layout"
+}
 export interface IRichTextEditingMutationParams extends IMutationCommonParams {
     unitId: string;
+    /** Host-owned transient layout state, used only by local editor history. */
+    layoutState?: unknown;
+    historyAction?: string;
+    historyActions?: string[];
     actions: JSONXActions;
     textRanges: Nullable<ITextRangeWithStyle[]>;
     segmentId?: string;
@@ -32,6 +47,12 @@ export interface IRichTextEditingMutationParams extends IMutationCommonParams {
     isEditing?: boolean;
     syncer?: string;
 }
+/**
+ * Transforms document selections through the same JSONX actions applied by a rich-text mutation.
+ * Collaboration and rendering use this shared offset rule so the Main interaction window follows
+ * the transformed local caret before an authoritative background layout is published.
+ */
+export declare function transformDocumentTextRanges(actions: JSONXActions, textRanges: ITextRangeWithStyle[], priority?: TPriority): ITextRangeWithStyle[];
 /**
  * The core mutator to change rich text actions. The execution result would be undo mutation params. Could be directly
  * send to undo redo service (will be used by the triggering command).

package/lib/types/commands/mutations/doc-structure-mutation-validation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type { DocumentDataModel, JSONXActions } from '@univerjs/core';
+export declare function isDocSdtMutationAllowed(documentDataModel: DocumentDataModel, segmentId: string, actions: JSONXActions): boolean;
+export declare function validateDocStructureMutation(documentDataModel: DocumentDataModel, segmentId: string, actions: JSONXActions, undoActions: JSONXActions, isHistoryReplay?: boolean): boolean;

package/lib/types/commands/mutations/set-document-permission-rule.mutation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { IMutation, ISetObjectPermissionRuleMutationParams } from '@univerjs/core';
+export declare const SetDocumentPermissionRuleMutation: IMutation<ISetObjectPermissionRuleMutationParams>;

package/lib/types/commands/mutations/set-document-permission-rules.mutation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { IMutation, ISetObjectPermissionRulesMutationParams } from '@univerjs/core';
+export declare const SetDocumentPermissionRulesMutation: IMutation<ISetObjectPermissionRulesMutationParams>;

package/lib/types/controllers/doc-permission.controller.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 { Disposable, ICommandService, Injector, IPermissionService, IUniverInstanceService } from '@univerjs/core';
+export declare class DocPermissionController extends Disposable {
+    private readonly _injector;
+    private readonly _commandService;
+    private readonly _permissionService;
+    private readonly _univerInstanceService;
+    constructor(_injector: Injector, _commandService: ICommandService, _permissionService: IPermissionService, _univerInstanceService: IUniverInstanceService);
+    private _registerUnitPermissionPoints;
+    private _check;
+    private _resolveTargetObjectIds;
+}

package/lib/types/facade/f-document-paragraph.d.ts

@@ -16,8 +16,9 @@
 import type { Injector, IParagraph, IParagraphStyle } from '@univerjs/core';
 import type { FDocument } from './f-document';
 import type { IFDocumentTextRange } from './utils';
-import { ICommandService } from '@univerjs/core';
+import { ICommandService, IPermissionService } from '@univerjs/core';
 import { FBaseInitialable } from '@univerjs/core/facade';
+import { FDocumentObjectPermission } from './f-document-permission';
 import { FDocumentTextRange } from './f-document-text-range';
 /**
  * Resolved paragraph metadata in the the document body.
@@ -62,7 +63,8 @@ export declare class FDocumentParagraph extends FBaseInitialable {
     protected readonly _segmentId: string;
     protected readonly _injector: Injector;
     private readonly _commandService;
-    constructor(_document: FDocument, _paragraphId: string, _segmentId: string | undefined, _injector: Injector, _commandService: ICommandService);
+    private readonly _permissionService;
+    constructor(_document: FDocument, _paragraphId: string, _segmentId: string | undefined, _injector: Injector, _commandService: ICommandService, _permissionService: IPermissionService);
     /**
      * Get the persisted paragraph id.
      * @returns {string} The paragraph id.
@@ -87,6 +89,17 @@ export declare class FDocumentParagraph extends FBaseInitialable {
      * ```
      */
     getSegmentId(): string;
+    /**
+     * 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;
     /**
      * Get this paragraph's metadata.
      * @returns {IFDocumentParagraphInfo} The paragraph info.

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

@@ -0,0 +1,177 @@
+/**
+ * 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 type { ICommandService, IObjectPermissionBatchResult, IObjectPermissionChange, IPermissionService } from '@univerjs/core';
+import type { DocumentUnitPermissionAction } from '@univerjs/docs';
+/**
+ * Command-backed permissions for one Document unit.
+ * @hideconstructor
+ */
+export declare class FDocumentPermission {
+    private readonly _unitId;
+    private readonly _commandService;
+    private readonly _permissionService;
+    constructor(_unitId: string, _commandService: ICommandService, _permissionService: IPermissionService);
+    /**
+     * Creates or updates child-object edit policies in this unit; policy: null removes protection and restores inheritance.
+     *
+     * Requires Authz support and objectPermissionTypes configured for every target type. File and parent restrictions
+     * still apply. Use the exported permission object ID helpers, not raw object IDs or server permission IDs.
+     * The batch must be nonempty, contain distinct objects, and belong to this unit; file-wide policies are excluded.
+     * Other targets use getDocumentSectionPermissionObjectId and getDocumentEntityPermissionObjectId.
+     *
+     * edit: 'all' allows Unit editors, 'owner' restricts editing to the object owner, and 'members' selects existing
+     * Unit collaborators. Pass their collaborator records from the member service; this does not invite new users.
+     * Use strategies: [] for the default Edit strategy; child-object strategies support only UnitAction.Edit.
+     *
+     * Authz writes execute per object and can partially succeed. Inspect failed before retrying only those objects.
+     * refreshError means writes finished but permission readback failed; do not retry succeeded objects for that error.
+     * Successful binding changes share one undo entry; existing remote policy edits are not undoable.
+     * @param {IObjectPermissionChange[]} changes Permission object IDs and policies to apply.
+     * @returns {Promise<IObjectPermissionBatchResult>} Successful object IDs, per-object failures, and optional readback error.
+     * @throws {Error} Invalid batches or unsupported object types are rejected before Authz writes.
+     * @example Set owner/member editing and remove protection in one batch
+     * ```ts
+     * import type { ICollaborator } from '@univerjs/protocol';
+     * import { getDocumentParagraphPermissionObjectId } from '@univerjs/docs';
+     *
+     * // selectedMembers comes from the existing Unit collaborator picker/service.
+     * async function applyPermissions(selectedMembers: ICollaborator[]) {
+     *     if (!selectedMembers.length) throw new Error('Select at least one Unit collaborator.');
+     *     const document = univerAPI.getActiveDocument();
+     *     if (!document) throw new Error('No active document.');
+     *     const objects = document.getParagraphs().slice(0, 3);
+     *     const objectIds = objects.map((paragraph) =>
+     *         getDocumentParagraphPermissionObjectId(paragraph.getSegmentId(), paragraph.getId()));
+     *     if (objectIds.length < 3) throw new Error('This example requires three paragraphs.');
+     *     const result = await document.getPermission().setObjectPermissions([
+     *         { objectId: objectIds[0], policy: { edit: 'owner', collaborators: [], strategies: [] } },
+     *         { objectId: objectIds[1], policy: { edit: 'members', collaborators: selectedMembers, strategies: [] } },
+     *         { objectId: objectIds[2], policy: null },
+     *     ]);
+     *     // A policy creates protection if absent, or updates the existing policy when already configured.
+     *     for (const failure of result.failed) {
+     *         console.error(failure.objectId, failure.error);
+     *     }
+     *     if (result.refreshError) {
+     *         console.error(result.refreshError);
+     *     }
+     *     return result;
+     * }
+     * ```
+     */
+    setObjectPermissions(changes: IObjectPermissionChange[]): Promise<IObjectPermissionBatchResult>;
+    /**
+     * 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);
+     * ```
+     */
+    setPoint(action: DocumentUnitPermissionAction, value: boolean): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    setEditable(editable?: boolean): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    setReadOnly(): Promise<void>;
+    /**
+     * Returns whether the whole Document is currently editable.
+     * @returns {boolean} Whether Document editing is allowed.
+     */
+    canEdit(): boolean;
+}
+/**
+ * Command-backed Edit permission for one stable Document object.
+ * @hideconstructor
+ */
+export declare class FDocumentObjectPermission {
+    private readonly _unitId;
+    private readonly _objectId;
+    private readonly _commandService;
+    private readonly _permissionService;
+    private readonly _getParentObjectIds;
+    constructor(_unitId: string, _objectId: string, _commandService: ICommandService, _permissionService: IPermissionService, _getParentObjectIds?: () => string[]);
+    /**
+     * 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?.getParagraphs()[0];
+     * if (!paragraph) throw new Error('Paragraph not found.');
+     * await paragraph.getPermission().setEditable();
+     * ```
+     */
+    setEditable(editable?: boolean): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    setReadOnly(): Promise<void>;
+    /**
+     * Returns the effective Edit result after applying the Document, parent, and object permissions.
+     * @returns {boolean} Whether the object is currently editable.
+     */
+    canEdit(): boolean;
+}

package/lib/types/facade/f-document-section.d.ts

@@ -17,7 +17,8 @@ import type { ISectionBreak, ISectionColumnProperties, SectionHeaderFooterKind,
 import type { IEffectiveSectionPageSetup, IHeaderFooterProps } from '@univerjs/docs';
 import type { FDocument } from './f-document';
 import type { IFDocumentTextRange } from './utils';
-import { ColumnSeparatorType, ICommandService, SectionType } from '@univerjs/core';
+import { ColumnSeparatorType, ICommandService, IPermissionService, SectionType } from '@univerjs/core';
+import { FDocumentObjectPermission } from './f-document-permission';
 export interface IFDocumentSectionColumnOptions {
     /** Gap after each column except the last, in 96-DPI layout pixels. */
     gap?: number;
@@ -61,7 +62,8 @@ export declare class FDocumentSection {
     private readonly _document;
     private readonly _sectionId;
     private readonly _commandService;
-    constructor(_document: FDocument, _sectionId: string, _commandService: ICommandService);
+    private readonly _permissionService;
+    constructor(_document: FDocument, _sectionId: string, _commandService: ICommandService, _permissionService: IPermissionService);
     /**
      * Returns the persisted section id.
      * @example
@@ -71,6 +73,17 @@ export declare class FDocumentSection {
      * ```
      */
     getId(): string;
+    /**
+     * 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;
     /**
      * Returns the current zero-based section index.
      * @example
@@ -121,6 +134,10 @@ export declare class FDocumentSection {
      * Sets equal or explicitly sized columns for this traditional section.
      * Use `columnCount = 1` to restore normal single-column layout.
      * `gap` and `widths` are in 96-DPI layout pixels.
+     * @param {number} columnCount Positive integer column count.
+     * @param {IFDocumentSectionColumnOptions} [options] Column widths, gap (default 18 pixels), and separator (default none).
+     * @returns {boolean} Whether the section update succeeded.
+     * @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -132,6 +149,10 @@ export declare class FDocumentSection {
     setColumns(columnCount: number, options?: IFDocumentSectionColumnOptions): boolean;
     /**
      * Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.
+     * @param {ISectionColumnProperties[]} columns Explicit widths and trailing spaces; an empty array restores a single column.
+     * @param {ColumnSeparatorType} [separator] Column separator style. Defaults to `ColumnSeparatorType.NONE`.
+     * @returns {boolean} Whether the section update succeeded.
+     * @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -258,6 +279,8 @@ export declare class FDocumentSection {
     setPageSetup(pageSetup: FDocumentSectionPageSetup): boolean;
     /**
      * Ensures a header segment linked specifically to this section.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {string} The existing or newly created section-specific segment ID.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -272,6 +295,8 @@ export declare class FDocumentSection {
     ensureHeader(variant?: SectionHeaderFooterVariant): string;
     /**
      * Ensures a footer segment linked specifically to this section.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {string} The existing or newly created section-specific segment ID.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -286,6 +311,8 @@ export declare class FDocumentSection {
     ensureFooter(variant?: SectionHeaderFooterVariant): string;
     /**
      * Returns the effective header id after resolving links to previous sections.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {string | null} The effective segment ID, or `null` if no segment is available.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -295,6 +322,8 @@ export declare class FDocumentSection {
     getHeaderId(variant?: SectionHeaderFooterVariant): string | null;
     /**
      * Returns the effective footer id after resolving links to previous sections.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {string | null} The effective segment ID, or `null` if no segment is available.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -304,6 +333,8 @@ export declare class FDocumentSection {
     getFooterId(variant?: SectionHeaderFooterVariant): string | null;
     /**
      * Whether this header variant inherits the previous section's reference.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {boolean} Whether this variant inherits from the previous section.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -313,6 +344,8 @@ export declare class FDocumentSection {
     isHeaderLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean;
     /**
      * Whether this footer variant inherits the previous section's reference.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {boolean} Whether this variant inherits from the previous section.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -322,6 +355,9 @@ export declare class FDocumentSection {
     isFooterLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean;
     /**
      * Links or unlinks this header variant. Unlinking clones the inherited header.
+     * @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {boolean} Whether the link update succeeded.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -333,6 +369,9 @@ export declare class FDocumentSection {
     setHeaderLinkedToPrevious(linkedToPrevious: boolean, variant?: SectionHeaderFooterVariant): boolean;
     /**
      * Links or unlinks this footer variant. Unlinking clones the inherited footer.
+     * @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+     * @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+     * @returns {boolean} Whether the link update succeeded.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -345,6 +384,8 @@ export declare class FDocumentSection {
     /**
      * Updates header/footer switches and margins on this section break.
      * `marginHeader` and `marginFooter` are in 96-DPI layout pixels.
+     * @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+     * @returns {boolean} Whether the update command succeeded.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();

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

@@ -16,6 +16,7 @@
 import type { Injector, ITextStyle } from '@univerjs/core';
 import type { FDocument } from './f-document';
 import type { IFDocumentTextRange } from './utils';
+import { ICommandService } from '@univerjs/core';
 import { FBaseInitialable } from '@univerjs/core/facade';
 /** A clipped text-style run in document offsets. */
 export interface IFDocumentTextStyleRun {
@@ -48,7 +49,8 @@ export declare class FDocumentTextRange extends FBaseInitialable {
     protected readonly _endOffset: number;
     protected readonly _segmentId: string;
     protected readonly _injector: Injector;
-    constructor(_document: FDocument, _startOffset: number, _endOffset: number, _segmentId: string, _injector: Injector);
+    private readonly _commandService;
+    constructor(_document: FDocument, _startOffset: number, _endOffset: number, _segmentId: string, _injector: Injector, _commandService: ICommandService);
     /**
      * Returns the serializable document range.
      * @example
@@ -106,6 +108,8 @@ export declare class FDocumentTextRange extends FBaseInitialable {
      * Existing text-run splitting, merging, and normalization are handled by
      * the document mutation pipeline.
      * `style.fs` is a font size in points (pt), not CSS pixels.
+     * @param {ITextStyle} style Text-style properties to merge into the range.
+     * @returns {boolean} Whether the style update succeeded; `false` for an empty range.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -116,6 +120,8 @@ export declare class FDocumentTextRange extends FBaseInitialable {
     setTextStyle(style: ITextStyle): boolean;
     /**
      * Replaces the range with plain text while preserving document mutation semantics.
+     * @param {string} text Replacement plain text. An empty string deletes the range.
+     * @returns {boolean} Whether the replacement succeeded.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();