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

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

@@ -23,7 +23,9 @@ export declare enum HeaderFooterType {
     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;
@@ -35,7 +37,9 @@ export interface ICreateHeaderFooterCommandParams {
     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, documentStyle: IHeaderFooterProps, actions: JSONXActions, createMode?: HeaderFooterCreateMode): JSONXActions;
+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

@@ -16,6 +16,7 @@
 import type { Injector, IParagraph, IParagraphStyle } from '@univerjs/core';
 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.
  */
@@ -90,6 +91,18 @@ export declare class FDocumentParagraph {
      * ```
      */
     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.
@@ -129,6 +142,7 @@ export declare class FDocumentParagraph {
     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

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

@@ -0,0 +1,281 @@
+/**
+ * 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 { Injector, ISectionBreak, ISectionColumnProperties, SectionHeaderFooterKind, SectionHeaderFooterVariant } from '@univerjs/core';
+import type { IHeaderFooterProps } from '@univerjs/docs';
+import type { FDocument } from './f-document';
+import type { IFDocumentTextRange } from './utils';
+import { ColumnSeparatorType, SectionType } from '@univerjs/core';
+export interface IFDocumentSectionColumnOptions {
+    /** Gap after each column except the last, in points (pt). */
+    gap?: number;
+    /** Optional explicit column widths in points (pt). Length must equal `columnCount`. */
+    widths?: number[];
+    /** Whether to draw separators, or the exact separator enum value. */
+    separator?: boolean | ColumnSeparatorType;
+    /** How the following section starts. */
+    sectionType?: SectionType;
+}
+export interface IFDocumentSectionDescription {
+    sectionId: string;
+    index: number;
+    range: IFDocumentTextRange;
+    columnCount: number;
+    columns: ISectionColumnProperties[];
+    columnSeparatorType: ColumnSeparatorType;
+    sectionType: SectionType;
+    headerFooter: Record<`${SectionHeaderFooterVariant}${Capitalize<SectionHeaderFooterKind>}`, {
+        segmentId: string | null;
+        linkedToPrevious: boolean;
+    }>;
+    config: ISectionBreak;
+}
+/** Error thrown when traditional section APIs are used to mutate a modern document. */
+export declare class DocsSectionUnsupportedDocumentFlavorError extends Error {
+    constructor();
+}
+/**
+ * Facade wrapper for an OOXML-compatible traditional document section.
+ * Modern documents use ColumnGroup APIs and cannot mutate this facade.
+ * @example
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * if (fDocument && !fDocument.isModern()) {
+ *   console.log(fDocument.getSection(0)?.describe());
+ * }
+ * ```
+ */
+export declare class FDocumentSection {
+    private readonly _document;
+    private readonly _sectionId;
+    private readonly _injector;
+    constructor(_document: FDocument, _sectionId: string, _injector: Injector);
+    /**
+     * Returns the persisted section id.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getId());
+     * ```
+     */
+    getId(): string;
+    /**
+     * Returns the current zero-based section index.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getIndex());
+     * ```
+     */
+    getIndex(): number;
+    /**
+     * Returns the section break snapshot that terminates this section.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getConfig());
+     * ```
+     */
+    getConfig(): ISectionBreak;
+    /**
+     * Returns the section content range, excluding its terminating section-break token.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getRange());
+     * ```
+     */
+    getRange(): IFDocumentTextRange;
+    /**
+     * Returns the explicit columns. An empty array means the normal single-column layout.
+     * Column widths and trailing spaces are in points (pt).
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getColumns());
+     * ```
+     */
+    getColumns(): ISectionColumnProperties[];
+    /**
+     * Returns a compact serializable section summary.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.describe());
+     * ```
+     */
+    describe(): IFDocumentSectionDescription;
+    /**
+     * Sets equal or explicitly sized columns for this traditional section.
+     * Use `columnCount = 1` to restore normal single-column layout.
+     * `gap` and `widths` are in points (pt).
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   fDocument.getSection(0)?.setColumns(2, { gap: 18, separator: true });
+     * }
+     * ```
+     */
+    setColumns(columnCount: number, options?: IFDocumentSectionColumnOptions): boolean;
+    /**
+     * Sets explicit OOXML-compatible column width and trailing-space values in points (pt).
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   fDocument.getSection(0)?.setColumnProperties([
+     *     { width: 240, paddingEnd: 18 },
+     *     { width: 240, paddingEnd: 0 },
+     *   ], univerAPI.Enum.ColumnSeparatorType.BETWEEN_EACH_COLUMN);
+     * }
+     * ```
+     */
+    setColumnProperties(columns: ISectionColumnProperties[], separator?: ColumnSeparatorType): boolean;
+    /**
+     * Sets how the next section begins.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   fDocument.getSection(0)?.setSectionType(univerAPI.Enum.SectionType.NEXT_PAGE);
+     * }
+     * ```
+     */
+    setSectionType(sectionType: SectionType): boolean;
+    /**
+     * Ensures a header segment linked specifically to this section.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   const segmentId = fDocument.getSection(0)?.ensureHeader();
+     *   if (segmentId) {
+     *     fDocument.insertText(0, 'Quarterly report', segmentId);
+     *   }
+     * }
+     * ```
+     */
+    ensureHeader(variant?: SectionHeaderFooterVariant): string;
+    /**
+     * Ensures a footer segment linked specifically to this section.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   const segmentId = fDocument.getSection(0)?.ensureFooter('first');
+     *   if (segmentId) {
+     *     fDocument.insertText(0, 'Confidential', segmentId);
+     *   }
+     * }
+     * ```
+     */
+    ensureFooter(variant?: SectionHeaderFooterVariant): string;
+    /**
+     * Returns the effective header id after resolving links to previous sections.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getHeaderId('default'));
+     * ```
+     */
+    getHeaderId(variant?: SectionHeaderFooterVariant): string | null;
+    /**
+     * Returns the effective footer id after resolving links to previous sections.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(0)?.getFooterId('first'));
+     * ```
+     */
+    getFooterId(variant?: SectionHeaderFooterVariant): string | null;
+    /**
+     * Whether this header variant inherits the previous section's reference.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(1)?.isHeaderLinkedToPrevious());
+     * ```
+     */
+    isHeaderLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean;
+    /**
+     * Whether this footer variant inherits the previous section's reference.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * console.log(fDocument?.getSection(1)?.isFooterLinkedToPrevious('even'));
+     * ```
+     */
+    isFooterLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean;
+    /**
+     * Links or unlinks this header variant. Unlinking clones the inherited header.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   fDocument.getSection(1)?.setHeaderLinkedToPrevious(false, 'default');
+     * }
+     * ```
+     */
+    setHeaderLinkedToPrevious(linkedToPrevious: boolean, variant?: SectionHeaderFooterVariant): boolean;
+    /**
+     * Links or unlinks this footer variant. Unlinking clones the inherited footer.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   fDocument.getSection(1)?.setFooterLinkedToPrevious(true, 'even');
+     * }
+     * ```
+     */
+    setFooterLinkedToPrevious(linkedToPrevious: boolean, variant?: SectionHeaderFooterVariant): boolean;
+    /**
+     * Updates header/footer switches and margins on this section break.
+     * `marginHeader` and `marginFooter` are in points (pt).
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   fDocument.getSection(0)?.setHeaderFooterOptions({
+     *     marginHeader: 36,
+     *     marginFooter: 36,
+     *     useFirstPageHeaderFooter: univerAPI.Enum.BooleanNumber.TRUE,
+     *   });
+     * }
+     * ```
+     */
+    setHeaderFooterOptions(options: IHeaderFooterProps): boolean;
+    /**
+     * Deletes this section break. The final top-level section break cannot be removed.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * if (fDocument && !fDocument.isModern()) {
+     *   const sections = fDocument.getSections();
+     *   if (sections.length > 1) {
+     *     sections[0].remove();
+     *   }
+     * }
+     * ```
+     */
+    remove(): boolean;
+    private _update;
+    private _ensureHeaderFooter;
+    private _getHeaderFooterReference;
+    private _describeHeaderFooterReference;
+    private _setHeaderFooterLinkedToPrevious;
+    private _assertTraditionalDocument;
+    private _resolve;
+}

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

@@ -0,0 +1,136 @@
+/**
+ * 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 { Injector, ITextStyle } from '@univerjs/core';
+import type { FDocument } from './f-document';
+import type { IFDocumentTextRange } from './utils';
+/** A clipped text-style run in document offsets. */
+export interface IFDocumentTextStyleRun {
+    /** Inclusive start offset in the document segment. */
+    startOffset: number;
+    /** Exclusive end offset in the document segment. */
+    endOffset: number;
+    /** Explicit text style stored on this run. */
+    textStyle: ITextStyle;
+}
+/** Agent-friendly summary of a document text range. */
+export interface IFDocumentTextRangeDescription extends IFDocumentTextRange {
+    text: string;
+    length: number;
+    /** Explicit styles stored directly in text runs. */
+    explicitTextStyleRuns: IFDocumentTextStyleRun[];
+    /** Top-level explicit style properties common to the complete range. */
+    commonExplicitTextStyle: ITextStyle;
+    /** @deprecated Use `explicitTextStyleRuns`. */
+    textStyleRuns: IFDocumentTextStyleRun[];
+    /** @deprecated Use `commonExplicitTextStyle`. */
+    commonTextStyle: ITextStyle;
+}
+/**
+ * Facade wrapper for reading and styling a fixed document text range.
+ *
+ * Offsets are fixed when the wrapper is created. Create a new range after edits
+ * that insert or remove content before it.
+ * @hideconstructor
+ */
+export declare class FDocumentTextRange {
+    private readonly _document;
+    private readonly _startOffset;
+    private readonly _endOffset;
+    private readonly _segmentId;
+    private readonly _injector;
+    constructor(_document: FDocument, _startOffset: number, _endOffset: number, _segmentId: string, _injector: Injector);
+    /**
+     * Returns the serializable document range.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+     * console.log(range?.getRange());
+     * ```
+     */
+    getRange(): IFDocumentTextRange;
+    /**
+     * Returns the plain data-stream text in this range.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+     * console.log(range?.getText());
+     * ```
+     */
+    getText(): string;
+    /**
+     * Returns explicit text-style runs intersecting this range.
+     * Returned offsets are clipped to the range and remain document-relative.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+     * console.log(range?.getExplicitTextStyleRuns());
+     * ```
+     */
+    getExplicitTextStyleRuns(): IFDocumentTextStyleRun[];
+    /** @deprecated Use `getExplicitTextStyleRuns()` to distinguish stored styles from effective styles. */
+    getTextStyleRuns(): IFDocumentTextStyleRun[];
+    /**
+     * Returns top-level style properties that have the same explicit value
+     * across the complete range. Unstyled gaps make a property non-common.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+     * console.log(range?.getCommonExplicitTextStyle());
+     * ```
+     */
+    getCommonExplicitTextStyle(): ITextStyle;
+    /** @deprecated Use `getCommonExplicitTextStyle()` to distinguish stored styles from effective styles. */
+    getCommonTextStyle(): ITextStyle;
+    /**
+     * Returns a serializable summary suitable for an agent/tool response.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+     * console.log(range?.describe());
+     * ```
+     */
+    describe(): IFDocumentTextRangeDescription;
+    /**
+     * Merges a text-style patch into every character in the range.
+     * Existing text-run splitting, merging, and normalization are handled by
+     * the document mutation pipeline.
+     * `style.fs` is a font size in points (pt), not CSS pixels.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+     * range?.setTextStyle({ fs: 10.5, bl: univerAPI.Enum.BooleanNumber.TRUE });
+     * ```
+     */
+    setTextStyle(style: ITextStyle): boolean;
+    /**
+     * Replaces the range with plain text while preserving document mutation semantics.
+     * @example
+     * ```ts
+     * const fDocument = univerAPI.getActiveDocument();
+     * const range = fDocument?.findParagraphByText('Draft')?.getTextRange();
+     * range?.setText('Final');
+     * ```
+     */
+    setText(text: string): boolean;
+    private _validateRange;
+    private _getStyleSegments;
+}