@univerjs/docs 1.0.0-alpha.0 → 1.0.0-alpha.1

package/lib/index.js

@@ -532,7 +532,7 @@ const UpdateTextCommand = {
 //#endregion
 //#region package.json
 var name = "@univerjs/docs";
-var version = "1.0.0-alpha.0";
+var version = "1.0.0-alpha.1";
 
 //#endregion
 //#region src/commands/mutations/docs-rename.mutation.ts
@@ -621,6 +621,33 @@ DocCustomRangeController = __decorate([
 	__decorateParam(2, IUniverInstanceService)
 ], DocCustomRangeController);
 
+//#endregion
+//#region src/services/doc-block-move-validator.service.ts
+var DocBlockMoveValidatorService = class extends Disposable {
+	constructor(..._args) {
+		super(..._args);
+		_defineProperty(this, "_validators", []);
+		_defineProperty(this, "_transformers", []);
+	}
+	registerValidator(validator) {
+		this._validators.push(validator);
+		return this.disposeWithMe(toDisposable(() => remove(this._validators, validator)));
+	}
+	registerTransformer(transformer) {
+		this._transformers.push(transformer);
+		return this.disposeWithMe(toDisposable(() => remove(this._transformers, transformer)));
+	}
+	canMoveBlock(context) {
+		return this._validators.every((validator) => validator(context));
+	}
+	transformMoveResult(context) {
+		return this._transformers.reduce((result, transformer) => transformer({
+			...context,
+			result
+		}), context.result);
+	}
+};
+
 //#endregion
 //#region src/services/doc-content-insert.service.ts
 /**
@@ -839,6 +866,7 @@ let UniverDocsPlugin = class UniverDocsPlugin extends Plugin {
 			[DocSelectionManagerService],
 			[DocStateEmitService],
 			[DocStateChangeManagerService],
+			[DocBlockMoveValidatorService],
 			[DocContentInsertService],
 			[DocCustomRangeController]
 		].forEach((d) => this._injector.add(d));
@@ -1064,4 +1092,4 @@ function replaceSelectionFactory(accessor, params) {
 }
 
 //#endregion
-export { DOC_INTERCEPTOR_POINT, DeleteTextCommand, DocContentInsertService, DocInterceptorService, DocSelectionManagerService, DocSkeletonManagerService, DocStateChangeManagerService, DocStateEmitService, IDocStateChangeInterceptorService, InsertTextCommand, RichTextEditingMutation, SetTextSelectionsOperation, UniverDocsPlugin, UpdateTextCommand, addCustomRangeBySelectionFactory, addCustomRangeFactory, deleteCustomRangeFactory, replaceSelectionFactory };
+export { DOC_INTERCEPTOR_POINT, DeleteTextCommand, DocBlockMoveValidatorService, DocContentInsertService, DocInterceptorService, DocSelectionManagerService, DocSkeletonManagerService, DocStateChangeManagerService, DocStateEmitService, IDocStateChangeInterceptorService, InsertTextCommand, RichTextEditingMutation, SetTextSelectionsOperation, UniverDocsPlugin, UpdateTextCommand, addCustomRangeBySelectionFactory, addCustomRangeFactory, deleteCustomRangeFactory, replaceSelectionFactory };

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

@@ -0,0 +1,132 @@
+/**
+ * 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 { DocumentBlockRangeType, IDocumentBlockRange, Injector } from '@univerjs/core';
+import type { FDocumentBody, IFDocumentBodyEdit } from './f-document-body';
+import type { IFDocumentElementInfo } from './f-document-element';
+import { FDocumentElement } from './f-document-element';
+interface IFDocumentBlockRangeMixin {
+    asBlockRange(): FDocumentBlockRange;
+}
+/**
+ * A facade wrapper for document block ranges, such as callout, quote, and code blocks.
+ *
+ * Block range identity is backed by the persisted `IDocumentBlockRange.blockId`,
+ * so wrappers can be re-resolved after text is inserted before the block range.
+ *
+ * @hideconstructor
+ */
+export declare class FDocumentBlockRange extends FDocumentElement {
+    protected readonly body: FDocumentBody;
+    protected readonly bodyEdit: IFDocumentBodyEdit;
+    protected readonly info: IFDocumentElementInfo;
+    protected readonly injector: Injector;
+    constructor(body: FDocumentBody, bodyEdit: IFDocumentBodyEdit, info: IFDocumentElementInfo, injector: Injector);
+    /**
+     * Get the top-level block range data model.
+     * @returns {IDocumentBlockRange} The block range data model.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isBlockRange()) {
+     *   const blockRange = element.asBlockRange();
+     *   console.log(blockRange.getBlockRange());
+     * }
+     * ```
+     */
+    getBlockRange(): IDocumentBlockRange;
+    /**
+     * Get the block range type.
+     * @returns {DocumentBlockRangeType} The block type, such as callout, quote, or code.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isBlockRange()) {
+     *   const blockRange = element.asBlockRange();
+     *   console.log(blockRange.getBlockType());
+     * }
+     * ```
+     */
+    getBlockType(): DocumentBlockRangeType;
+    /**
+     * Get the plain text inside this block range.
+     * @returns {string} The block range text.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isBlockRange()) {
+     *   const blockRange = element.asBlockRange();
+     *   console.log(blockRange.getText());
+     * }
+     * ```
+     */
+    getText(): string;
+    /**
+     * Replace the plain text inside this block range.
+     * @param {string} text The replacement text.
+     * @returns {boolean} `true` if the block range text was replaced.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isBlockRange()) {
+     *   const blockRange = element.asBlockRange();
+     *   blockRange.setText('Updated block text');
+     *   console.log(blockRange.getText());
+     * }
+     * ```
+     */
+    setText(text: string): boolean;
+    /**
+     * Remove this block range wrapper from the body.
+     *
+     * This currently removes the block range and its content, matching
+     * `remove()`.
+     *
+     * @returns {boolean} `true` if the block range content was removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isBlockRange()) {
+     *   const blockRange = element.asBlockRange();
+     *   const removed = blockRange.unwrap();
+     *   console.log(removed ? 'Block range removed' : 'Failed to remove block range');
+     * }
+     * ```
+     */
+    unwrap(): boolean;
+}
+export declare class FDocumentBlockRangeMixin extends FDocumentElement {
+    asBlockRange(): FDocumentBlockRange;
+}
+declare module '@univerjs/docs/facade' {
+    interface FDocumentElement extends IFDocumentBlockRangeMixin {
+    }
+}
+export {};

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

@@ -0,0 +1,276 @@
+/**
+ * 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, IDocumentBody, Injector, ITextStyle } from '@univerjs/core';
+import type { FDocumentBlockRange } from './f-document-block-range';
+import type { FDocumentCustomBlock } from './f-document-custom-block';
+import type { IFDocumentElementInfo } from './f-document-element';
+import type { FDocumentTable } from './f-document-table';
+import { UpdateDocsAttributeType } from '@univerjs/core';
+import { FDocumentElement } from './f-document-element';
+import { FDocumentParagraph } from './f-document-paragraph';
+/**
+ * A text range in a document segment. Offsets are zero-based positions in the segment data stream.
+ */
+export interface IFDocumentTextRange {
+    /** The inclusive start offset of the range. */
+    startOffset: number;
+    /** The exclusive end offset of the range. */
+    endOffset: number;
+    /** The header/footer segment id. Omit or use an empty string for the main body. */
+    segmentId?: string;
+}
+export interface IFDocumentBodyEdit {
+    replaceRange: (range: IFDocumentTextRange, body: IDocumentBody) => boolean;
+    retainRange: (range: IFDocumentTextRange, body: IDocumentBody, coverType: UpdateDocsAttributeType) => boolean;
+}
+/**
+ * A Facade API object bounded to a document body or header/footer segment.
+ * It provides Google Docs-like element access and range editing methods.
+ *
+ * Paragraph elements use their persisted `paragraphId`. Tables, block ranges, and
+ * custom blocks use their persisted ids.
+ *
+ * @hideconstructor
+ */
+export declare class FDocumentBody {
+    private readonly _documentDataModel;
+    private readonly _injector;
+    private readonly _segmentId;
+    private readonly _bodyEdit;
+    constructor(_documentDataModel: DocumentDataModel, _injector: Injector, _segmentId?: string);
+    /**
+     * Get the segment id of this document body facade.
+     * The main body has an empty string segment id.
+     * The header and footer FDocumentBody instances have their respective segment ids.
+     * @returns {string} The segment id of this document body facade.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * console.log(fDocumentBody.getSegmentId());
+     * ```
+     */
+    getSegmentId(): string;
+    /**
+     * Get the underlying document body snapshot.
+     * @returns {IDocumentBody} The document body snapshot.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * console.log(fDocumentBody.getBody());
+     * ```
+     */
+    getBody(): IDocumentBody;
+    /**
+     * Get a list of top-level child elements in the body.
+     * @returns {FDocumentElement[]} The list of top-level document elements.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const elements = fDocumentBody.getElements();
+     * console.log(elements);
+     * ```
+     */
+    getElements(): FDocumentElement[];
+    /**
+     * Get a top-level child element by child index.
+     * @param {number} index The zero-based child index.
+     * @returns {FDocumentElement} The top-level child element wrapper.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     * console.log(element);
+     * ```
+     */
+    getElement(index: number): FDocumentElement | null;
+    /**
+     * Get the current child index of an element handle.
+     * The index is resolved from the element key, so a paragraph handle keeps pointing
+     * to the same paragraph after facade edits insert content before it.
+     * @param {FDocumentElement} element The element handle to locate.
+     * @returns {number} The current zero-based child index.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     * console.log(fDocumentBody.getElementIndex(element));
+     * ```
+     */
+    getElementIndex(element: FDocumentElement): number;
+    /**
+     * Insert plain text at a document body offset.
+     * @param {number} index The zero-based insertion offset.
+     * @param {string} text The plain text to insert.
+     * @returns {boolean} `true` if the edit was applied.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * fDocumentBody.insertText(0, 'Hello ');
+     * ```
+     */
+    insertText(index: number, text: string): boolean;
+    /**
+     * Apply text style to a body range.
+     * @param {IFDocumentTextRange} range The range to style.
+     * @param {ITextStyle} style The Univer text style patch.
+     * @returns {boolean} `true` if the style was applied.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * fDocumentBody.setTextStyle({ startOffset: 0, endOffset: 5 }, { bl: 1 });
+     * ```
+     */
+    setTextStyle(range: IFDocumentTextRange, style: ITextStyle): boolean;
+    /**
+     * Insert a plain-text paragraph before the paragraph at the given paragraph index.
+     * @param {number} index The zero-based paragraph insertion index.
+     * @param {string} text The paragraph text. Defaults to an empty paragraph.
+     * @returns {FDocumentParagraph} The inserted paragraph wrapper.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const paragraph = fDocumentBody.insertParagraph(0, 'Document title');
+     * paragraph.appendText(' suffix');
+     * ```
+     */
+    insertParagraph(index: number, text?: string): FDocumentParagraph;
+    /**
+     * Append a plain-text paragraph at the end of the body.
+     * @param {string} text The paragraph text. Defaults to an empty paragraph.
+     * @returns {FDocumentParagraph} The appended paragraph wrapper.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const paragraph = fDocumentBody.appendParagraph('Summary');
+     * console.log(paragraph.getText());
+     * ```
+     */
+    appendParagraph(text?: string): FDocumentParagraph;
+    /**
+     * Delete a range from the body.
+     * @param {IFDocumentTextRange} range The text range to delete.
+     * @returns {boolean} `true` if the range was deleted.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * fDocumentBody.deleteRange({ startOffset: 0, endOffset: 5 });
+     * ```
+     */
+    deleteRange(range: IFDocumentTextRange): boolean;
+    /**
+     * Remove a paragraph by paragraph id.
+     * @param {FDocumentParagraph} paragraph The paragraph handle to remove.
+     * @returns {boolean} `true` if the paragraph was removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isParagraph()) {
+     *   const paragraph = element.asParagraph();
+     *   const removed = fDocumentBody.removeParagraph(paragraph);
+     *   console.log(removed ? 'Paragraph removed' : 'Failed to remove paragraph');
+     * }
+     * ```
+     */
+    removeParagraph(paragraph: FDocumentParagraph): boolean;
+    /**
+     * Remove a callout, quote, or code block range and its content.
+     * @param {FDocumentBlockRange} blockRange The block range handle to remove.
+     * @returns {boolean} `true` if the block range content was removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isBlockRange()) {
+     *   const blockRange = element.asBlockRange();
+     *   const removed = fDocumentBody.removeBlockRange(blockRange);
+     *   console.log(removed ? 'Block range removed' : 'Failed to remove block range');
+     * }
+     * ```
+     */
+    removeBlockRange(blockRange: FDocumentBlockRange): boolean;
+    /**
+     * Remove a table marker and its content range.
+     * @returns {boolean} `true` if the table range was removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isTable()) {
+     *   const table = element.asTable();
+     *   const removed = fDocumentBody.removeTable(table);
+     *   console.log(removed ? 'Table removed' : 'Failed to remove table');
+     * }
+     * ```
+     */
+    removeTable(table: FDocumentTable): boolean;
+    /**
+     * Remove a custom block marker and its placeholder character.
+     * @param {FDocumentCustomBlock} customBlock The custom block handle to remove.
+     * @returns {boolean} `true` if the custom block placeholder was removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isCustomBlock()) {
+     *   const customBlock = element.asCustomBlock();
+     *   const removed = fDocumentBody.removeCustomBlock(customBlock);
+     *   console.log(removed ? 'Custom block removed' : 'Failed to remove custom block');
+     * }
+     * ```
+     */
+    removeCustomBlock(customBlock: FDocumentCustomBlock): boolean;
+    /**
+     * Resolve an element key to its current child metadata.
+     * @param {FDocumentElement} element The element handle to resolve.
+     * @returns {IFDocumentElementInfo} The current child metadata used by the facade.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     * const resolved = fDocumentBody.resolveElement(element);
+     * console.log(resolved);
+     * ```
+     */
+    resolveElement(element: FDocumentElement): IFDocumentElementInfo;
+    private _getChildren;
+    private _resolveParagraphInfo;
+    private _getParagraphId;
+    private _getParagraphInsertOffset;
+    private _replaceBodyRange;
+    private _retainBodyRange;
+    private _ensureTextRuns;
+    private _executeTextX;
+}

package/lib/types/facade/f-document-custom-block.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { ICustomBlock, Injector } from '@univerjs/core';
+import type { FDocumentBody, IFDocumentBodyEdit } from './f-document-body';
+import type { IFDocumentElementInfo } from './f-document-element';
+import { FDocumentElement } from './f-document-element';
+interface IFDocumentCustomBlockMixin {
+    asCustomBlock(): FDocumentCustomBlock;
+}
+/**
+ * A facade wrapper for document top-level custom blocks.
+ * @hideconstructor
+ */
+export declare class FDocumentCustomBlock extends FDocumentElement {
+    protected readonly body: FDocumentBody;
+    protected readonly bodyEdit: IFDocumentBodyEdit;
+    protected readonly info: IFDocumentElementInfo;
+    protected readonly injector: Injector;
+    constructor(body: FDocumentBody, bodyEdit: IFDocumentBodyEdit, info: IFDocumentElementInfo, injector: Injector);
+    /**
+     * Get the custom block marker.
+     * @returns {ICustomBlock} The custom block marker.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const fDocumentBody = fDocument.getBody();
+     * const element = fDocumentBody.getElement(0);
+     *
+     * if (element?.isCustomBlock()) {
+     *   const customBlock = element.asCustomBlock();
+     *   console.log(customBlock.getCustomBlock());
+     * }
+     * ```
+     */
+    getCustomBlock(): ICustomBlock;
+}
+export declare class FDocumentCustomBlockMixin extends FDocumentElement {
+    asCustomBlock(): FDocumentCustomBlock;
+}
+declare module '@univerjs/docs/facade' {
+    interface FDocumentElement extends IFDocumentCustomBlockMixin {
+    }
+}
+export {};