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

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;
+}