@univerjs/docs 1.0.0-rc.0 → 1.0.1

package/lib/cjs/facade.js

@@ -304,7 +304,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);
@@ -312,7 +312,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);
@@ -421,6 +421,8 @@ let FDocumentTextRange = class FDocumentTextRange extends _univerjs_core_facade.
 	* 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();
@@ -441,6 +443,8 @@ let FDocumentTextRange = class FDocumentTextRange extends _univerjs_core_facade.
 	}
 	/**
 	* 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();
@@ -1000,6 +1004,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();
@@ -1025,6 +1033,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();
@@ -1191,6 +1203,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();
@@ -1207,6 +1221,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();
@@ -1223,6 +1239,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();
@@ -1234,6 +1252,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();
@@ -1245,6 +1265,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();
@@ -1256,6 +1278,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();
@@ -1267,6 +1291,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();
@@ -1280,6 +1307,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();
@@ -1294,6 +1324,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();
@@ -1373,7 +1405,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	_getHeaderFooterReference(kind, variant) {
 		const { index } = this._resolve();
-		return (0, _univerjs_core.resolveSectionHeaderFooterReference)(this._document.getDocumentDataModel().getSnapshot().documentStyle, (0, _univerjs_docs.getTopLevelSectionBreaks)(this._document.getBody()), index, (0, _univerjs_core.getSectionHeaderFooterReferenceKey)(kind, variant));
+		const snapshot = this._document.getDocumentDataModel().getSnapshot();
+		return (0, _univerjs_core.resolveSectionHeaderFooterReference)(snapshot.documentStyle, (0, _univerjs_docs.getTopLevelSectionBreaks)(this._document.getBody()), index, (0, _univerjs_core.getSectionHeaderFooterReferenceKey)(kind, variant));
 	}
 	_describeHeaderFooterReference(kind, variant) {
 		const reference = this._getHeaderFooterReference(kind, variant);
@@ -1421,7 +1454,7 @@ let FDocumentSection = class FDocumentSection {
 FDocumentSection = __decorate([__decorateParam(2, _univerjs_core.ICommandService), __decorateParam(3, _univerjs_core.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) {
@@ -1432,7 +1465,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];
@@ -1445,14 +1478,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,
@@ -1478,7 +1511,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -1520,7 +1553,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -1537,6 +1570,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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();
 	}
@@ -1727,7 +1761,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -1741,7 +1775,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -1757,7 +1791,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -1798,6 +1832,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.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();
@@ -1821,7 +1857,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -1849,6 +1885,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.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();
@@ -1861,6 +1899,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.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();
@@ -1945,6 +1985,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.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();
@@ -1968,6 +2010,10 @@ let FDocument = class FDocument extends _univerjs_core_facade.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();
@@ -1998,7 +2044,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -2018,7 +2064,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -2039,7 +2085,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -2087,8 +2133,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.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
@@ -2115,8 +2161,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.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