@univerjs/docs 1.0.0-alpha.6 → 1.0.0-alpha.8

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

@@ -16,6 +16,8 @@
 import type { Injector, IParagraph, IParagraphStyle } from '@univerjs/core';
 import type { FDocument } from './f-document';
 import type { IFDocumentTextRange } from './utils';
+import { ICommandService } from '@univerjs/core';
+import { FBaseInitialable } from '@univerjs/core/facade';
 import { FDocumentTextRange } from './f-document-text-range';
 /**
  * Resolved paragraph metadata in the the document body.
@@ -30,6 +32,21 @@ export interface IFDocumentParagraphInfo {
     /** The exclusive end offset of the paragraph text, before the paragraph break. */
     endOffset: number;
 }
+/**
+ * Options for locating text inside a document paragraph.
+ */
+export interface IFDocumentFindTextOptions {
+    /**
+     * Whether matching is case-sensitive.
+     * @default true
+     */
+    matchCase?: boolean;
+    /**
+     * Zero-based occurrence to return from {@link FDocumentParagraph.findText}.
+     * @default 0
+     */
+    occurrence?: number;
+}
 /**
  * A paragraph facade wrapper.
  *
@@ -39,12 +56,13 @@ export interface IFDocumentParagraphInfo {
  *
  * @hideconstructor
  */
-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);
+export declare class FDocumentParagraph extends FBaseInitialable {
+    protected readonly _document: FDocument;
+    protected readonly _paragraphId: string;
+    protected readonly _segmentId: string;
+    protected readonly _injector: Injector;
+    private readonly _commandService;
+    constructor(_document: FDocument, _paragraphId: string, _segmentId: string | undefined, _injector: Injector, _commandService: ICommandService);
     /**
      * Get the persisted paragraph id.
      * @returns {string} The paragraph id.
@@ -103,6 +121,55 @@ export declare class FDocumentParagraph {
      * ```
      */
     getTextRange(): FDocumentTextRange;
+    /**
+     * Finds one literal text occurrence inside this paragraph.
+     *
+     * The returned text range is fixed when it is created. Resolve a new range
+     * after edits that insert or remove content before the match.
+     *
+     * @param {string} text Literal text to find. It must not be empty.
+     * @param {IFDocumentFindTextOptions} [options] Case sensitivity and zero-based occurrence.
+     * @returns {FDocumentTextRange | null} The matching fixed text range, or `null` when no such occurrence exists.
+     * @example
+     * ```ts
+     * const univerAPI = FUniver.newAPI(univer);
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) throw new Error('No active document');
+     *
+     * const paragraph = document.findParagraphByText('Launch formula');
+     * if (!paragraph) throw new Error('Target paragraph not found');
+     *
+     * const range = paragraph.findText('formula');
+     * if (!range) throw new Error('Target text not found');
+     *
+     * console.log(range.describe());
+     * ```
+     */
+    findText(text: string, options?: IFDocumentFindTextOptions): FDocumentTextRange | null;
+    /**
+     * Finds every non-overlapping literal text occurrence inside this paragraph.
+     *
+     * Results are ordered from the start of the paragraph. The returned ranges
+     * are fixed when created; use them immediately and resolve new ranges after
+     * edits that change earlier document content.
+     *
+     * @param {string} text Literal text to find. It must not be empty.
+     * @param {Omit<IFDocumentFindTextOptions, 'occurrence'>} [options] Case-sensitivity option.
+     * @returns {FDocumentTextRange[]} All matching fixed text ranges, or an empty array when no matches exist.
+     * @example
+     * ```ts
+     * const univerAPI = FUniver.newAPI(univer);
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) throw new Error('No active document');
+     *
+     * const paragraph = document.findParagraphByText('x plus x');
+     * if (!paragraph) throw new Error('Target paragraph not found');
+     *
+     * const matches = paragraph.findAllText('x');
+     * console.log(matches.map((range) => range.describe()));
+     * ```
+     */
+    findAllText(text: string, options?: Omit<IFDocumentFindTextOptions, 'occurrence'>): FDocumentTextRange[];
     /**
      * Get this paragraph's plain text.
      * @returns {string} The paragraph text without the trailing paragraph break.
@@ -141,25 +208,53 @@ export declare class FDocumentParagraph {
      */
     appendText(text: string): boolean;
     /**
-     * Apply paragraph style to a paragraph handle or text range.
+     * Applies a paragraph and optional text-style patch through one document command.
+     *
+     * Pagination values use `BooleanNumber.TRUE` or `BooleanNumber.FALSE`; explicit
+     * false is preserved and overrides inherited true. The paragraph and text-style
+     * changes share one undo/redo item. A stale paragraph handle returns `false`
+     * without applying a partial update.
+     *
+     * The Traditional renderer applies these Word-compatible pagination rules:
+     * use `pageBreakBefore` for a hard chapter-page boundary, `keepLines` for a
+     * short paragraph that should stay intact, `keepNext` for a heading or caption
+     * that should accompany the next paragraph, and `widowControl` for natural
+     * multi-line body text. Do not enable every rule on every paragraph. Modern
+     * and Unspecified Docs preserve the values in the model but do not apply them
+     * to physical pages.
+     *
      * `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.
+     * @returns {boolean} `true` when the complete patch was applied; otherwise `false`.
      * @example
      * ```ts
-     * const fDocument = univerAPI.getActiveDocument();
-     * const paragraph = fDocument.getParagraphs()[0];
-     * paragraph?.setText('Styled text');
-     * paragraph?.setStyle({
-     *   textStyle: {
-     *     cl: {
-     *       rgb: '#FF0000',
-     *     },
-     *     fs: 14,
-     *   },
-     *   horizontalAlign: 2,
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) {
+     *   throw new Error('No active document');
+     * }
+     * if (!document.isTraditional()) {
+     *   throw new Error('Traditional document pagination is required');
+     * }
+     * const heading = document.findParagraphByText('Appendix');
+     * const following = document.findParagraphByText('Supporting details');
+     * if (!heading || !following) {
+     *   throw new Error('Expected paragraphs were not found');
+     * }
+     *
+     * const headingUpdated = heading.setStyle({
+     *   pageBreakBefore: univerAPI.Enum.BooleanNumber.TRUE,
+     *   keepLines: univerAPI.Enum.BooleanNumber.TRUE,
+     *   keepNext: univerAPI.Enum.BooleanNumber.TRUE,
      * });
-     * console.log(paragraph?.getInfo().paragraph.paragraphStyle);
+     * const followingUpdated = following.setStyle({
+     *   // Explicit FALSE terminates this authored keepNext chain even if a named
+     *   // style or document default enables it.
+     *   keepNext: univerAPI.Enum.BooleanNumber.FALSE,
+     *   widowControl: univerAPI.Enum.BooleanNumber.TRUE,
+     * });
+     * if (!headingUpdated || !followingUpdated) {
+     *   throw new Error('Failed to update paragraph pagination');
+     * }
      * ```
      */
     setStyle(style: IParagraphStyle): boolean;

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

@@ -13,21 +13,20 @@
  * 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 { ISectionBreak, ISectionColumnProperties, SectionHeaderFooterKind, SectionHeaderFooterVariant } from '@univerjs/core';
+import type { IEffectiveSectionPageSetup, IHeaderFooterProps } from '@univerjs/docs';
 import type { FDocument } from './f-document';
 import type { IFDocumentTextRange } from './utils';
-import { ColumnSeparatorType, SectionType } from '@univerjs/core';
+import { ColumnSeparatorType, ICommandService, SectionType } from '@univerjs/core';
 export interface IFDocumentSectionColumnOptions {
-    /** Gap after each column except the last, in points (pt). */
+    /** Gap after each column except the last, in 96-DPI layout pixels. */
     gap?: number;
-    /** Optional explicit column widths in points (pt). Length must equal `columnCount`. */
+    /** Optional explicit column widths in 96-DPI layout pixels. 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 type FDocumentSectionPageSetup = Pick<ISectionBreak, 'pageNumberStart' | 'pageSize' | 'pageOrient' | 'marginTop' | 'marginBottom' | 'marginLeft' | 'marginRight'>;
 export interface IFDocumentSectionDescription {
     sectionId: string;
     index: number;
@@ -42,17 +41,18 @@ export interface IFDocumentSectionDescription {
     }>;
     config: ISectionBreak;
 }
-/** Error thrown when traditional section APIs are used to mutate a modern document. */
+/** Error thrown when a Traditional-only section API is used with another document flavor. */
 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.
+ * Modern documents use ColumnGroup APIs. Unspecified documents must resolve
+ * their flavor before using this facade.
  * @example
  * ```ts
  * const fDocument = univerAPI.getActiveDocument();
- * if (fDocument && !fDocument.isModern()) {
+ * if (fDocument?.isTraditional()) {
  *   console.log(fDocument.getSection(0)?.describe());
  * }
  * ```
@@ -60,8 +60,8 @@ export declare class DocsSectionUnsupportedDocumentFlavorError extends Error {
 export declare class FDocumentSection {
     private readonly _document;
     private readonly _sectionId;
-    private readonly _injector;
-    constructor(_document: FDocument, _sectionId: string, _injector: Injector);
+    private readonly _commandService;
+    constructor(_document: FDocument, _sectionId: string, _commandService: ICommandService);
     /**
      * Returns the persisted section id.
      * @example
@@ -100,7 +100,7 @@ export declare class FDocumentSection {
     getRange(): IFDocumentTextRange;
     /**
      * Returns the explicit columns. An empty array means the normal single-column layout.
-     * Column widths and trailing spaces are in points (pt).
+     * Column widths and trailing spaces are in 96-DPI layout pixels.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
@@ -120,22 +120,22 @@ export declare class FDocumentSection {
     /**
      * 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).
+     * `gap` and `widths` are in 96-DPI layout pixels.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   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).
+     * Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   fDocument.getSection(0)?.setColumnProperties([
      *     { width: 240, paddingEnd: 18 },
      *     { width: 240, paddingEnd: 0 },
@@ -145,22 +145,123 @@ export declare class FDocumentSection {
      */
     setColumnProperties(columns: ISectionColumnProperties[], separator?: ColumnSeparatorType): boolean;
     /**
-     * Sets how the next section begins.
+     * Sets how this section begins relative to the previous section.
+     *
+     * The first section has no preceding boundary, so setting its type does not
+     * create an initial blank page. Prefer `FDocument.insertSectionBreak` with
+     * `nextSectionType` when creating a new boundary; use this method when
+     * updating an existing section after resolving it again from the document.
+     *
+     * @param {SectionType} sectionType How this section begins.
+     * @returns {boolean} `true` when the section command was applied.
      * @example
      * ```ts
-     * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
-     *   fDocument.getSection(0)?.setSectionType(univerAPI.Enum.SectionType.NEXT_PAGE);
+     * const document = univerAPI.getActiveDocument();
+     * if (!document?.isTraditional()) {
+     *   throw new Error('A Traditional document is required');
+     * }
+     *
+     * const secondSection = document.getSection(1);
+     * if (!secondSection) {
+     *   throw new Error('The second section does not exist');
+     * }
+     * if (!secondSection.setSectionType(univerAPI.Enum.SectionType.NEXT_PAGE)) {
+     *   throw new Error('Failed to update the second section');
      * }
      * ```
      */
     setSectionType(sectionType: SectionType): boolean;
+    /**
+     * Returns this section's explicit page setup overrides.
+     * Missing values inherit from the document style. Geometry values use 96-DPI layout pixels.
+     *
+     * Use `getEffectivePageSetup()` when an agent needs resolved page and content
+     * dimensions rather than only the overrides stored on this section.
+     *
+     * @returns {FDocumentSectionPageSetup} A cloned object containing only explicit section overrides.
+     * @example
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * const section = document?.getSection(0);
+     * console.log(section?.getPageSetup());
+     * ```
+     */
+    getPageSetup(): FDocumentSectionPageSetup;
+    /**
+     * Returns nominal page geometry after resolving this section's overrides
+     * against document defaults. All geometry values use 96-DPI layout pixels.
+     *
+     * This synchronous model-only API works without `engine-render`. It does not
+     * report physical page count, remaining page space, or final coordinates.
+     *
+     * @returns {IEffectiveSectionPageSetup} A cloned, serializable page setup.
+     * @example
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * if (!document) {
+     *   throw new Error('No active document');
+     * }
+     * if (!document.isTraditional()) {
+     *   throw new Error('Traditional document sections are required');
+     * }
+     *
+     * const section = document.getSection(0);
+     * if (!section) {
+     *   throw new Error('The document has no traditional section');
+     * }
+     *
+     * const layout = section.getEffectivePageSetup();
+     * console.log({
+     *   pageWidth: layout.pageSize.width,
+     *   pageHeight: layout.pageSize.height,
+     *   contentWidth: layout.contentSize.width,
+     *   contentHeight: layout.contentSize.height,
+     *   margins: layout.margins,
+     * });
+     * ```
+     */
+    getEffectivePageSetup(): IEffectiveSectionPageSetup;
+    /**
+     * Updates this section's page setup through the document section command.
+     * Geometry values use 96-DPI layout pixels.
+     *
+     * This method changes static page geometry; it does not choose where the
+     * section begins. Use `setSectionType()` for an existing boundary, or
+     * `insertSectionBreak(..., { nextSectionType })` while creating one.
+     *
+     * @param {FDocumentSectionPageSetup} pageSetup Explicit section overrides to patch.
+     * @returns {boolean} `true` when the section command was applied.
+     * @example
+     * ```ts
+     * const document = univerAPI.getActiveDocument();
+     * if (!document?.isTraditional()) {
+     *   throw new Error('A Traditional document is required');
+     * }
+     *
+     * const section = document.getSection(1);
+     * if (!section) {
+     *   throw new Error('The second section does not exist');
+     * }
+     * const updated = section.setPageSetup({
+     *   pageSize: { width: 816, height: 1056 },
+     *   marginTop: 96,
+     *   marginBottom: 96,
+     *   marginLeft: 96,
+     *   marginRight: 96,
+     * });
+     * if (!updated) {
+     *   throw new Error('Failed to update section page setup');
+     * }
+     * console.log(section.getEffectivePageSetup());
+     * ```
+     */
+    setPageSetup(pageSetup: FDocumentSectionPageSetup): boolean;
     /**
      * Ensures a header segment linked specifically to this section.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   const segmentId = fDocument.getSection(0)?.ensureHeader();
      *   if (segmentId) {
      *     fDocument.insertText(0, 'Quarterly report', segmentId);
@@ -174,7 +275,7 @@ export declare class FDocumentSection {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   const segmentId = fDocument.getSection(0)?.ensureFooter('first');
      *   if (segmentId) {
      *     fDocument.insertText(0, 'Confidential', segmentId);
@@ -224,7 +325,7 @@ export declare class FDocumentSection {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   fDocument.getSection(1)?.setHeaderLinkedToPrevious(false, 'default');
      * }
      * ```
@@ -235,7 +336,7 @@ export declare class FDocumentSection {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   fDocument.getSection(1)?.setFooterLinkedToPrevious(true, 'even');
      * }
      * ```
@@ -243,11 +344,11 @@ export declare class FDocumentSection {
     setFooterLinkedToPrevious(linkedToPrevious: boolean, variant?: SectionHeaderFooterVariant): boolean;
     /**
      * Updates header/footer switches and margins on this section break.
-     * `marginHeader` and `marginFooter` are in points (pt).
+     * `marginHeader` and `marginFooter` are in 96-DPI layout pixels.
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   fDocument.getSection(0)?.setHeaderFooterOptions({
      *     marginHeader: 36,
      *     marginFooter: 36,
@@ -262,7 +363,7 @@ export declare class FDocumentSection {
      * @example
      * ```ts
      * const fDocument = univerAPI.getActiveDocument();
-     * if (fDocument && !fDocument.isModern()) {
+     * if (fDocument?.isTraditional()) {
      *   const sections = fDocument.getSections();
      *   if (sections.length > 1) {
      *     sections[0].remove();
@@ -277,5 +378,7 @@ export declare class FDocumentSection {
     private _describeHeaderFooterReference;
     private _setHeaderFooterLinkedToPrevious;
     private _assertTraditionalDocument;
+    private _getConfigSnapshot;
+    private _getRange;
     private _resolve;
 }

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

@@ -16,6 +16,7 @@
 import type { Injector, ITextStyle } from '@univerjs/core';
 import type { FDocument } from './f-document';
 import type { IFDocumentTextRange } from './utils';
+import { FBaseInitialable } from '@univerjs/core/facade';
 /** A clipped text-style run in document offsets. */
 export interface IFDocumentTextStyleRun {
     /** Inclusive start offset in the document segment. */
@@ -33,10 +34,6 @@ export interface IFDocumentTextRangeDescription extends IFDocumentTextRange {
     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.
@@ -45,12 +42,12 @@ export interface IFDocumentTextRangeDescription extends IFDocumentTextRange {
  * 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;
+export declare class FDocumentTextRange extends FBaseInitialable {
+    protected readonly _document: FDocument;
+    protected readonly _startOffset: number;
+    protected readonly _endOffset: number;
+    protected readonly _segmentId: string;
+    protected readonly _injector: Injector;
     constructor(_document: FDocument, _startOffset: number, _endOffset: number, _segmentId: string, _injector: Injector);
     /**
      * Returns the serializable document range.
@@ -83,8 +80,6 @@ export declare class FDocumentTextRange {
      * ```
      */
     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.
@@ -96,8 +91,6 @@ export declare class FDocumentTextRange {
      * ```
      */
     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