@univerjs/core 1.0.0-alpha.2 → 1.0.0-alpha.3

package/lib/types/docs/data-model/rich-text-builder.d.ts

@@ -14,11 +14,142 @@
  * limitations under the License.
  */
 import type { Nullable } from '../../shared';
-import type { BaselineOffset, HorizontalAlign, TextDecoration, TextDirection } from '../../types/enum';
+import type { BaselineOffset, HorizontalAlign, TextDecoration, TextDirection, VerticalAlign } from '../../types/enum';
 import type { IBorderData, IColorStyle, IDocumentBody, IDocumentData, INumberUnit, IParagraphBorder, IParagraphStyle, IShading, ITabStop, ITextDecoration, ITextStyle, NamedStyleType, SpacingRule } from '../../types/interfaces';
 import { BooleanNumber } from '../../types/enum';
+import { PresetListType } from './preset-list-type';
 export declare function normalizeBody(body: IDocumentBody): IDocumentBody;
 export declare function normalizeData(data: IDocumentData): IDocumentData;
+/**
+ * Agent-friendly text style aliases accepted by `RichTextBuilder.span()`.
+ *
+ * The readable aliases can be combined in one object and apply only to the appended span. Native `ITextStyle` fields
+ * remain available for advanced document integrations.
+ *
+ * @example
+ * ```ts
+ * const text = univerAPI.newRichText()
+ *   .text('Status: ')
+ *   .span('Blocked', {
+ *     bold: true,
+ *     italic: true,
+ *     color: '#dc2626',
+ *     background: '#fee2e2',
+ *   });
+ * ```
+ */
+export interface IRichTextSpanStyle extends ITextStyle {
+    /**
+     * Agent-friendly alias for `bl`.
+     */
+    bold?: boolean;
+    /**
+     * Agent-friendly alias for `it`.
+     */
+    italic?: boolean;
+    /**
+     * Agent-friendly alias for `ff`.
+     */
+    fontFamily?: string;
+    /**
+     * Agent-friendly alias for `fs`.
+     */
+    fontSize?: number;
+    /**
+     * Agent-friendly alias for `cl`. A string is treated as an RGB color.
+     */
+    color?: string | IColorStyle | null;
+    /**
+     * Agent-friendly alias for `bg`. A string is treated as an RGB color.
+     */
+    background?: string | IColorStyle | null;
+}
+/**
+ * Agent-friendly paragraph options accepted by `RichTextBuilder.paragraph()`.
+ *
+ * Numeric lengths use document points. Pass an `INumberUnit` when another supported unit is required. `lineHeight`
+ * behaves as a multiplier with `SpacingRule.AUTO`, and as an absolute document size with `AT_LEAST` or `EXACT`.
+ *
+ * @example
+ * ```ts
+ * const text = univerAPI.newRichText()
+ *   .paragraph({
+ *     align: univerAPI.Enum.HorizontalAlign.LEFT,
+ *     lineHeight: 1.4,
+ *     lineHeightRule: univerAPI.Enum.SpacingRule.AUTO,
+ *     firstLineIndent: 12,
+ *     spaceAfter: 6,
+ *   })
+ *   .text('Agent-friendly paragraph');
+ * ```
+ */
+export interface IRichTextParagraphStyle {
+    /** Horizontal paragraph alignment. Use `univerAPI.Enum.HorizontalAlign`. */
+    align?: HorizontalAlign;
+    /** Line-height multiplier or absolute size, depending on `lineHeightRule`. */
+    lineHeight?: number;
+    /** Line-height interpretation. Defaults to `SpacingRule.AUTO`. */
+    lineHeightRule?: SpacingRule;
+    /** First-line indent. A number is interpreted as document points. */
+    firstLineIndent?: number | INumberUnit;
+    /** Hanging indent. A number is interpreted as document points. */
+    hangingIndent?: number | INumberUnit;
+    /** Leading-side indent. A number is interpreted as document points. */
+    indentStart?: number | INumberUnit;
+    /** Trailing-side indent. A number is interpreted as document points. */
+    indentEnd?: number | INumberUnit;
+    /** Space before the paragraph. A number is interpreted as document points. */
+    spaceBefore?: number | INumberUnit;
+    /** Space after the paragraph. A number is interpreted as document points. */
+    spaceAfter?: number | INumberUnit;
+    /** Text direction. Use `univerAPI.Enum.TextDirection`. */
+    direction?: TextDirection;
+    /** Whether lines may wrap at character boundaries. */
+    wordWrap?: boolean;
+    /** Keeps all paragraph lines together when pagination applies. */
+    keepLines?: boolean;
+    /** Keeps this paragraph with the following paragraph when pagination applies. */
+    keepNext?: boolean;
+}
+/**
+ * Portable text-container alignment accepted by `RichTextBuilder.align()`.
+ *
+ * Unlike `paragraph({ align })`, which styles one paragraph, this alignment is a document-level presentation hint that
+ * can be consumed consistently by shapes, table cells, and other rich-text hosts.
+ */
+export interface IRichTextAlignment {
+    /** Horizontal alignment for the rich-text block. */
+    horizontal?: HorizontalAlign;
+    /** Vertical alignment inside the host text container. */
+    vertical?: VerticalAlign;
+}
+/**
+ * Agent-friendly options for one paragraph list item.
+ *
+ * @example
+ * ```ts
+ * const text = univerAPI.newRichText()
+ *   .listItem('Plan', {
+ *     type: univerAPI.Enum.PresetListType.ORDER_LIST,
+ *     listId: 'agent.release-steps',
+ *   })
+ *   .listItem('Build', {
+ *     type: univerAPI.Enum.PresetListType.ORDER_LIST,
+ *     listId: 'agent.release-steps',
+ *     level: 1,
+ *   });
+ * ```
+ */
+export interface IRichTextListItemOptions {
+    /** Preset ordered, unordered, or checklist style. Defaults to `PresetListType.BULLET_LIST`. */
+    type?: PresetListType;
+    /** Stable list identity. Consecutive compatible items reuse the previous id when omitted. */
+    listId?: string;
+    /** Zero-based nesting level. Defaults to `0`. */
+    level?: number;
+    /** Optional paragraph layout for this item. */
+    paragraphStyle?: ParagraphStyleBuilder | IRichTextParagraphStyle;
+}
 /**
  * Represents a read-only font style value object.
  * This class provides access to font style properties without modification capabilities.
@@ -1230,6 +1361,143 @@ export declare class RichTextBuilder extends RichTextValue {
     static create(data?: IDocumentData): RichTextBuilder;
     private _doc;
     constructor(data: IDocumentData);
+    /**
+     * Appends plain text to the rich text.
+     *
+     * This is an agent-friendly alias of `insertText(text)`. Use it when building rich text from left to right for
+     * shapes, comments, table cells, and document fragments.
+     *
+     * @param text Text to append.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText()
+     *   .text('Priority: ')
+     *   .bold('High')
+     *   .text(' ')
+     *   .code('P0');
+     * ```
+     */
+    text(text: string): RichTextBuilder;
+    /**
+     * Aligns the rich-text block inside its host container.
+     *
+     * This is the preferred facade-friendly API for alignment shared by shapes and table cells. It keeps callers away
+     * from `IDocumentData.documentStyle.renderConfig`. Use `paragraph({ align })` when individual paragraphs need
+     * different horizontal alignment.
+     *
+     * @param alignment Horizontal and/or vertical container alignment.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const text = univerAPI.newRichText()
+     *   .align({
+     *     horizontal: univerAPI.Enum.HorizontalAlign.CENTER,
+     *     vertical: univerAPI.Enum.VerticalAlign.MIDDLE,
+     *   })
+     *   .text('Centered text');
+     * ```
+     */
+    align(alignment: IRichTextAlignment): RichTextBuilder;
+    /**
+     * Appends one text span with explicit style.
+     *
+     * Prefer this method when combining multiple styles, because the style object is local to the inserted text and does
+     * not leak into following calls.
+     *
+     * @param text Text to append.
+     * @param style Text style for this span. Agent-friendly aliases such as `bold`, `italic`, `fontFamily`, `fontSize`,
+     * `color`, and `background` are supported alongside native document text style fields.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText()
+     *   .text('Status: ')
+     *   .span('Important', { bold: true, italic: true, color: '#d92d20' });
+     * ```
+     */
+    span(text: string, style: IRichTextSpanStyle): RichTextBuilder;
+    /**
+     * Appends bold text.
+     *
+     * @param text Text to append.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText().text('This is ').bold('important');
+     * ```
+     */
+    bold(text: string): RichTextBuilder;
+    /**
+     * Appends italic text.
+     *
+     * @param text Text to append.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText().text('Use ').italic('judgment');
+     * ```
+     */
+    italic(text: string): RichTextBuilder;
+    /**
+     * Appends inline code-style text.
+     *
+     * This is intentionally an inline text style, not a block range. Use `paragraph().code('...')` when the code should
+     * occupy its own line.
+     *
+     * @param text Text to append as inline code.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText()
+     *   .text('Run ')
+     *   .code('pnpm test')
+     *   .text(' before submitting.');
+     * ```
+     */
+    code(text: string): RichTextBuilder;
+    /**
+     * Appends one ordered, unordered, or checklist paragraph.
+     *
+     * Consecutive items with the same `type` automatically share a generated list id. Supply a semantic `listId` when
+     * an agent needs stable list identity across regeneration.
+     *
+     * @param text Plain item text.
+     * @param options List type, stable identity, nesting, and optional paragraph layout.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText()
+     *   .listItem('Analyze requirements', {
+     *     type: univerAPI.Enum.PresetListType.BULLET_LIST,
+     *     listId: 'agent.tasks',
+     *   })
+     *   .listItem('Implement API', {
+     *     type: univerAPI.Enum.PresetListType.BULLET_LIST,
+     *     listId: 'agent.tasks',
+     *     level: 1,
+     *   });
+     * ```
+     */
+    listItem(text: string, options?: IRichTextListItemOptions): RichTextBuilder;
+    /**
+     * Starts a new paragraph before the next appended content.
+     *
+     * Calling `paragraph()` on an empty builder is a no-op, so agents can naturally start chains with
+     * `newRichText().paragraph().text('Title')` without creating a leading blank paragraph.
+     *
+     * @param paragraphStyle Optional agent-friendly paragraph options or an advanced paragraph style builder.
+     * @returns The current builder for chaining.
+     * @example
+     * ```ts
+     * const richText = univerAPI.newRichText()
+     *   .paragraph({ lineHeight: 1.4, firstLineIndent: 16, spaceAfter: 8 })
+     *   .text('First paragraph')
+     *   .paragraph({ align: univerAPI.Enum.HorizontalAlign.CENTER })
+     *   .span('Second paragraph', { bold: true, italic: true });
+     * ```
+     */
+    paragraph(paragraphStyle?: ParagraphStyleBuilder | IRichTextParagraphStyle): RichTextBuilder;
     /**
      * Inserts text into the rich text builder at the specified start position
      * @param start The start position of the text to insert

package/lib/types/docs/data-model/text-x/action-types.d.ts

@@ -15,6 +15,7 @@
  */
 import type { UpdateDocsAttributeType } from '../../../shared/command-enum';
 import type { IDocumentBody } from '../../../types/interfaces/i-document-data';
+export declare const PRESERVE_INSERTED_PARAGRAPH_IDS = "__textXPreserveParagraphIds";
 export declare enum TextXActionType {
     RETAIN = "r",
     INSERT = "i",

package/lib/types/docs/data-model/text-x/apply-utils/common.d.ts

@@ -32,14 +32,17 @@ export declare function insertTextRuns(body: IDocumentBody, insertBody: IDocumen
  * @param textLength The length of the inserted content text.
  * @param currentIndex Determining the index where the content will be inserted into the current content.
  */
-export declare function insertParagraphs(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number, preserveMissingParagraphIds?: boolean): void;
+export declare function insertParagraphs(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number, preserveMissingParagraphIds?: boolean, originalDataStream?: string): void;
 export declare function normalizeInsertedParagraphIdsForDocument(paragraphs: IParagraph[] | undefined, insertParagraphs: IParagraph[] | undefined, currentIndex: number, options: {
     freshenSplitParagraph: boolean;
     preserveExplicitSplitParagraphIds?: boolean;
+    preserveExplicitParagraphIds?: boolean;
     preserveMissingParagraphIds?: boolean;
     reservedParagraphIds?: Set<string>;
+    dataStream?: string;
 }): void;
 export declare function insertSectionBreaks(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number): void;
+export declare function normalizeInsertedSectionIdsForDocument(sectionBreaks: ISectionBreak[] | undefined, insertSectionBreaks: ISectionBreak[] | undefined, reservedSectionIds?: Set<string>): void;
 export declare function insertCustomBlocks(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number): void;
 export declare function insertTables(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number): void;
 export declare function insertColumnGroups(body: IDocumentBody, insertBody: IDocumentBody, textLength: number, currentIndex: number): void;

package/lib/types/docs/data-model/text-x/build-utils/data-stream-change.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { IDocumentBody } from '../../../../types/interfaces';
+export interface IDataStreamChange {
+    start: number;
+    deleteLength: number;
+    insertLength: number;
+}
+/**
+ * Finds one contiguous dataStream change. Pure structural insertions are
+ * anchored by their new stable ids before falling back to string comparison.
+ * This prevents an adjacent identical sentinel from being mistaken for an
+ * unchanged prefix and keeps the inserted structure metadata in the TextX body.
+ */
+export declare function getSingleDataStreamChange(previousBody: IDocumentBody | undefined, nextBody: IDocumentBody | undefined): IDataStreamChange | null;

package/lib/types/docs/data-model/text-x/build-utils/index.d.ts

@@ -67,4 +67,9 @@ export declare class BuildTextUtils {
         add: (param: import("./drawings").IAddDrawingParam) => false | import("ot-json1").JSONOp;
     };
 }
+export { getSingleDataStreamChange } from './data-stream-change';
+export type { IDataStreamChange } from './data-stream-change';
+export { getParagraphContentStartOffset, getParagraphContentStartOffsets, getParagraphFollowingBlockOffset } from './paragraph';
+export { containsInteriorInsertionOffset, containsStreamIndex, getBlockRangeInterval, getColumnGroupRangeInterval, getCustomBlockInterval, getCustomRangeInterval, getExclusiveRangeInterval, getInclusiveRangeInterval, getTableCellTokenInterval, getTableRangeInterval, getTableRowTokenInterval, intersectsOperationalIntervals, shiftExclusiveRangeOnDelete, shiftExclusiveRangeOnInsert, shiftInclusiveRangeOnDelete, shiftInclusiveRangeOnInsert, } from './range-interval';
+export type { IDocOperationalInterval } from './range-interval';
 export type { IAddCustomRangeTextXParam, IDeleteCustomRangeParam, IReplaceSelectionTextXParams } from './text-x-utils';

package/lib/types/docs/data-model/text-x/build-utils/paragraph.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import type { ITextRange } from '../../../../sheets/typedef';
-import type { ICustomTable, IParagraph, IParagraphStyle, ITextStyle } from '../../../../types/interfaces';
+import type { ICustomTable, IDocumentBody, IParagraph, IParagraphStyle, ITextStyle } from '../../../../types/interfaces';
 import type { DocumentDataModel } from '../../document-data-model';
 import { TextX } from '../text-x';
 export interface ISwitchParagraphBulletParams {
@@ -45,6 +45,9 @@ export interface IChangeParagraphBulletNestLevelParams {
     type: 1 | -1;
 }
 export declare function hasParagraphInTable(paragraph: IParagraph, tables: ICustomTable[]): boolean;
+export declare function getParagraphContentStartOffset(body: Pick<IDocumentBody, 'dataStream' | 'paragraphs'>, paragraph: Pick<IParagraph, 'startIndex'>): number;
+export declare function getParagraphContentStartOffsets(body: Pick<IDocumentBody, 'dataStream' | 'paragraphs'>): Map<number, number>;
+export declare function getParagraphFollowingBlockOffset(body: Pick<IDocumentBody, 'blockRanges'>, paragraph: Pick<IParagraph, 'startIndex'>): number;
 export declare const changeParagraphBulletNestLevel: (params: IChangeParagraphBulletNestLevelParams) => TextX;
 export interface ISetParagraphStyleParams {
     textRanges: readonly ITextRange[];

package/lib/types/docs/data-model/text-x/build-utils/range-interval.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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, ICustomColumnGroup, ICustomRange, ICustomTable, IDocumentBlockRange } from '../../../../types/interfaces/i-document-data';
+/**
+ * A canonical half-open interval used by document editing algorithms.
+ * `startOffset` is included and `endOffset` is excluded.
+ */
+export interface IDocOperationalInterval {
+    startOffset: number;
+    endOffset: number;
+}
+type IInclusiveDocumentRange = Pick<IDocumentBlockRange, 'startIndex' | 'endIndex'>;
+type IExclusiveDocumentRange = Pick<ICustomTable, 'startIndex' | 'endIndex'>;
+/** Converts persisted inclusive indexes `[startIndex, endIndex]` to `[startOffset, endOffset)`. */
+export declare function getInclusiveRangeInterval(range: IInclusiveDocumentRange): IDocOperationalInterval;
+/** Converts persisted half-open indexes `[startIndex, endIndex)` to the operational representation. */
+export declare function getExclusiveRangeInterval(range: IExclusiveDocumentRange): IDocOperationalInterval;
+/** A table stores an exclusive end immediately after `TABLE_END`. */
+export declare function getTableRangeInterval(table: Pick<ICustomTable, 'startIndex' | 'endIndex'>): IDocOperationalInterval;
+/** A document block stores an inclusive end that points at `BLOCK_END`. */
+export declare function getBlockRangeInterval(blockRange: Pick<IDocumentBlockRange, 'startIndex' | 'endIndex'>): IDocOperationalInterval;
+/** A column group stores an inclusive end that points at `COLUMN_GROUP_END`. */
+export declare function getColumnGroupRangeInterval(columnGroup: Pick<ICustomColumnGroup, 'startIndex' | 'endIndex'>): IDocOperationalInterval;
+/** A custom range stores inclusive character indexes. */
+export declare function getCustomRangeInterval(customRange: Pick<ICustomRange, 'startIndex' | 'endIndex'>): IDocOperationalInterval;
+/** A custom block occupies exactly one `CUSTOM_BLOCK` sentinel. */
+export declare function getCustomBlockInterval(customBlock: Pick<ICustomBlock, 'startIndex'>): IDocOperationalInterval;
+/** Returns the half-open token interval for a row that starts at `startOffset`. */
+export declare function getTableRowTokenInterval(dataStream: string, startOffset: number): IDocOperationalInterval | null;
+/** Returns the half-open token interval for a cell that starts at `startOffset`. */
+export declare function getTableCellTokenInterval(dataStream: string, startOffset: number): IDocOperationalInterval | null;
+/** Tests whether a stream index belongs to a half-open operational interval. */
+export declare function containsStreamIndex(interval: IDocOperationalInterval, index: number): boolean;
+/**
+ * Tests whether an insertion point is strictly inside a container.
+ * Boundary insertion affinity must be decided by the caller.
+ */
+export declare function containsInteriorInsertionOffset(interval: IDocOperationalInterval, offset: number): boolean;
+/** Tests whether two half-open operational intervals overlap. */
+export declare function intersectsOperationalIntervals(left: IDocOperationalInterval, right: IDocOperationalInterval): boolean;
+/** Shifts or expands an inclusive persisted range for an insertion at `offset`. */
+export declare function shiftInclusiveRangeOnInsert<T extends {
+    startIndex: number;
+    endIndex: number;
+}>(range: T, offset: number, length: number): T;
+/** Shifts or expands a half-open persisted range for an insertion at `offset`. */
+export declare function shiftExclusiveRangeOnInsert<T extends {
+    startIndex: number;
+    endIndex: number;
+}>(range: T, offset: number, length: number): T;
+/** Transforms an inclusive persisted range after deleting `[offset, offset + length)`. */
+export declare function shiftInclusiveRangeOnDelete<T extends {
+    startIndex: number;
+    endIndex: number;
+}>(range: T, offset: number, length: number): T | null;
+/** Transforms a half-open persisted range after deleting `[offset, offset + length)`. */
+export declare function shiftExclusiveRangeOnDelete<T extends {
+    startIndex: number;
+    endIndex: number;
+}>(range: T, offset: number, length: number): T | null;
+export {};

package/lib/types/docs/data-model/text-x/structure-validator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { IDocumentBody, IDocumentData } from '../../../types/interfaces/i-document-data';
+export type DocStructureIssueCode = 'missing-root-paragraph' | 'missing-root-section-break' | 'paragraph-token-mismatch' | 'duplicate-paragraph-metadata' | 'section-break-token-mismatch' | 'duplicate-section-break-metadata' | 'missing-section-id' | 'duplicate-section-id' | 'table-start-token-mismatch' | 'table-end-token-mismatch' | 'missing-table-metadata' | 'overlapping-table' | 'block-range-token-mismatch' | 'missing-block-range-metadata' | 'overlapping-block-range' | 'unbalanced-block' | 'column-group-range-token-mismatch' | 'missing-column-group-metadata' | 'overlapping-column-group' | 'column-group-column-count-mismatch' | 'custom-block-token-mismatch' | 'missing-custom-block-metadata' | 'duplicate-custom-block-metadata' | 'empty-column' | 'empty-table-cell' | 'unbalanced-column-group' | 'unbalanced-table';
+export interface IDocStructureIssue {
+    code: DocStructureIssueCode;
+    segmentType: 'body' | 'header' | 'footer';
+    segmentId?: string;
+    index?: number;
+    message: string;
+}
+interface IValidationContext {
+    segmentType: IDocStructureIssue['segmentType'];
+    segmentId?: string;
+}
+export declare function validateDocBodyStructure(body: IDocumentBody, context?: IValidationContext): IDocStructureIssue[];
+export declare function validateDocumentStructure(snapshot: Pick<IDocumentData, 'body' | 'headers' | 'footers'>): IDocStructureIssue[];
+export {};

package/lib/types/docs/data-model/text-x/utils.d.ts

@@ -21,14 +21,19 @@ export declare enum SliceBodyType {
     copy = 0,
     cut = 1
 }
+export declare enum SliceStructuralRangeMode {
+    intersect = 0,
+    contained = 1,
+    ending = 2
+}
 export declare function getTextRunSlice(body: IDocumentBody, startOffset: number, endOffset: number, returnEmptyTextRuns?: boolean): ITextRun[] | undefined;
-export declare function getTableSlice(body: IDocumentBody, startOffset: number, endOffset: number): {
+export declare function getTableSlice(body: IDocumentBody, startOffset: number, endOffset: number, mode?: SliceStructuralRangeMode): {
     startIndex: number;
     endIndex: number;
     tableId: string;
 }[];
-export declare function getBlockRangeSlice(body: IDocumentBody, startOffset: number, endOffset: number): IDocumentBlockRange[];
-export declare function getColumnGroupSlice(body: IDocumentBody, startOffset: number, endOffset: number): ICustomColumnGroup[];
+export declare function getBlockRangeSlice(body: IDocumentBody, startOffset: number, endOffset: number, mode?: SliceStructuralRangeMode): IDocumentBlockRange[];
+export declare function getColumnGroupSlice(body: IDocumentBody, startOffset: number, endOffset: number, mode?: SliceStructuralRangeMode): ICustomColumnGroup[];
 export declare function getParagraphsSlice(body: IDocumentBody, startOffset: number, endOffset: number, type?: SliceBodyType): {
     startIndex: number;
     paragraphId: string;
@@ -37,6 +42,7 @@ export declare function getParagraphsSlice(body: IDocumentBody, startOffset: num
 }[] | undefined;
 export declare function getSectionBreakSlice(body: IDocumentBody, startOffset: number, endOffset: number): {
     startIndex: number;
+    sectionId: string;
     pageNumberStart?: number;
     pageSize?: import("../../..").ISize;
     pageOrient?: import("../../..").PageOrientType;
@@ -71,7 +77,9 @@ export declare function getCustomBlockSlice(body: IDocumentBody, startOffset: nu
     blockType?: import("../../..").BlockType;
     blockId: string;
 }[] | undefined;
-export declare function getBodySlice(body: IDocumentBody, startOffset: number, endOffset: number, returnEmptyArray?: boolean, type?: SliceBodyType): IDocumentBody;
+export declare function getBodySlice(body: IDocumentBody, startOffset: number, endOffset: number, returnEmptyArray?: boolean, type?: SliceBodyType, structuralRangeMode?: SliceStructuralRangeMode): IDocumentBody;
+export declare function getBodySliceForTextXAction(body: IDocumentBody, startOffset: number, endOffset: number, returnEmptyArray?: boolean, type?: SliceBodyType): IDocumentBody;
+export declare function getBodySliceForSplitTextXAction(body: IDocumentBody, startOffset: number, endOffset: number, returnEmptyArray?: boolean, type?: SliceBodyType): IDocumentBody;
 export declare function normalizeBody(body: IDocumentBody): IDocumentBody;
 export declare function getCustomRangeSlice(body: IDocumentBody, startOffset: number, endOffset: number): {
     customRanges?: undefined;

package/lib/types/docs/index.d.ts

@@ -14,3 +14,8 @@
  * limitations under the License.
  */
 export * from './data-model';
+export { cloneBodyWithFreshParagraphIds, cloneParagraphWithId, createParagraphId, PARAGRAPH_ID_PREFIX, } from './paragraph-id';
+export type { IParagraphIdScope } from './paragraph-id';
+export { cloneSectionBreakWithId, createSectionId, SECTION_ID_PREFIX, } from './section-break-id';
+export { getSectionHeaderFooterReferenceKey, resolveSectionHeaderFooterReference, resolveSectionHeaderFooterReferences, } from './section-header-footer';
+export type { IResolvedSectionHeaderFooterReference, SectionHeaderFooterKind, SectionHeaderFooterReferenceKey, SectionHeaderFooterVariant, } from './section-header-footer';

package/lib/types/docs/section-break-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { ISectionBreak } from '../types/interfaces/i-document-data';
+export declare const SECTION_ID_PREFIX = "section_";
+export declare function createSectionId(existingIds: Set<string>): string;
+export declare function cloneSectionBreakWithId(sectionBreak: ISectionBreak, existingIds: Set<string>, preserveId?: boolean): ISectionBreak;

package/lib/types/docs/section-header-footer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { IDocumentStyle, ISectionBreak } from '../types/interfaces/i-document-data';
+export type SectionHeaderFooterKind = 'header' | 'footer';
+export type SectionHeaderFooterVariant = 'default' | 'first' | 'even';
+export type SectionHeaderFooterReferenceKey = 'defaultHeaderId' | 'defaultFooterId' | 'firstPageHeaderId' | 'firstPageFooterId' | 'evenPageHeaderId' | 'evenPageFooterId';
+export interface IResolvedSectionHeaderFooterReference {
+    segmentId?: string;
+    linkedToPrevious: boolean;
+    sourceSectionId?: string;
+}
+export declare function getSectionHeaderFooterReferenceKey(kind: SectionHeaderFooterKind, variant: SectionHeaderFooterVariant): SectionHeaderFooterReferenceKey;
+/**
+ * Resolves one OOXML header/footer reference for a document section.
+ * A missing reference after the first section inherits the previous section.
+ * Document-level references are defaults for the first section only.
+ */
+export declare function resolveSectionHeaderFooterReference(documentStyle: IDocumentStyle, sections: Readonly<ISectionBreak[]>, sectionIndex: number, key: SectionHeaderFooterReferenceKey): IResolvedSectionHeaderFooterReference;
+export declare function resolveSectionHeaderFooterReferences(documentStyle: IDocumentStyle, sections: Readonly<ISectionBreak[]>, sectionIndex: number): Pick<ISectionBreak, SectionHeaderFooterReferenceKey>;

package/lib/types/facade/f-enum.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { AbsoluteRefType, AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, HorizontalAlign, InterpolationPointType, LifecycleStages, LocaleType, MentionType, ProtectionType, RelativeDate, SheetTypes, TextDecoration, TextDirection, ThemeColorType, UniverInstanceType, VerticalAlign, WrapStrategy } from '@univerjs/core';
+import { AbsoluteRefType, AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, HorizontalAlign, ImageSourceType, InterpolationPointType, LifecycleStages, LocaleType, MentionType, NumberUnitType, PresetListType, ProtectionType, RelativeDate, SheetTypes, SpacingRule, TextDecoration, TextDirection, ThemeColorType, UniverInstanceType, VerticalAlign, WrapStrategy } from '@univerjs/core';
 /**
  * @hideconstructor
  */
@@ -136,6 +136,36 @@ export declare class FEnum {
      * ```
      */
     get HorizontalAlign(): typeof HorizontalAlign;
+    /**
+     * Paragraph line-height interpretation modes
+     *
+     * @example
+     * ```ts
+     * console.log(univerAPI.Enum.SpacingRule.EXACT);
+     * ```
+     */
+    get SpacingRule(): typeof SpacingRule;
+    /**
+     * Units accepted by document lengths such as paragraph indentation and spacing
+     *
+     * Agent-facing rich-text helpers accept plain numbers as document points, so this enum is only needed when an
+     * explicit alternative unit is required.
+     *
+     * @example
+     * ```ts
+     * console.log(univerAPI.Enum.NumberUnitType.POINT);
+     * ```
+     */
+    get NumberUnitType(): typeof NumberUnitType;
+    /**
+     * Preset ordered, unordered, and checklist styles used by rich-text list items
+     *
+     * @example
+     * ```ts
+     * console.log(univerAPI.Enum.PresetListType.BULLET_LIST);
+     * ```
+     */
+    get PresetListType(): typeof PresetListType;
     /**
      * Different text decoration styles
      *
@@ -325,4 +355,13 @@ export declare class FEnum {
      * ```
      */
     get ThemeColorType(): typeof ThemeColorType;
+    /**
+     * Image source types
+     *
+     * @example
+     * ```ts
+     * console.log(univerAPI.Enum.ImageSourceType.URL);
+     * ```
+     */
+    get ImageSourceType(): typeof ImageSourceType;
 }