@univerjs/docs 0.25.0 → 1.0.0-alpha.0

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

@@ -0,0 +1,94 @@
+/**
+ * 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;
+}

package/lib/types/facade/f-doc-element.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 { FDocBody } from './f-doc-body';
+import type { FDocElementType } from './doc-element-registry';
+import { FDocBlockRange } from './f-doc-block-range';
+import { FDocCustomBlock } from './f-doc-custom-block';
+import { FDocParagraph } from './f-doc-paragraph';
+import { FDocTable } from './f-doc-table';
+/**
+ * A generic top-level document body element.
+ *
+ * Use this wrapper when you need to inspect an element type first, navigate to
+ * neighboring elements, or cast the element to a more specific facade wrapper.
+ *
+ * Paragraph keys are persisted `paragraphId` values. Tables, block ranges, and
+ * custom blocks use their persisted ids.
+ *
+ * @hideconstructor
+ */
+export declare class FDocElement {
+    protected readonly _body: FDocBody;
+    protected readonly _type: FDocElementType;
+    protected readonly _key: string;
+    constructor(_body: FDocBody, _type: FDocElementType, _key: string);
+    /**
+     * Get the document element type.
+     * @returns {FDocElementType} The element type, such as `paragraph`, `table`, `blockRange`, or `customBlock`.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const element = doc.getBody().getChild(0);
+     * console.log(element.getType());
+     * ```
+     */
+    getType(): FDocElementType;
+    /**
+     * Get the facade key used to resolve this element.
+     * @returns {string} The paragraph `paragraphId` or persisted table/block/custom block id.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const body = doc.getBody();
+     * const element = body.getChild(0);
+     * console.log(element.getKey());
+     * ```
+     */
+    getKey(): string;
+    /**
+     * Get the parent body facade that owns this element.
+     * @returns {FDocBody} The document body facade.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const element = doc.getBody().getChild(0);
+     * console.log(element.getParent().getNumChildren());
+     * ```
+     */
+    getParent(): FDocBody;
+    /**
+     * Get the next sibling element in the current body order.
+     * @returns {FDocElement | null} The next sibling wrapper, or `null` when this is the last child.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const first = doc.getBody().getChild(0);
+     * const next = first.getNextSibling();
+     * console.log(next?.getType());
+     * ```
+     */
+    getNextSibling(): FDocElement | null;
+    /**
+     * Get the previous sibling element in the current body order.
+     * @returns {FDocElement | null} The previous sibling wrapper, or `null` when this is the first child.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const second = doc.getBody().getChild(1);
+     * const previous = second.getPreviousSibling();
+     * console.log(previous?.getType());
+     * ```
+     */
+    getPreviousSibling(): FDocElement | null;
+    /**
+     * Remove this element from its parent body.
+     * @returns {boolean} `true` if the element content was removed.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const body = doc.getBody();
+     * const element = body.getChild(0);
+     * element.removeFromParent();
+     * ```
+     */
+    removeFromParent(): boolean;
+    /**
+     * Cast this generic element to a paragraph facade.
+     * @returns {FDocParagraph} The paragraph facade wrapper.
+     * @throws {TypeError} If the element is not a paragraph.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const paragraph = doc.getBody().getChild(0).asParagraph();
+     * console.log(paragraph.getText());
+     * ```
+     */
+    asParagraph(): FDocParagraph;
+    /**
+     * Cast this generic element to a table facade.
+     * @returns {FDocTable} The table facade wrapper.
+     * @throws {TypeError} If the element is not a table.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const table = doc.getBody().getChild(0).asTable();
+     * console.log(table.getTableId());
+     * ```
+     */
+    asTable(): FDocTable;
+    /**
+     * Cast this generic element to a callout, quote, or code block range facade.
+     * @returns {FDocBlockRange} The block range facade wrapper.
+     * @throws {TypeError} If the element is not a block range.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const blockRange = doc.getBody().getChild(0).asBlockRange();
+     * console.log(blockRange.getBlockType());
+     * ```
+     */
+    asBlockRange(): FDocBlockRange;
+    /**
+     * Cast this generic element to a custom block facade.
+     * @returns {FDocCustomBlock} The custom block facade wrapper.
+     * @throws {TypeError} If the element is not a 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.getBlockId());
+     * ```
+     */
+    asCustomBlock(): FDocCustomBlock;
+    private _assertType;
+}

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

@@ -0,0 +1,194 @@
+/**
+ * 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, IFDocTextRange } from './f-doc-body';
+/**
+ * A paragraph facade wrapper.
+ *
+ * Paragraph identity is backed by the persisted `paragraphId`. The id is
+ * re-resolved before each method call, so insertions before this paragraph do
+ * not break the wrapper.
+ *
+ * @hideconstructor
+ */
+export declare class FDocParagraph {
+    protected readonly _body: FDocBody;
+    protected readonly _key: string;
+    constructor(_body: FDocBody, _key: string);
+    /**
+     * Get the document element type.
+     * @returns {'paragraph'} The literal paragraph element type.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const paragraph = doc.getBody().getChild(0).asParagraph();
+     * console.log(paragraph.getType());
+     * ```
+     */
+    getType(): 'paragraph';
+    /**
+     * Get the persisted paragraph id.
+     * @returns {string} The paragraph id.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const paragraph = doc.getBody().getChild(0).asParagraph();
+     * console.log(paragraph.getKey());
+     * ```
+     */
+    getKey(): string;
+    /**
+     * Get the persisted paragraph id.
+     * @returns {string} The paragraph id.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const paragraph = doc.getBody().getChild(0).asParagraph();
+     * console.log(paragraph.getId());
+     * ```
+     */
+    getId(): string;
+    /**
+     * Get the parent body facade that owns this paragraph.
+     * @returns {FDocBody} The document body facade.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const paragraph = doc.getBody().getChild(0).asParagraph();
+     * console.log(paragraph.getParent().getChildIndex(paragraph));
+     * ```
+     */
+    getParent(): FDocBody;
+    /**
+     * Remove this paragraph from its parent body.
+     * @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();
+     * paragraph.removeFromParent();
+     * ```
+     */
+    removeFromParent(): boolean;
+    /**
+     * Get this paragraph's plain text.
+     * @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(paragraph.getText());
+     * ```
+     */
+    getText(): string;
+    /**
+     * Replace this paragraph's plain text.
+     * @param {string} text The replacement text. Do not include the paragraph break.
+     * @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();
+     * paragraph.setText('Updated title');
+     * ```
+     */
+    setText(text: string): boolean;
+    /**
+     * Append plain text before this paragraph's trailing paragraph break.
+     * @param {string} text The plain text to append.
+     * @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();
+     * paragraph.appendText(' suffix');
+     * ```
+     */
+    appendText(text: string): boolean;
+    /**
+     * Get the current text range occupied by this paragraph.
+     * @returns {IFDocTextRange} The paragraph text 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 = paragraph.getRange();
+     * doc.getBody().setTextStyle(range, { bl: 1 });
+     * ```
+     */
+    getRange(): IFDocTextRange;
+    /**
+     * Check whether this paragraph is a bullet, ordered, or checklist item.
+     * @returns {boolean} `true` if the paragraph has list metadata.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const paragraph = doc.getBody().getChild(0).asParagraph();
+     * console.log(paragraph.isListItem());
+     * ```
+     */
+    isListItem(): boolean;
+    /**
+     * Check whether this paragraph is a task/checklist item.
+     * @returns {boolean} `true` if this 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();
+     * if (paragraph.isTask()) {
+     *     paragraph.setTaskChecked(true);
+     * }
+     * ```
+     */
+    isTask(): boolean;
+    /**
+     * Set the checked state of this task/checklist paragraph.
+     * @param {boolean} checked Whether the task item should be checked.
+     * @returns {boolean} `true` if the task state was updated, or `false` if this 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();
+     * if (paragraph.isTask()) {
+     *     paragraph.setTaskChecked(false);
+     * }
+     * ```
+     */
+    setTaskChecked(checked: boolean): boolean;
+}

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

@@ -0,0 +1,94 @@
+/**
+ * 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 table marker.
+ *
+ * Table identity is backed by the persisted `ICustomTable.tableId`, so the
+ * wrapper can be re-resolved after text is inserted before the table.
+ *
+ * @hideconstructor
+ */
+export declare class FDocTable {
+    protected readonly _body: FDocBody;
+    protected readonly _key: string;
+    constructor(_body: FDocBody, _key: string);
+    /**
+     * Get the document element type.
+     * @returns {'table'} The literal table element type.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const table = doc.getBody().getChild(0).asTable();
+     * console.log(table.getType());
+     * ```
+     */
+    getType(): 'table';
+    /**
+     * Get the table key.
+     * @returns {string} The persisted `tableId` for this table.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const table = doc.getBody().getChild(0).asTable();
+     * console.log(table.getKey());
+     * ```
+     */
+    getKey(): string;
+    /**
+     * Get the parent body facade that owns this table.
+     * @returns {FDocBody} The document body facade.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const table = doc.getBody().getChild(0).asTable();
+     * console.log(table.getParent().getChildIndex(table));
+     * ```
+     */
+    getParent(): FDocBody;
+    /**
+     * Remove this table from the parent body.
+     * @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();
+     * table.removeFromParent();
+     * ```
+     */
+    removeFromParent(): boolean;
+    /**
+     * Get the persisted table id.
+     * @returns {string} The `ICustomTable.tableId` value.
+     * @example
+     * ```ts
+     * const doc = univerAPI.getActiveDocument();
+     * if (!doc) throw new Error('No active document');
+     *
+     * const table = doc.getBody().getChild(0).asTable();
+     * console.log(table.getTableId());
+     * ```
+     */
+    getTableId(): string;
+}