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

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

@@ -1,535 +0,0 @@
-/**
- * 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, ICommandService, ICustomBlock, ICustomTable, IDocumentBlockRange, IDocumentBody, IParagraph, IParagraphStyle, ITextStyle } from '@univerjs/core';
-import type { DocElementRegistry, FDocElementType } from './doc-element-registry';
-import { FDocElement } from './f-doc-element';
-import { FDocParagraph } from './f-doc-paragraph';
-/**
- * A text range in a document segment. Offsets are zero-based positions in the segment data stream.
- */
-export interface IFDocTextRange {
-    /** 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;
-}
-/**
- * Resolved paragraph metadata in the current document body.
- */
-export interface IFDocResolvedParagraph {
-    /** The underlying paragraph snapshot object. */
-    paragraph: IParagraph;
-    /** The current paragraph index in the body paragraph list. */
-    paragraphIndex: number;
-    /** The inclusive start offset of the paragraph text. */
-    startOffset: number;
-    /** The exclusive end offset of the paragraph text, before the paragraph break. */
-    endOffset: number;
-}
-/**
- * A stable facade element handle that can be resolved by type and key.
- */
-export interface IFDocElementHandle {
-    /**
-     * Get the element type.
-     * @returns {FDocElementType} The element type used by the facade resolver.
-     */
-    getType(): FDocElementType;
-    /**
-     * Get the persisted key used by the facade to resolve the element.
-     * @returns {string} The facade key.
-     */
-    getKey(): string;
-}
-/**
- * A rich-text-like object, such as `RichTextValue` or `RichTextBuilder`, that can provide document body data.
- */
-export interface IFDocRichTextLike {
-    /**
-     * Get rich text data that contains document body data.
-     * @returns {{ body?: IDocumentBody }} The rich text data object.
-     */
-    getData(): {
-        body?: IDocumentBody;
-    };
-}
-interface IFDocChildInfo {
-    type: FDocElementType;
-    key: string;
-    position: number;
-    priority: number;
-}
-/**
- * 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 FDocBody {
-    private readonly _documentDataModel;
-    private readonly _commandService;
-    private readonly _segmentId;
-    constructor(_documentDataModel: DocumentDataModel, _commandService: ICommandService, _registry: DocElementRegistry, _segmentId?: string);
-    /**
-     * Get the number of top-level child elements in the body.
-     * @returns {number} The number of child elements.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * console.log(body.getNumChildren());
-     * ```
-     */
-    getNumChildren(): number;
-    /**
-     * Get a top-level child element by child index.
-     * @param {number} index The zero-based child index.
-     * @returns {FDocElement} The child element wrapper.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * const firstChild = body.getChild(0);
-     * console.log(firstChild.getType());
-     * ```
-     */
-    getChild(index: number): FDocElement;
-    /**
-     * 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 {IFDocElementHandle} element The element handle to locate.
-     * @returns {number} The current zero-based child index.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * const paragraph = body.getChild(1).asParagraph();
-     * body.insertParagraph(0, 'Intro');
-     * console.log(body.getChildIndex(paragraph));
-     * ```
-     */
-    getChildIndex(element: IFDocElementHandle): 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 doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * body.insertText(0, 'Hello ');
-     * ```
-     */
-    insertText(index: number, text: string): 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 {FDocParagraph} The inserted paragraph wrapper.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * const paragraph = body.insertParagraph(0, 'Document title');
-     * paragraph.appendText(' suffix');
-     * ```
-     */
-    insertParagraph(index: number, text?: string): FDocParagraph;
-    /**
-     * Append a plain-text paragraph at the end of the body.
-     * @param {string} text The paragraph text. Defaults to an empty paragraph.
-     * @returns {FDocParagraph} The appended paragraph wrapper.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * const paragraph = body.appendParagraph('Summary');
-     * console.log(paragraph.getText());
-     * ```
-     */
-    appendParagraph(text?: string): FDocParagraph;
-    /**
-     * Delete a range from the body.
-     * @param {IFDocTextRange} range The text range to delete.
-     * @returns {boolean} `true` if the range was deleted.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * body.deleteRange({ startOffset: 0, endOffset: 5 });
-     * ```
-     */
-    deleteRange(range: IFDocTextRange): boolean;
-    /**
-     * Replace a range with plain text or rich text body data.
-     * @param {IFDocTextRange} range The text range to replace.
-     * @param {string | IFDocRichTextLike | { body?: IDocumentBody }} value The replacement text or rich-text-like value.
-     * @returns {boolean} `true` if the replacement was applied.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * body.replaceRange({ startOffset: 0, endOffset: 5 }, 'Hello');
-     * ```
-     */
-    replaceRange(range: IFDocTextRange, value: string | IFDocRichTextLike | {
-        body?: IDocumentBody;
-    }): boolean;
-    /**
-     * Apply text style to a body range.
-     * @param {IFDocTextRange} range The range to style.
-     * @param {ITextStyle} style The Univer text style patch.
-     * @returns {boolean} `true` if the style was applied.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * body.setTextStyle({ startOffset: 0, endOffset: 5 }, { bl: 1 });
-     * ```
-     */
-    setTextStyle(range: IFDocTextRange, style: ITextStyle): boolean;
-    /**
-     * Apply paragraph style to a paragraph handle or text range.
-     * @param {FDocElement | FDocParagraph | IFDocTextRange} paragraph The paragraph handle or a range inside the paragraph.
-     * @param {IParagraphStyle} style The Univer paragraph style patch.
-     * @returns {boolean} `true` if the style was applied.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const body = doc.getBody();
-     * const paragraph = body.getChild(0).asParagraph();
-     * body.setParagraphStyle(paragraph, { horizontalAlign: 2 });
-     * ```
-     */
-    setParagraphStyle(paragraph: FDocElement | FDocParagraph | IFDocTextRange, style: IParagraphStyle): boolean;
-    /**
-     * Get the text content of a paragraph by paragraph id.
-     * @param {string} key The paragraph id.
-     * @returns {string} The paragraph text without the trailing paragraph break.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * console.log(doc.getBody().getParagraphText(paragraph.getKey()));
-     * ```
-     */
-    getParagraphText(key: string): string;
-    /**
-     * Replace the text content of a paragraph by paragraph id.
-     * @param {string} key The paragraph id.
-     * @param {string} text The replacement paragraph text.
-     * @returns {boolean} `true` if the paragraph text was replaced.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * doc.getBody().setParagraphText(paragraph.getKey(), 'Updated text');
-     * ```
-     */
-    setParagraphText(key: string, text: string): boolean;
-    /**
-     * Append text to a paragraph by paragraph id.
-     * @param {string} key The paragraph id.
-     * @param {string} text The text to append before the paragraph break.
-     * @returns {boolean} `true` if the text was appended.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * doc.getBody().appendParagraphText(paragraph.getKey(), ' suffix');
-     * ```
-     */
-    appendParagraphText(key: string, text: string): boolean;
-    /**
-     * Remove a paragraph by paragraph id.
-     * @param {string} key The paragraph id.
-     * @returns {boolean} `true` if the paragraph was removed.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * doc.getBody().removeParagraph(paragraph.getKey());
-     * ```
-     */
-    removeParagraph(key: string): boolean;
-    /**
-     * Get a paragraph text range by paragraph id.
-     * @param {string} key The paragraph id.
-     * @returns {IFDocTextRange} The paragraph range excluding the trailing paragraph break.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * const range = doc.getBody().getParagraphRange(paragraph.getKey());
-     * console.log(range.startOffset, range.endOffset);
-     * ```
-     */
-    getParagraphRange(key: string): IFDocTextRange;
-    /**
-     * Check whether a paragraph has list metadata.
-     * @param {string} key The paragraph id.
-     * @returns {boolean} `true` if the paragraph is a list item.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * console.log(doc.getBody().isListParagraph(paragraph.getKey()));
-     * ```
-     */
-    isListParagraph(key: string): boolean;
-    /**
-     * Check whether a paragraph is a task/checklist item.
-     * @param {string} key The paragraph id.
-     * @returns {boolean} `true` if the paragraph is an unchecked or checked task item.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * console.log(doc.getBody().isTaskParagraph(paragraph.getKey()));
-     * ```
-     */
-    isTaskParagraph(key: string): boolean;
-    /**
-     * Set the checked state of a task/checklist paragraph.
-     * @param {string} key The paragraph id.
-     * @param {boolean} checked Whether the task should be checked.
-     * @returns {boolean} `true` if the task state was updated, or `false` if the paragraph is not a task item.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * doc.getBody().setTaskChecked(paragraph.getKey(), true);
-     * ```
-     */
-    setTaskChecked(key: string, checked: boolean): boolean;
-    /**
-     * Resolve a paragraph id to its current paragraph metadata.
-     * @param {string} key The paragraph id.
-     * @returns {IFDocResolvedParagraph} The current paragraph metadata.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const paragraph = doc.getBody().getChild(0).asParagraph();
-     * const resolved = doc.getBody().resolveParagraph(paragraph.getKey());
-     * console.log(resolved.paragraphIndex);
-     * ```
-     */
-    resolveParagraph(key: string): IFDocResolvedParagraph;
-    /**
-     * Resolve an element key to its current child metadata.
-     * @param {FDocElementType} type The element type.
-     * @param {string} key The persisted element key.
-     * @returns {object} The current child metadata used by the facade.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const element = doc.getBody().getChild(0);
-     * const resolved = doc.getBody().resolveElement(element.getType(), element.getKey());
-     * console.log(resolved.position);
-     * ```
-     */
-    resolveElement(type: FDocElementType, key: string): IFDocChildInfo;
-    /**
-     * Get a callout, quote, or code block range by block id.
-     * @param {string} key The persisted block range id.
-     * @returns {IDocumentBlockRange} The matching block range snapshot.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const block = doc.getBody().getChild(0).asBlockRange();
-     * console.log(doc.getBody().getBlockRange(block.getKey()).blockType);
-     * ```
-     */
-    getBlockRange(key: string): IDocumentBlockRange;
-    /**
-     * Get the text inside a callout, quote, or code block range.
-     * @param {string} key The persisted block range id.
-     * @returns {string} The block range text.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const block = doc.getBody().getChild(0).asBlockRange();
-     * console.log(doc.getBody().getBlockRangeText(block.getKey()));
-     * ```
-     */
-    getBlockRangeText(key: string): string;
-    /**
-     * Replace the text inside a callout, quote, or code block range.
-     * @param {string} key The persisted block range id.
-     * @param {string} text The replacement text.
-     * @returns {boolean} `true` if the text was replaced.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const block = doc.getBody().getChild(0).asBlockRange();
-     * doc.getBody().setBlockRangeText(block.getKey(), 'Updated block');
-     * ```
-     */
-    setBlockRangeText(key: string, text: string): boolean;
-    /**
-     * Remove a callout, quote, or code block range and its content.
-     * @param {string} key The persisted block range id.
-     * @returns {boolean} `true` if the block range content was removed.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const block = doc.getBody().getChild(0).asBlockRange();
-     * doc.getBody().removeBlockRange(block.getKey());
-     * ```
-     */
-    removeBlockRange(key: string): boolean;
-    /**
-     * Get a table marker by table id.
-     * @param {string} key The persisted table id.
-     * @returns {ICustomTable} The matching table marker.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const table = doc.getBody().getChild(0).asTable();
-     * console.log(doc.getBody().getTable(table.getTableId()));
-     * ```
-     */
-    getTable(key: string): ICustomTable;
-    /**
-     * Remove a table marker and its content range.
-     * @param {string} key The persisted table id.
-     * @returns {boolean} `true` if the table range was removed.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const table = doc.getBody().getChild(0).asTable();
-     * doc.getBody().removeTable(table.getTableId());
-     * ```
-     */
-    removeTable(key: string): boolean;
-    /**
-     * Get a custom block marker by block id.
-     * @param {string} key The persisted custom block id.
-     * @returns {ICustomBlock} The matching custom block marker.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * console.log(doc.getBody().getCustomBlock(customBlock.getBlockId()));
-     * ```
-     */
-    getCustomBlock(key: string): ICustomBlock;
-    /**
-     * Remove a custom block marker and its placeholder character.
-     * @param {string} key The persisted custom block id.
-     * @returns {boolean} `true` if the custom block placeholder was removed.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * doc.getBody().removeCustomBlock(customBlock.getBlockId());
-     * ```
-     */
-    removeCustomBlock(key: string): boolean;
-    /**
-     * Create a sibling element wrapper relative to the current element key.
-     * @param {FDocElementType} type The current element type.
-     * @param {string} key The current element key.
-     * @param {-1 | 1} direction `-1` for previous sibling, `1` for next sibling.
-     * @returns {FDocElement | null} The sibling wrapper, or `null` if none exists.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const element = doc.getBody().getChild(0);
-     * const next = doc.getBody().createSibling(element.getType(), element.getKey(), 1);
-     * console.log(next?.getType());
-     * ```
-     */
-    createSibling(type: FDocElementType, key: string, direction: -1 | 1): FDocElement | null;
-    private _getChildren;
-    private _createElement;
-    private _getBody;
-    private _getParagraphInsertOffset;
-    private _normalizeInsertedParagraphIndex;
-    private _getParagraphId;
-    private _preserveExplicitParagraphIds;
-    private _findParagraphByRange;
-    private _replaceBodyRange;
-    private _retainBodyRange;
-    private _ensureTextRuns;
-    private _executeTextX;
-}
-export {};

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

@@ -1,94 +0,0 @@
-/**
- * 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 { FDocBody } from './f-doc-body';
-/**
- * A facade wrapper for a document custom block, such as an embedded drawing or widget.
- *
- * Custom block identity is backed by the persisted `ICustomBlock.blockId`, so the
- * wrapper can be re-resolved after text is inserted before the custom block.
- *
- * @hideconstructor
- */
-export declare class FDocCustomBlock {
-    protected readonly _body: FDocBody;
-    protected readonly _key: string;
-    constructor(_body: FDocBody, _key: string);
-    /**
-     * Get the document element type.
-     * @returns {'customBlock'} The literal custom block element type.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * console.log(customBlock.getType());
-     * ```
-     */
-    getType(): 'customBlock';
-    /**
-     * Get the custom block key.
-     * @returns {string} The persisted `blockId` for this custom block.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * console.log(customBlock.getKey());
-     * ```
-     */
-    getKey(): string;
-    /**
-     * Get the parent body facade that owns this custom block.
-     * @returns {FDocBody} The document body facade.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * console.log(customBlock.getParent().getChildIndex(customBlock));
-     * ```
-     */
-    getParent(): FDocBody;
-    /**
-     * Remove this custom block from the parent body.
-     * @returns {boolean} `true` if the custom block placeholder was removed.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * customBlock.removeFromParent();
-     * ```
-     */
-    removeFromParent(): boolean;
-    /**
-     * Get the persisted custom block id.
-     * @returns {string} The `ICustomBlock.blockId` value.
-     * @example
-     * ```ts
-     * const doc = univerAPI.getActiveDocument();
-     * if (!doc) throw new Error('No active document');
-     *
-     * const customBlock = doc.getBody().getChild(0).asCustomBlock();
-     * console.log(customBlock.getBlockId());
-     * ```
-     */
-    getBlockId(): string;
-}