@univerjs/docs 1.0.0-rc.0 → 1.0.0

package/lib/facade.js

@@ -303,7 +303,7 @@ function stripBlockTokens(text) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorateParam.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);
@@ -311,7 +311,7 @@ function __decorateParam(paramIndex, decorator) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -420,6 +420,8 @@ let FDocumentTextRange = class FDocumentTextRange extends FBaseInitialable {
 	* 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.
+	* @param {ITextStyle} style Text-style properties to merge into the range.
+	* @returns {boolean} Whether the style update succeeded; `false` for an empty range.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -440,6 +442,8 @@ let FDocumentTextRange = class FDocumentTextRange extends FBaseInitialable {
 	}
 	/**
 	* Replaces the range with plain text while preserving document mutation semantics.
+	* @param {string} text Replacement plain text. An empty string deletes the range.
+	* @returns {boolean} Whether the replacement succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -999,6 +1003,10 @@ let FDocumentSection = 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 96-DPI layout pixels.
+	* @param {number} columnCount Positive integer column count.
+	* @param {IFDocumentSectionColumnOptions} [options] Column widths, gap (default 18 pixels), and separator (default none).
+	* @returns {boolean} Whether the section update succeeded.
+	* @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1024,6 +1032,10 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.
+	* @param {ISectionColumnProperties[]} columns Explicit widths and trailing spaces; an empty array restores a single column.
+	* @param {ColumnSeparatorType} [separator] Column separator style. Defaults to `ColumnSeparatorType.NONE`.
+	* @returns {boolean} Whether the section update succeeded.
+	* @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1190,6 +1202,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Ensures a header segment linked specifically to this section.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string} The existing or newly created section-specific segment ID.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1206,6 +1220,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Ensures a footer segment linked specifically to this section.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string} The existing or newly created section-specific segment ID.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1222,6 +1238,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Returns the effective header id after resolving links to previous sections.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string | null} The effective segment ID, or `null` if no segment is available.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1233,6 +1251,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Returns the effective footer id after resolving links to previous sections.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string | null} The effective segment ID, or `null` if no segment is available.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1244,6 +1264,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Whether this header variant inherits the previous section's reference.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether this variant inherits from the previous section.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1255,6 +1277,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Whether this footer variant inherits the previous section's reference.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether this variant inherits from the previous section.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1266,6 +1290,9 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Links or unlinks this header variant. Unlinking clones the inherited header.
+	* @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether the link update succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1279,6 +1306,9 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Links or unlinks this footer variant. Unlinking clones the inherited footer.
+	* @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether the link update succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1293,6 +1323,8 @@ let FDocumentSection = class FDocumentSection {
 	/**
 	* Updates header/footer switches and margins on this section break.
 	* `marginHeader` and `marginFooter` are in 96-DPI layout pixels.
+	* @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+	* @returns {boolean} Whether the update command succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1372,7 +1404,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	_getHeaderFooterReference(kind, variant) {
 		const { index } = this._resolve();
-		return resolveSectionHeaderFooterReference(this._document.getDocumentDataModel().getSnapshot().documentStyle, getTopLevelSectionBreaks(this._document.getBody()), index, getSectionHeaderFooterReferenceKey(kind, variant));
+		const snapshot = this._document.getDocumentDataModel().getSnapshot();
+		return resolveSectionHeaderFooterReference(snapshot.documentStyle, getTopLevelSectionBreaks(this._document.getBody()), index, getSectionHeaderFooterReferenceKey(kind, variant));
 	}
 	_describeHeaderFooterReference(kind, variant) {
 		const reference = this._getHeaderFooterReference(kind, variant);
@@ -1420,7 +1453,7 @@ let FDocumentSection = class FDocumentSection {
 FDocumentSection = __decorate([__decorateParam(2, ICommandService), __decorateParam(3, IPermissionService)], FDocumentSection);
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -1431,7 +1464,7 @@ function _typeof(o) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -1444,14 +1477,14 @@ function toPrimitive(t, r) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -1477,7 +1510,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Get the document data model of the document.
-	* @param {string} segmentId The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.
+	* @param {string} [segmentId] The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.
 	* @returns {DocumentDataModel} The document data model.
 	* @example
 	* ```typescript
@@ -1519,7 +1552,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Get the document body or header/footer body by the segment id.
 	* The main body has an empty segment id.
 	* The header and footer body have their respective segment ids.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {IDocumentBody} The document body.
 	* @example
 	* ```typescript
@@ -1536,6 +1569,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 		if (!body) throw new Error(segmentId === "" ? "Body is not found in the document." : `Body is not found in the segment: ${segmentId}`);
 		return body;
 	}
+	/** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
 	dispose() {
 		super.dispose();
 	}
@@ -1726,7 +1760,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Ensure the page header segment exists and return its segment id.
-	* @param {number} pageIndex The zero-based page index. Defaults to the first page.
+	* @param {number} [pageIndex] The zero-based page index. Defaults to the first page.
 	* @returns {string} The header segment id.
 	* @example
 	* ```ts
@@ -1740,7 +1774,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Ensure the page footer segment exists and return its segment id.
-	* @param {number} pageIndex The zero-based page index. Defaults to the first page.
+	* @param {number} [pageIndex] The zero-based page index. Defaults to the first page.
 	* @returns {string} The footer segment id.
 	* @example
 	* ```ts
@@ -1756,7 +1790,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Insert plain text at a document body offset.
 	* @param {number} index The zero-based insertion offset.
 	* @param {string} text The plain text to insert.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {boolean} `true` if the edit was applied.
 	* @example
 	* ```ts
@@ -1797,6 +1831,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Traditional and Unspecified documents keep the legacy header/footer
 	* behavior. Modern documents reject this API. `marginHeader` and
 	* `marginFooter` use 96-DPI layout pixels.
+	* @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+	* @returns {boolean} Whether the update command succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1820,7 +1856,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* The end offset is exclusive, and offsets are scoped to the selected body segment.
 	* @param {number} startOffset The inclusive start offset.
 	* @param {number} endOffset The exclusive end offset.
-	* @param {string} segmentId The header/footer segment id, or an empty string for the main body.
+	* @param {string} [segmentId] The header/footer segment id, or an empty string for the main body.
 	* @returns {FDocumentTextRange} A fixed text-range facade.
 	* @example
 	* ```ts
@@ -1848,6 +1884,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Returns a traditional section by zero-based index, or `null` in modern documents.
+	* @param {number} index Zero-based section index.
+	* @returns {FDocumentSection | null} The matching section, or `null` if none exists or the document is not Traditional.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1860,6 +1898,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Returns the traditional section containing a data-stream offset, or `null` in modern documents.
+	* @param {number} offset Zero-based data-stream offset in the main document body.
+	* @returns {FDocumentSection | null} The matching section, or `null` if none exists or the document is not Traditional.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1944,6 +1984,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* In a single-column section, the traditional renderer advances to the next physical page.
 	* Modern documents must use ColumnGroup. Unspecified documents must resolve
 	* their flavor first. Both throw `DocsSectionUnsupportedDocumentFlavorError`.
+	* @param {number} offset Zero-based data-stream offset at which to insert the column break.
+	* @returns {boolean} Whether the insertion succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1967,6 +2009,10 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Inserts a horizontal rule using the existing paragraph `borderBottom` mechanism.
 	* The returned paragraph can be inspected or removed with normal paragraph APIs.
 	* Border width and padding are in points (pt).
+	* @param {number} offset Zero-based insertion offset in the selected body segment.
+	* @param {IParagraphBorder} [border] Bottom border appearance. Defaults to a solid gray 1 pt line with 5 pt padding.
+	* @param {string} [segmentId] Header/footer segment ID, or an empty string for the main body (default).
+	* @returns {FDocumentParagraph | null} The inserted paragraph, or `null` if insertion fails.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1997,7 +2043,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Get all paragraphs in the document body or header/footer body by the segment id.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph[]} An array of paragraph facade instances.
 	* @example
 	* ```ts
@@ -2017,7 +2063,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	/**
 	* Get a paragraph by its paragraph id and segment id.
 	* @param {string} paragraphId The paragraph id.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph | null} The paragraph facade instance, or `null` if the paragraph is not found.
 	* @example
 	* ```ts
@@ -2038,7 +2084,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	/**
 	* Find a paragraph by its text content and segment id.
 	* @param {string} text The text content to search for.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph | null} The paragraph facade instance, or `null` if the paragraph is not found.
 	* @example
 	* ```ts
@@ -2086,8 +2132,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	/**
 	* Insert a plain-text paragraph before the paragraph at the given paragraph index.
 	* @param {number} index The zero-based paragraph insertion index.
-	* @param {string} text The paragraph text. Defaults to an empty paragraph.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [text] The paragraph text. Defaults to an empty paragraph.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph} The inserted paragraph facade instance.
 	* @example
 	* ```ts
@@ -2114,8 +2160,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Append a plain-text paragraph at the end of the body.
-	* @param {string} text The paragraph text. Defaults to an empty paragraph.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [text] The paragraph text. Defaults to an empty paragraph.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph} The appended paragraph wrapper.
 	* @example
 	* ```ts