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

package/lib/facade.js

@@ -1,6 +1,6 @@
-import { BooleanNumber, DataStreamTreeTokenType, DocumentFlavor, ICommandService, IResourceLoaderService, IUniverInstanceService, Inject, Injector, JSONX, PresetListType, RESTORE_INSERTED_PARAGRAPH_IDS, RedoCommand, TextX, TextXActionType, UndoCommand, UniverInstanceType, UpdateDocsAttributeType, createParagraphId, generateRandomId, getRichTextEditPath } from "@univerjs/core";
-import { FBaseInitialable, FUniver } from "@univerjs/core/facade";
-import { CreateHeaderFooterCommand, HeaderFooterType, RichTextEditingMutation } from "@univerjs/docs";
+import { BooleanNumber, ColumnSeparatorType, DashStyleType, DataStreamTreeTokenType, DocumentFlavor, ICommandService, IResourceLoaderService, IUniverInstanceService, Inject, Injector, JSONX, PresetListType, RESTORE_INSERTED_PARAGRAPH_IDS, RedoCommand, SectionType, TextX, TextXActionType, Tools, UndoCommand, UniverInstanceType, UpdateDocsAttributeType, createParagraphId, createSectionId, generateRandomId, getParagraphContentStartOffset, getRichTextEditPath, getSectionHeaderFooterReferenceKey, resolveSectionHeaderFooterReference } from "@univerjs/core";
+import { FBaseInitialable, FEnum, FUniver } from "@univerjs/core/facade";
+import { CreateHeaderFooterCommand, DeleteDocumentSectionBreakCommand, HeaderFooterType, InsertDocumentSectionBreakCommand, RichTextEditingMutation, SetSectionHeaderFooterLinkCommand, UpdateDocumentSectionCommand, createSectionColumnProperties, generateParagraphs, getTopLevelSectionBreaks } from "@univerjs/docs";
 
 //#region src/facade/utils.ts
 function cloneParagraphStyle(paragraphStyle) {
@@ -97,6 +97,184 @@ function stripBlockTokens(text) {
 	return Array.from(text).map((char) => char === DataStreamTreeTokenType.PARAGRAPH ? "\n" : char).filter((char) => char !== DataStreamTreeTokenType.BLOCK_START && char !== DataStreamTreeTokenType.BLOCK_END && char !== DataStreamTreeTokenType.SECTION_BREAK).join("").replace(/\n$/, "");
 }
 
+//#endregion
+//#region src/facade/f-document-text-range.ts
+/**
+* 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
+*/
+var FDocumentTextRange = class {
+	constructor(_document, _startOffset, _endOffset, _segmentId, _injector) {
+		this._document = _document;
+		this._startOffset = _startOffset;
+		this._endOffset = _endOffset;
+		this._segmentId = _segmentId;
+		this._injector = _injector;
+		this._validateRange();
+	}
+	/**
+	* Returns the serializable document range.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* const range = fDocument?.findParagraphByText('Launch')?.getTextRange();
+	* console.log(range?.getRange());
+	* ```
+	*/
+	getRange() {
+		return {
+			startOffset: this._startOffset,
+			endOffset: this._endOffset,
+			segmentId: this._segmentId
+		};
+	}
+	/**
+	* 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() {
+		return this._document.getBody(this._segmentId).dataStream.slice(this._startOffset, this._endOffset);
+	}
+	/**
+	* 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() {
+		const { textRuns = [] } = this._document.getBody(this._segmentId);
+		return textRuns.filter((run) => run.st < this._endOffset && run.ed > this._startOffset).map((run) => {
+			var _run$ts;
+			return {
+				startOffset: Math.max(run.st, this._startOffset),
+				endOffset: Math.min(run.ed, this._endOffset),
+				textStyle: Tools.deepClone((_run$ts = run.ts) !== null && _run$ts !== void 0 ? _run$ts : {})
+			};
+		});
+	}
+	/** @deprecated Use `getExplicitTextStyleRuns()` to distinguish stored styles from effective styles. */
+	getTextStyleRuns() {
+		return this.getExplicitTextStyleRuns();
+	}
+	/**
+	* 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() {
+		if (this._startOffset === this._endOffset) return {};
+		const [first, ...rest] = this._getStyleSegments();
+		const common = Tools.deepClone(first.textStyle);
+		for (const key of Object.keys(common)) if (rest.some((run) => !isDeepEqual(run.textStyle[key], common[key]))) delete common[key];
+		return common;
+	}
+	/** @deprecated Use `getCommonExplicitTextStyle()` to distinguish stored styles from effective styles. */
+	getCommonTextStyle() {
+		return this.getCommonExplicitTextStyle();
+	}
+	/**
+	* 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() {
+		const explicitTextStyleRuns = this.getExplicitTextStyleRuns();
+		const commonExplicitTextStyle = this.getCommonExplicitTextStyle();
+		return {
+			...this.getRange(),
+			text: this.getText(),
+			length: this._endOffset - this._startOffset,
+			explicitTextStyleRuns,
+			commonExplicitTextStyle,
+			textStyleRuns: explicitTextStyleRuns,
+			commonTextStyle: commonExplicitTextStyle
+		};
+	}
+	/**
+	* 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) {
+		if (this._startOffset === this._endOffset) return false;
+		return retainBodyRange(this.getRange(), {
+			dataStream: "",
+			textRuns: [{
+				st: 0,
+				ed: this._endOffset - this._startOffset,
+				ts: Tools.deepClone(style)
+			}]
+		}, UpdateDocsAttributeType.COVER, this._document.getDocumentDataModel(), this._injector);
+	}
+	/**
+	* 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) {
+		return replaceBodyRange(this.getRange(), buildPlainTextInsertBody(text), this._document.getDocumentDataModel(), this._injector);
+	}
+	_validateRange() {
+		const bodyLength = this._document.getBody(this._segmentId).dataStream.length;
+		if (!Number.isInteger(this._startOffset) || !Number.isInteger(this._endOffset) || this._startOffset < 0 || this._endOffset < this._startOffset || this._endOffset > bodyLength) throw new RangeError(`Invalid document text range [${this._startOffset}, ${this._endOffset}) for body length ${bodyLength}.`);
+	}
+	_getStyleSegments() {
+		const explicitRuns = this.getExplicitTextStyleRuns();
+		const segments = [];
+		let offset = this._startOffset;
+		for (const run of explicitRuns) {
+			if (offset < run.startOffset) segments.push({
+				startOffset: offset,
+				endOffset: run.startOffset,
+				textStyle: {}
+			});
+			segments.push(run);
+			offset = run.endOffset;
+		}
+		if (offset < this._endOffset) segments.push({
+			startOffset: offset,
+			endOffset: this._endOffset,
+			textStyle: {}
+		});
+		return segments;
+	}
+};
+function isDeepEqual(left, right) {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+
 //#endregion
 //#region src/facade/f-document-paragraph.ts
 /**
@@ -154,7 +332,8 @@ var FDocumentParagraph = class {
 	* ```
 	*/
 	getInfo() {
-		const { paragraphs = [] } = this._document.getBody(this._segmentId);
+		const body = this._document.getBody(this._segmentId);
+		const { paragraphs = [] } = body;
 		const matches = paragraphs.map((paragraph, paragraphIndex) => ({
 			paragraph,
 			paragraphIndex
@@ -165,7 +344,7 @@ var FDocumentParagraph = class {
 		return {
 			paragraph,
 			paragraphIndex,
-			startOffset: paragraphIndex > 0 ? paragraphs[paragraphIndex - 1].startIndex + 1 : 0,
+			startOffset: getParagraphContentStartOffset(body, paragraph),
 			endOffset: paragraph.startIndex
 		};
 	}
@@ -188,6 +367,21 @@ var FDocumentParagraph = class {
 		};
 	}
 	/**
+	* 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() {
+		const { startOffset, endOffset } = this.getInfo();
+		return this._injector.createInstance(FDocumentTextRange, this._document, startOffset, endOffset, this._segmentId, this._injector);
+	}
+	/**
 	* Get this paragraph's plain text.
 	* @returns {string} The paragraph text without the trailing paragraph break.
 	* @example
@@ -240,6 +434,7 @@ var FDocumentParagraph = class {
 	}
 	/**
 	* 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
@@ -387,6 +582,412 @@ function isParagraphFacade(value) {
 	return typeof value.getId === "function" && typeof value.getSegmentId === "function" && typeof value.getInfo === "function" && typeof value.getRange === "function";
 }
 
+//#endregion
+//#region src/facade/f-document-section.ts
+/** Error thrown when traditional section APIs are used to mutate a modern document. */
+var DocsSectionUnsupportedDocumentFlavorError = class extends Error {
+	constructor() {
+		super("Section column APIs are supported only in traditional documents. Use ColumnGroup APIs for modern documents.");
+		this.name = "DocsSectionUnsupportedDocumentFlavorError";
+	}
+};
+/**
+* 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());
+* }
+* ```
+*/
+var FDocumentSection = class {
+	constructor(_document, _sectionId, _injector) {
+		this._document = _document;
+		this._sectionId = _sectionId;
+		this._injector = _injector;
+	}
+	/**
+	* Returns the persisted section id.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* console.log(fDocument?.getSection(0)?.getId());
+	* ```
+	*/
+	getId() {
+		return this._sectionId;
+	}
+	/**
+	* Returns the current zero-based section index.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* console.log(fDocument?.getSection(0)?.getIndex());
+	* ```
+	*/
+	getIndex() {
+		return this._resolve().index;
+	}
+	/**
+	* Returns the section break snapshot that terminates this section.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* console.log(fDocument?.getSection(0)?.getConfig());
+	* ```
+	*/
+	getConfig() {
+		const { sectionBreak } = this._resolve();
+		return Tools.deepClone(sectionBreak);
+	}
+	/**
+	* Returns the section content range, excluding its terminating section-break token.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* console.log(fDocument?.getSection(0)?.getRange());
+	* ```
+	*/
+	getRange() {
+		const sectionBreaks = getTopLevelSectionBreaks(this._document.getBody());
+		const { index, sectionBreak } = this._resolve();
+		return {
+			startOffset: index === 0 ? 0 : sectionBreaks[index - 1].startIndex + 1,
+			endOffset: sectionBreak.startIndex,
+			segmentId: ""
+		};
+	}
+	/**
+	* 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() {
+		var _this$getConfig$colum;
+		return Tools.deepClone((_this$getConfig$colum = this.getConfig().columnProperties) !== null && _this$getConfig$colum !== void 0 ? _this$getConfig$colum : []);
+	}
+	/**
+	* Returns a compact serializable section summary.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* console.log(fDocument?.getSection(0)?.describe());
+	* ```
+	*/
+	describe() {
+		var _config$columnPropert, _config$columnSeparat, _config$sectionType;
+		const config = this.getConfig();
+		const columns = (_config$columnPropert = config.columnProperties) !== null && _config$columnPropert !== void 0 ? _config$columnPropert : [];
+		const headerFooter = {
+			defaultHeader: this._describeHeaderFooterReference("header", "default"),
+			defaultFooter: this._describeHeaderFooterReference("footer", "default"),
+			firstHeader: this._describeHeaderFooterReference("header", "first"),
+			firstFooter: this._describeHeaderFooterReference("footer", "first"),
+			evenHeader: this._describeHeaderFooterReference("header", "even"),
+			evenFooter: this._describeHeaderFooterReference("footer", "even")
+		};
+		return {
+			sectionId: this._sectionId,
+			index: this.getIndex(),
+			range: this.getRange(),
+			columnCount: columns.length || 1,
+			columns: Tools.deepClone(columns),
+			columnSeparatorType: (_config$columnSeparat = config.columnSeparatorType) !== null && _config$columnSeparat !== void 0 ? _config$columnSeparat : ColumnSeparatorType.NONE,
+			sectionType: (_config$sectionType = config.sectionType) !== null && _config$sectionType !== void 0 ? _config$sectionType : SectionType.SECTION_TYPE_UNSPECIFIED,
+			headerFooter,
+			config
+		};
+	}
+	/**
+	* 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, options = {}) {
+		var _options$gap, _options$separator;
+		this._assertTraditionalDocument();
+		if (!Number.isInteger(columnCount) || columnCount < 1) throw new RangeError("Section column count must be a positive integer.");
+		if (options.widths && options.widths.length !== columnCount) throw new RangeError("Section column widths must match the column count.");
+		const gap = Math.max(0, (_options$gap = options.gap) !== null && _options$gap !== void 0 ? _options$gap : 18);
+		const config = this.getConfig();
+		const columns = createSectionColumnProperties(this._document.getDocumentDataModel().getSnapshot().documentStyle, config, columnCount, gap, options.widths);
+		const separator = typeof options.separator === "boolean" ? options.separator ? ColumnSeparatorType.BETWEEN_EACH_COLUMN : ColumnSeparatorType.NONE : (_options$separator = options.separator) !== null && _options$separator !== void 0 ? _options$separator : ColumnSeparatorType.NONE;
+		return this._update({
+			columnProperties: columns,
+			columnSeparatorType: separator,
+			...options.sectionType == null ? {} : { sectionType: options.sectionType }
+		});
+	}
+	/**
+	* 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, separator = ColumnSeparatorType.NONE) {
+		this._assertTraditionalDocument();
+		if (columns.some(({ width, paddingEnd }) => width < 0 || paddingEnd < 0)) throw new RangeError("Section column widths and padding must be non-negative.");
+		return this._update({
+			columnProperties: Tools.deepClone(columns),
+			columnSeparatorType: separator
+		});
+	}
+	/**
+	* 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) {
+		this._assertTraditionalDocument();
+		return this._update({ sectionType });
+	}
+	/**
+	* 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 = "default") {
+		return this._ensureHeaderFooter("header", variant);
+	}
+	/**
+	* 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 = "default") {
+		return this._ensureHeaderFooter("footer", variant);
+	}
+	/**
+	* 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 = "default") {
+		var _this$_getHeaderFoote;
+		return (_this$_getHeaderFoote = this._getHeaderFooterReference("header", variant).segmentId) !== null && _this$_getHeaderFoote !== void 0 ? _this$_getHeaderFoote : 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 = "default") {
+		var _this$_getHeaderFoote2;
+		return (_this$_getHeaderFoote2 = this._getHeaderFooterReference("footer", variant).segmentId) !== null && _this$_getHeaderFoote2 !== void 0 ? _this$_getHeaderFoote2 : 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 = "default") {
+		return this._getHeaderFooterReference("header", variant).linkedToPrevious;
+	}
+	/**
+	* 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 = "default") {
+		return this._getHeaderFooterReference("footer", variant).linkedToPrevious;
+	}
+	/**
+	* 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, variant = "default") {
+		return this._setHeaderFooterLinkedToPrevious("header", variant, linkedToPrevious);
+	}
+	/**
+	* 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, variant = "default") {
+		return this._setHeaderFooterLinkedToPrevious("footer", variant, linkedToPrevious);
+	}
+	/**
+	* 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) {
+		this._assertTraditionalDocument();
+		return this._update(options);
+	}
+	/**
+	* 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() {
+		this._assertTraditionalDocument();
+		return this._injector.get(ICommandService).syncExecuteCommand(DeleteDocumentSectionBreakCommand.id, {
+			unitId: this._document.getId(),
+			sectionId: this._sectionId
+		});
+	}
+	_update(patch) {
+		const { sectionId: _sectionId, startIndex: _startIndex, ...config } = patch;
+		return this._injector.get(ICommandService).syncExecuteCommand(UpdateDocumentSectionCommand.id, {
+			unitId: this._document.getId(),
+			updates: [{
+				sectionId: this._sectionId,
+				config
+			}]
+		});
+	}
+	_ensureHeaderFooter(kind, variant) {
+		this._assertTraditionalDocument();
+		const { index } = this._resolve();
+		const existing = this.getConfig()[getSectionHeaderFooterReferenceKey(kind, variant)];
+		if (typeof existing === "string" && existing) return existing;
+		if (index > 0) {
+			const segmentId = generateRandomId(6);
+			if (!this._injector.get(ICommandService).syncExecuteCommand(SetSectionHeaderFooterLinkCommand.id, {
+				unitId: this._document.getId(),
+				sectionId: this._sectionId,
+				kind,
+				variant,
+				linkedToPrevious: false,
+				segmentId
+			})) throw new Error(`Failed to create section ${kind}.`);
+			return segmentId;
+		}
+		const types = {
+			default: kind === "header" ? HeaderFooterType.DEFAULT_HEADER : HeaderFooterType.DEFAULT_FOOTER,
+			first: kind === "header" ? HeaderFooterType.FIRST_PAGE_HEADER : HeaderFooterType.FIRST_PAGE_FOOTER,
+			even: kind === "header" ? HeaderFooterType.EVEN_PAGE_HEADER : HeaderFooterType.EVEN_PAGE_FOOTER
+		};
+		const segmentId = generateRandomId(6);
+		if (!this._injector.get(ICommandService).syncExecuteCommand(CreateHeaderFooterCommand.id, {
+			unitId: this._document.getId(),
+			segmentId,
+			createType: types[variant],
+			sectionId: this._sectionId
+		})) throw new Error(`Failed to create section ${kind}.`);
+		return segmentId;
+	}
+	_getHeaderFooterReference(kind, variant) {
+		const { index } = this._resolve();
+		return resolveSectionHeaderFooterReference(this._document.getDocumentDataModel().getSnapshot().documentStyle, getTopLevelSectionBreaks(this._document.getBody()), index, getSectionHeaderFooterReferenceKey(kind, variant));
+	}
+	_describeHeaderFooterReference(kind, variant) {
+		var _reference$segmentId;
+		const reference = this._getHeaderFooterReference(kind, variant);
+		return {
+			segmentId: (_reference$segmentId = reference.segmentId) !== null && _reference$segmentId !== void 0 ? _reference$segmentId : null,
+			linkedToPrevious: reference.linkedToPrevious
+		};
+	}
+	_setHeaderFooterLinkedToPrevious(kind, variant, linkedToPrevious) {
+		this._assertTraditionalDocument();
+		return this._injector.get(ICommandService).syncExecuteCommand(SetSectionHeaderFooterLinkCommand.id, {
+			unitId: this._document.getId(),
+			sectionId: this._sectionId,
+			kind,
+			variant,
+			linkedToPrevious,
+			...linkedToPrevious ? {} : { segmentId: generateRandomId(6) }
+		});
+	}
+	_assertTraditionalDocument() {
+		if (this._document.getDocumentDataModel().getSnapshot().documentStyle.documentFlavor !== DocumentFlavor.TRADITIONAL) throw new DocsSectionUnsupportedDocumentFlavorError();
+	}
+	_resolve() {
+		this._assertTraditionalDocument();
+		const sectionBreaks = getTopLevelSectionBreaks(this._document.getBody());
+		const index = sectionBreaks.findIndex((section) => section.sectionId === this._sectionId);
+		if (index < 0) throw new Error(`Document section with id ${this._sectionId} not found.`);
+		return {
+			index,
+			sectionBreak: sectionBreaks[index]
+		};
+	}
+};
+
 //#endregion
 //#region \0@oxc-project+runtime@0.137.0/helpers/esm/typeof.js
 function _typeof(o) {
@@ -629,6 +1230,180 @@ let FDocument = class FDocument extends FBaseInitialable {
 		}, buildPlainTextInsertBody(text), this._documentDataModel, this._injector);
 	}
 	/**
+	* Returns document-level header/footer switches and margins. Margin values are in points (pt).
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* console.log(fDocument?.getHeaderFooterOptions());
+	* ```
+	*/
+	getHeaderFooterOptions() {
+		const style = this._documentDataModel.getSnapshot().documentStyle;
+		return {
+			marginHeader: style.marginHeader,
+			marginFooter: style.marginFooter,
+			useFirstPageHeaderFooter: style.useFirstPageHeaderFooter,
+			evenAndOddHeaders: style.evenAndOddHeaders
+		};
+	}
+	/**
+	* Updates document-level header/footer switches and margins in a traditional document.
+	* `marginHeader` and `marginFooter` are in points (pt).
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* if (fDocument && !fDocument.isModern()) {
+	*   fDocument.setHeaderFooterOptions({ marginHeader: 36, marginFooter: 36 });
+	* }
+	* ```
+	*/
+	setHeaderFooterOptions(options) {
+		if (this.isModern()) throw new Error("The document is a modern document, header/footer is not supported.");
+		return this._commandService.syncExecuteCommand(CreateHeaderFooterCommand.id, {
+			unitId: this.getId(),
+			headerFooterProps: options
+		});
+	}
+	/**
+	* Creates a facade for reading and styling a document text range.
+	* 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.
+	* @returns {FDocumentTextRange} A fixed text-range facade.
+	* @example
+	* ```ts
+	* const range = univerAPI.getActiveDocument()?.getTextRange(0, 5);
+	* console.log(range?.describe());
+	* range?.setTextStyle({ bl: 1 });
+	* ```
+	*/
+	getTextRange(startOffset, endOffset, segmentId = "") {
+		return this._injector.createInstance(FDocumentTextRange, this, startOffset, endOffset, segmentId, this._injector);
+	}
+	/**
+	* Returns traditional document sections backed by persisted SectionBreak ids.
+	* Modern documents use ColumnGroup instead and return an empty array from this read API.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* const sections = fDocument?.getSections() ?? [];
+	* console.log(sections.map((section) => section.describe()));
+	* ```
+	*/
+	getSections() {
+		if (this._documentDataModel.getSnapshot().documentStyle.documentFlavor !== DocumentFlavor.TRADITIONAL) return [];
+		return getTopLevelSectionBreaks(this.getBody()).map((sectionBreak) => this._injector.createInstance(FDocumentSection, this, sectionBreak.sectionId, this._injector));
+	}
+	/**
+	* Returns a traditional section by zero-based index, or `null` in modern documents.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* const firstSection = fDocument?.getSection(0);
+	* console.log(firstSection?.describe());
+	* ```
+	*/
+	getSection(index) {
+		var _this$getSections$ind;
+		return (_this$getSections$ind = this.getSections()[index]) !== null && _this$getSections$ind !== void 0 ? _this$getSections$ind : null;
+	}
+	/**
+	* Returns the traditional section containing a data-stream offset, or `null` in modern documents.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* const paragraph = fDocument?.findParagraphByText('Launch');
+	* const offset = paragraph?.getInfo().startOffset;
+	* const section = offset == null ? null : fDocument?.getSectionAt(offset);
+	* console.log(section?.getId());
+	* ```
+	*/
+	getSectionAt(offset) {
+		var _this$getSections$fin;
+		return (_this$getSections$fin = this.getSections().find((section) => {
+			const range = section.getRange();
+			return offset >= range.startOffset && offset <= range.endOffset;
+		})) !== null && _this$getSections$fin !== void 0 ? _this$getSections$fin : null;
+	}
+	/**
+	* Inserts a traditional document section break and returns its stable facade.
+	* Modern documents must use ColumnGroup and throw `DocsSectionUnsupportedDocumentFlavorError`.
+	* Numeric layout values in `config` are in points (pt).
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* if (fDocument && !fDocument.isModern()) {
+	*   const paragraph = fDocument.findParagraphByText('Appendix');
+	*   const offset = paragraph?.getInfo().startOffset;
+	*   const section = offset == null ? null : fDocument.insertSectionBreak(offset);
+	*   console.log(section?.getId());
+	* }
+	* ```
+	*/
+	insertSectionBreak(offset, config = {}) {
+		var _this$getBody$section;
+		if (this._documentDataModel.getSnapshot().documentStyle.documentFlavor !== DocumentFlavor.TRADITIONAL) throw new DocsSectionUnsupportedDocumentFlavorError();
+		const sectionId = createSectionId(new Set(((_this$getBody$section = this.getBody().sectionBreaks) !== null && _this$getBody$section !== void 0 ? _this$getBody$section : []).map((section) => section.sectionId)));
+		return this._commandService.syncExecuteCommand(InsertDocumentSectionBreakCommand.id, {
+			unitId: this.getId(),
+			offset,
+			sectionId,
+			config
+		}) ? this._injector.createInstance(FDocumentSection, this, sectionId, this._injector) : null;
+	}
+	/**
+	* Inserts a column-break token in a traditional document.
+	* Modern documents must use ColumnGroup and throw `DocsSectionUnsupportedDocumentFlavorError`.
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* if (fDocument && !fDocument.isModern()) {
+	*   const paragraph = fDocument.findParagraphByText('Continue in next column');
+	*   const offset = paragraph?.getInfo().startOffset;
+	*   if (offset != null) {
+	*     fDocument.insertColumnBreak(offset);
+	*   }
+	* }
+	* ```
+	*/
+	insertColumnBreak(offset) {
+		if (this._documentDataModel.getSnapshot().documentStyle.documentFlavor !== DocumentFlavor.TRADITIONAL) throw new DocsSectionUnsupportedDocumentFlavorError();
+		return this.insertText(offset, DataStreamTreeTokenType.COLUMN_BREAK);
+	}
+	/**
+	* 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).
+	* @example
+	* ```ts
+	* const fDocument = univerAPI.getActiveDocument();
+	* const paragraph = fDocument?.findParagraphByText('Summary');
+	* const offset = paragraph?.getInfo().startOffset;
+	* const rule = offset == null ? null : fDocument?.insertHorizontalRule(offset);
+	* console.log(rule?.getId());
+	* ```
+	*/
+	insertHorizontalRule(offset, border = {
+		padding: 5,
+		color: { rgb: "#CDD0D8" },
+		width: 1,
+		dashStyle: DashStyleType.SOLID
+	}, segmentId = "") {
+		var _body$paragraphs;
+		const body = this.getBody(segmentId);
+		const paragraphs = generateParagraphs(DataStreamTreeTokenType.PARAGRAPH, void 0, border, (_body$paragraphs = body.paragraphs) === null || _body$paragraphs === void 0 ? void 0 : _body$paragraphs.map((paragraph) => paragraph.paragraphId));
+		const paragraphId = paragraphs[0].paragraphId;
+		return replaceBodyRange({
+			startOffset: offset,
+			endOffset: offset,
+			segmentId
+		}, {
+			dataStream: DataStreamTreeTokenType.PARAGRAPH,
+			paragraphs
+		}, this._documentDataModel, this._injector) ? this.getParagraph(paragraphId, segmentId) : null;
+	}
+	/**
 	* 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.
 	* @returns {FDocumentParagraph[]} An array of paragraph facade instances.
@@ -748,6 +1523,7 @@ 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.
 	* @returns {FDocumentParagraph} The appended paragraph wrapper.
 	* @example
 	* ```ts
@@ -797,10 +1573,11 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	_getParagraphInsertOffset(index, segmentId = "") {
 		if (index <= 0) return 0;
-		const { dataStream, paragraphs = [] } = this.getBody(segmentId);
+		const body = this.getBody(segmentId);
+		const { dataStream, paragraphs = [] } = body;
 		if (paragraphs.length === 0) return Math.max(0, dataStream.length - 1);
 		if (index >= paragraphs.length) return paragraphs[paragraphs.length - 1].startIndex + 1;
-		return paragraphs[index - 1].startIndex + 1;
+		return getParagraphContentStartOffset(body, paragraphs[index]);
 	}
 	_ensureHeaderFooter(kind, pageIndex) {
 		if (this.isModern()) throw new Error("The document is a modern document, header/footer is not supported.");
@@ -876,4 +1653,31 @@ var FUniverDocsMixin = class extends FUniver {
 FUniver.extend(FUniverDocsMixin);
 
 //#endregion
-export { FDocument, FDocumentParagraph, isParagraphFacade, stripBlockTokens };
+//#region src/facade/f-enum.ts
+/**
+* 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.
+*/
+var FDocsEnumMixin = class extends FEnum {
+	get SectionType() {
+		return SectionType;
+	}
+	get ColumnSeparatorType() {
+		return ColumnSeparatorType;
+	}
+};
+FEnum.extend(FDocsEnumMixin);
+
+//#endregion
+export { DocsSectionUnsupportedDocumentFlavorError, FDocsEnumMixin, FDocument, FDocumentParagraph, FDocumentSection, FDocumentTextRange, isParagraphFacade, stripBlockTokens };