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

package/lib/types/commands/commands/create-header-footer.command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { BooleanNumber, ICommand, IDocumentBody, JSONXActions } from '@univerjs/core';
+export declare enum HeaderFooterType {
+    FIRST_PAGE_HEADER = 0,
+    FIRST_PAGE_FOOTER = 1,
+    DEFAULT_HEADER = 2,
+    DEFAULT_FOOTER = 3,
+    EVEN_PAGE_HEADER = 4,
+    EVEN_PAGE_FOOTER = 5
+}
+export interface IHeaderFooterProps {
+    /** Distance from the page edge to the header, in points (pt). */
+    marginHeader?: number;
+    /** Distance from the page edge to the footer, in points (pt). */
+    marginFooter?: number;
+    useFirstPageHeaderFooter?: BooleanNumber;
+    evenAndOddHeaders?: BooleanNumber;
+}
+export type HeaderFooterCreateMode = 'single' | 'pair';
+export interface ICreateHeaderFooterCommandParams {
+    unitId: string;
+    createType?: HeaderFooterType;
+    segmentId?: string;
+    headerFooterProps?: IHeaderFooterProps;
+    createMode?: HeaderFooterCreateMode;
+    /** Optional stable section id. Omit to configure the document-level default. */
+    sectionId?: string;
+}
+export declare function getEmptyHeaderFooterBody(): IDocumentBody;
+export declare function createHeaderFooterAction(segmentId: string | undefined, createType: HeaderFooterType, headerFooterConfig: IHeaderFooterProps, actions: JSONXActions, createMode?: HeaderFooterCreateMode, configPath?: Array<string | number>): JSONXActions;
+export declare const CreateHeaderFooterCommand: ICommand<ICreateHeaderFooterCommandParams>;

package/lib/types/commands/commands/set-document-default-paragraph-style.command.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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, IDocumentDefaultParagraphStyle, Nullable } from '@univerjs/core';
+export type IDocumentDefaultParagraphStylePatch = {
+    [K in keyof IDocumentDefaultParagraphStyle]?: Nullable<IDocumentDefaultParagraphStyle[K]>;
+};
+export interface ISetDocumentDefaultParagraphStyleCommandParams {
+    unitId: string;
+    defaultParagraphStyle: Nullable<IDocumentDefaultParagraphStylePatch>;
+}
+export declare const SetDocumentDefaultParagraphStyleCommand: ICommand<ISetDocumentDefaultParagraphStyleCommandParams>;

package/lib/types/commands/commands/set-section-header-footer-link.command.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 type { ICommand, SectionHeaderFooterKind, SectionHeaderFooterVariant } from '@univerjs/core';
+export interface ISetSectionHeaderFooterLinkCommandParams {
+    unitId: string;
+    sectionId: string;
+    kind: SectionHeaderFooterKind;
+    variant: SectionHeaderFooterVariant;
+    linkedToPrevious: boolean;
+    /** Stable id to use when unlinking. Generated automatically when omitted. */
+    segmentId?: string;
+}
+export declare const SetSectionHeaderFooterLinkCommand: ICommand<ISetSectionHeaderFooterLinkCommandParams>;

package/lib/types/commands/commands/update-document-section.command.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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, ISectionBreak } from '@univerjs/core';
+export type IDocumentSectionConfig = Omit<ISectionBreak, 'sectionId' | 'startIndex'>;
+export interface IDocumentSectionUpdate {
+    sectionId: string;
+    config: Partial<IDocumentSectionConfig>;
+}
+export interface IUpdateDocumentSectionCommandParams {
+    unitId: string;
+    updates: IDocumentSectionUpdate[];
+}
+export interface IInsertDocumentSectionBreakCommandParams {
+    unitId: string;
+    offset: number;
+    sectionId: string;
+    config?: Partial<IDocumentSectionConfig>;
+}
+export interface IDeleteDocumentSectionBreakCommandParams {
+    unitId: string;
+    sectionId: string;
+}
+export declare const UpdateDocumentSectionCommand: ICommand<IUpdateDocumentSectionCommandParams>;
+export declare const InsertDocumentSectionBreakCommand: ICommand<IInsertDocumentSectionBreakCommandParams>;
+export declare const DeleteDocumentSectionBreakCommand: ICommand<IDeleteDocumentSectionBreakCommandParams>;

package/lib/types/embed-host-anchor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { IDocDrawingBase, IMutationInfo, JSONXActions } from '@univerjs/core';
+import type { IRichTextEditingMutationParams } from './commands/mutations/core-editing.mutation';
+import { UniverInstanceType } from '@univerjs/core';
+export interface IDocsCustomBlockMutationParams {
+    unitId: string;
+    blockId: string;
+    startIndex: number;
+    segmentId?: string;
+    drawingOrderIndex?: number;
+    embedId?: string;
+    childUnitId?: string;
+    childType?: UniverInstanceType;
+    componentKey?: string;
+    interactionMode?: EmbedDocsCustomBlockInteractionMode;
+}
+export declare const EMBED_DOCS_CUSTOM_BLOCK_DEFAULT_COMPONENT_KEY = "UniverEmbedDocsCustomBlock";
+export type EmbedDocsCustomBlockInteractionMode = 'block' | 'inline';
+export interface IEmbedDocsCustomBlockData {
+    version: 1;
+    embedId: string;
+    hostUnitId?: string;
+    hostAnchorId: string;
+    childUnitId?: string;
+    childType?: UniverInstanceType;
+    interactionMode?: EmbedDocsCustomBlockInteractionMode;
+}
+export declare function createDocsCustomBlockInsertMutation(params: IDocsCustomBlockMutationParams): IMutationInfo<IRichTextEditingMutationParams>;
+export declare function createDocsCustomBlockRemoveMutation(params: IDocsCustomBlockMutationParams): IMutationInfo<IRichTextEditingMutationParams>;
+export declare function createInsertCustomBlockActions(params: IDocsCustomBlockMutationParams): JSONXActions;
+export declare function createRemoveCustomBlockActions(params: IDocsCustomBlockMutationParams): JSONXActions;
+export declare function createDocsCustomBlockDrawing(params: IDocsCustomBlockMutationParams): IDocDrawingBase;
+export declare function resolveDocsCustomBlockSize(childType?: UniverInstanceType): {
+    width: number;
+    height: number;
+};
+export declare function isSheetLikeDocsCustomBlockChildType(childType?: UniverInstanceType): boolean;
+export declare function createEmbedDocsCustomBlockData(params: {
+    blockId: string;
+    embedId?: string;
+    unitId?: string;
+    childUnitId?: string;
+    childType?: UniverInstanceType;
+    interactionMode?: EmbedDocsCustomBlockInteractionMode;
+}): IEmbedDocsCustomBlockData;
+export declare function isEmbedDocsCustomBlockData(data: unknown): data is IEmbedDocsCustomBlockData;
+export declare function shouldUseInlineTextSelectionForDocsCustomBlockDrawing(drawing: unknown): boolean;

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

@@ -14,16 +14,13 @@
  * limitations under the License.
  */
 import type { Injector, IParagraph, IParagraphStyle } from '@univerjs/core';
-import type { FDocumentBody, IFDocumentBodyEdit, IFDocumentTextRange } from './f-document-body';
-import type { IFDocumentElementInfo } from './f-document-element';
-import { FDocumentElement } from './f-document-element';
-interface IFDocumentParagraphMixin {
-    asParagraph(): FDocumentParagraph;
-}
+import type { FDocument } from './f-document';
+import type { IFDocumentTextRange } from './utils';
+import { FDocumentTextRange } from './f-document-text-range';
 /**
  * Resolved paragraph metadata in the the document body.
  */
-export interface IFDocumentResolvedParagraph {
+export interface IFDocumentParagraphInfo {
     /** The underlying paragraph snapshot object. */
     paragraph: IParagraph;
     /** The current paragraph index in the body paragraph list. */
@@ -42,74 +39,78 @@ export interface IFDocumentResolvedParagraph {
  *
  * @hideconstructor
  */
-export declare class FDocumentParagraph 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);
+export declare class FDocumentParagraph {
+    private readonly _document;
+    private readonly _paragraphId;
+    private readonly _segmentId;
+    private readonly _injector;
+    constructor(_document: FDocument, _paragraphId: string, _segmentId: string | undefined, _injector: Injector);
     /**
      * Get the persisted paragraph id.
      * @returns {string} The paragraph id.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   console.log(paragraph.getParagraphId());
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.getId());
      * ```
      */
-    getParagraphId(): string;
+    getId(): string;
     /**
-     * Get the resolved paragraph info for this wrapper.
-     * @returns {IFDocumentResolvedParagraph} The resolved paragraph info, including the paragraph object, its index, and its text range.
+     * Get the segment id of this paragraph.
+     * The main body paragraphs have an empty string segment id.
+     * The header and footer paragraphs have a non-empty string segment id.
+     * @returns {string} The segment id.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   console.log(paragraph.getResolvedParagraphInfo());
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.getSegmentId());
+     * ```
+     */
+    getSegmentId(): string;
+    /**
+     * Get this paragraph's metadata.
+     * @returns {IFDocumentParagraphInfo} The paragraph info.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.getInfo());
      * ```
      */
-    getResolvedParagraphInfo(): IFDocumentResolvedParagraph;
+    getInfo(): IFDocumentParagraphInfo;
     /**
      * Get the current text range occupied by this paragraph.
      * @returns {IFDocumentTextRange} The paragraph text range, excluding the trailing paragraph break.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   const range = paragraph.getRange();
-     *   fDocumentBody.setTextStyle(range, { bl: 1 });
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.getRange());
      * ```
      */
     getRange(): IFDocumentTextRange;
+    /**
+     * Returns an agent-friendly facade for reading and styling this paragraph's text.
+     * @returns {FDocumentTextRange} The paragraph text range, excluding the trailing paragraph break.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const paragraph = fDocument?.findParagraphByText('Launch');
+     * const range = paragraph?.getTextRange();
+     * console.log(range?.describe());
+     * ```
+     */
+    getTextRange(): FDocumentTextRange;
     /**
      * Get this paragraph's plain text.
      * @returns {string} The paragraph text without the trailing paragraph break.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   console.log(paragraph.getText());
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.getText());
      * ```
      */
     getText(): string;
@@ -120,14 +121,9 @@ export declare class FDocumentParagraph extends FDocumentElement {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   const success = paragraph.setText('Updated title');
-     *   console.log(success ? 'Text updated' : 'Failed to update text');
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * paragraph?.setText('New text');
+     * console.log(paragraph?.getText());
      * ```
      */
     setText(text: string): boolean;
@@ -138,31 +134,32 @@ export declare class FDocumentParagraph extends FDocumentElement {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   const success = paragraph.appendText(' Appended text');
-     *   console.log(success ? 'Text appended' : 'Failed to append text');
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * paragraph?.appendText(' Appended text');
+     * console.log(paragraph?.getText());
      * ```
      */
     appendText(text: string): boolean;
     /**
      * Apply paragraph style to a paragraph handle or text range.
+     * `style.textStyle.fs` is a font size in points (pt), not CSS pixels.
      * @param {IParagraphStyle} style The Univer paragraph style patch.
      * @returns {boolean} `true` if the style was applied.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   paragraph.setStyle({ horizontalAlign: 2 });
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * paragraph?.setText('Styled text');
+     * paragraph?.setStyle({
+     *   textStyle: {
+     *     cl: {
+     *       rgb: '#FF0000',
+     *     },
+     *     fs: 14,
+     *   },
+     *   horizontalAlign: 2,
+     * });
+     * console.log(paragraph?.getInfo().paragraph.paragraphStyle);
      * ```
      */
     setStyle(style: IParagraphStyle): boolean;
@@ -172,13 +169,8 @@ export declare class FDocumentParagraph extends FDocumentElement {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   console.log(paragraph.isListItem() ? 'This is a list item' : 'This is not a list item');
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.isListItem());
      * ```
      */
     isListItem(): boolean;
@@ -188,13 +180,8 @@ export declare class FDocumentParagraph extends FDocumentElement {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
-     *   console.log(paragraph.isTask() ? 'This is a task item' : 'This is not a task item');
-     * }
+     * const paragraph = fDocument.getParagraphs()[0];
+     * console.log(paragraph?.isTask());
      * ```
      */
     isTask(): boolean;
@@ -205,27 +192,27 @@ export declare class FDocumentParagraph extends FDocumentElement {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * const fDocumentBody = fDocument.getBody();
-     * const element = fDocumentBody.getElement(0);
-     *
-     * if (element?.isParagraph()) {
-     *   const paragraph = element.asParagraph();
+     * const paragraph = fDocument.getParagraphs()[0];
      *
-     *   if (paragraph.isTask()) {
-     *     const success = paragraph.setTaskChecked(true);
-     *     console.log(success ? 'Task checked' : 'Failed to check task');
-     *   }
+     * if (paragraph.isTask()) {
+     *   const success = paragraph.setTaskChecked(true);
+     *   console.log(success ? 'Task checked' : 'Failed to check task');
      * }
      * ```
      */
     setTaskChecked(checked: boolean): boolean;
+    /**
+     * Remove this paragraph.
+     * @returns {boolean} `true` if the paragraph was removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const paragraph = fDocument.getParagraphs()[0];
+     * const success = paragraph?.remove();
+     * console.log(success ? 'Paragraph removed' : 'Failed to remove paragraph');
+     * ```
+     */
+    remove(): boolean;
     private _preserveExplicitParagraphIds;
 }
-export declare class FDocumentParagraphMixin extends FDocumentElement {
-    asParagraph(): FDocumentParagraph;
-}
-declare module '@univerjs/docs/facade' {
-    interface FDocumentElement extends IFDocumentParagraphMixin {
-    }
-}
-export {};
+export declare function isParagraphFacade(value: unknown): value is FDocumentParagraph;