@stll/folio-core 0.3.1 → 0.5.0

package/dist/layout-bridge/convert/toFlowBlocks.js

@@ -5,6 +5,7 @@ import { DEFAULT_TEXTBOX_MARGINS } from "../../layout-engine/types.js";
 import { resolveColor, resolveHighlightToCss } from "../../utils/colorResolver.js";
 import { resolveShadingFill } from "../../utils/formatToStyle.js";
 import { convertBulletToUnicode } from "../../docx/bulletMarkers.js";
+import { setTextBoxGroupId } from "../../layout-engine/textBoxGroup.js";
 import { directionIsRtl } from "../../prosemirror/paragraphDirection.js";
 import { expectBlockSdtAttrs, expectCharacterSpacingMarkAttrs, expectCommentMarkAttrs, expectEmphasisMarkAttrs, expectFieldAttrs, expectFontFamilyMarkAttrs, expectFontSizeMarkAttrs, expectFootnoteRefMarkAttrs, expectHighlightMarkAttrs, expectHyperlinkMarkAttrs, expectImageAttrs, expectMathAttrs, expectParagraphAttrs, expectRunFormattingOverrideMarkAttrs, expectRunShadingMarkAttrs, expectTableAttrs, expectTableCellAttrs, expectTableRowAttrs, expectTextBoxAttrs, expectTextColorMarkAttrs, expectTextEffectMarkAttrs, expectTrackedChangeMarkAttrs, expectUnderlineMarkAttrs } from "../../prosemirror/attrs/index.js";
 import { autospacingMatchesBase } from "../../prosemirror/autospacingBase.js";
@@ -100,7 +101,7 @@ function toLetter(value, upper) {
 	return String.fromCodePoint(baseCodePoint + zeroBased % 26).repeat(Math.floor(zeroBased / 26) + 1);
 }
 function formatCounter(value, format) {
-	if (value <= 0) return "";
+	if (!Number.isFinite(value)) return "";
 	switch (format) {
 		case "upperRoman": return toRoman(value, true);
 		case "lowerRoman": return toRoman(value, false);
@@ -119,7 +120,9 @@ function resolveListTemplate(template, counters, levelFormats, forceDecimal = fa
 		const { digit, punct = "" } = args.at(-1);
 		const index = Number.parseInt(digit, 10) - 1;
 		if (index < 0) return "";
-		const formatted = formatCounter(counters[index] ?? 0, forceDecimal ? "decimal" : levelFormats?.[index]);
+		const counter = counters[index];
+		if (counter === void 0 || Number.isNaN(counter)) return "";
+		const formatted = formatCounter(counter, forceDecimal ? "decimal" : levelFormats?.[index]);
 		return formatted ? `${formatted}${punct}` : "";
 	});
 }
@@ -143,22 +146,28 @@ function computeListMarker(pmAttrs, listCounters, abstractCounters, seenNumIds)
 	}
 	if (pmAttrs.listIsBullet) return convertBulletToUnicode(pmAttrs.listMarker || "");
 	const level = pmAttrs.numPr?.ilvl ?? 0;
-	const counters = listCounters.get(numId) ?? Array.from({ length: 9 }, () => 0);
+	const counters = listCounters.get(numId) ?? Array.from({ length: 9 }, () => NaN);
 	const abstractNumId = pmAttrs.listAbstractNumId;
-	if (abstractNumId !== void 0 && level > 0) {
-		const latestAbstractCounters = abstractCounters.get(abstractNumId);
-		const missingParentCounters = counters.slice(0, level).every((value) => value === 0);
-		if (latestAbstractCounters && missingParentCounters) for (let i = 0; i < level; i += 1) counters[i] = latestAbstractCounters[i] ?? 0;
+	if (level > 0) {
+		const latestAbstractCounters = abstractNumId === void 0 ? void 0 : abstractCounters.get(abstractNumId);
+		if (counters.slice(0, level).every(Number.isNaN)) for (let i = 0; i < level; i += 1) {
+			const latestCounter = latestAbstractCounters?.[i];
+			counters[i] = latestCounter !== void 0 && !Number.isNaN(latestCounter) ? latestCounter : pmAttrs.listLevelStarts?.[i] ?? 1;
+		}
 	}
 	const seenKey = `${numId}:${level}`;
 	if (!seenNumIds.has(seenKey)) {
 		seenNumIds.add(seenKey);
 		if (pmAttrs.listStartOverride != null) counters[level] = pmAttrs.listStartOverride - 1;
+		else if (Number.isNaN(counters[level])) counters[level] = (pmAttrs.listLevelStarts?.[level] ?? 1) - 1;
 	}
 	counters[level] = (counters[level] ?? 0) + 1;
-	for (let i = level + 1; i < counters.length; i += 1) counters[i] = 0;
+	for (let i = level + 1; i < counters.length; i += 1) counters[i] = NaN;
 	const childAdvances = pmAttrs.listImplicitChildLevelAdvances ?? 0;
-	if (childAdvances > 0 && level + 1 < counters.length) counters[level + 1] = (counters[level + 1] ?? 0) + childAdvances;
+	if (childAdvances > 0 && level + 1 < counters.length) {
+		const childCounter = counters[level + 1];
+		counters[level + 1] = (childCounter === void 0 || Number.isNaN(childCounter) ? 0 : childCounter) + childAdvances;
+	}
 	listCounters.set(numId, counters);
 	if (abstractNumId !== void 0) abstractCounters.set(abstractNumId, [...counters]);
 	const levelFormats = pmAttrs.listLevelNumFmts ?? (pmAttrs.listNumFmt ? [pmAttrs.listNumFmt] : void 0);
@@ -234,7 +243,7 @@ function extractRunFormatting(marks, theme) {
 		}
 		case "characterSpacing": {
 			const attrs = expectCharacterSpacingMarkAttrs(mark);
-			if (attrs.spacing !== void 0 && attrs.spacing !== 0) formatting.letterSpacing = twipsToPixels(attrs.spacing);
+			if (attrs.spacing !== void 0) formatting.letterSpacing = twipsToPixels(attrs.spacing);
 			if (attrs.position !== void 0 && attrs.position !== 0) formatting.positionPx = halfPointsToPixels(attrs.position);
 			if (attrs.scale !== void 0 && attrs.scale !== 100) formatting.horizontalScale = attrs.scale;
 			if (attrs.kerning !== void 0 && attrs.kerning > 0) formatting.kerningMinPt = halfPointsToPoints(attrs.kerning);
@@ -336,10 +345,12 @@ function markDefaultBlackTextColorSource(formatting, paraDefaults) {
 	};
 }
 function mergeRunFormatting(paraDefaults, formatting) {
-	return {
+	const merged = {
 		...paraDefaults,
 		...markDefaultBlackTextColorSource(formatting, paraDefaults)
 	};
+	if (merged.letterSpacing === 0) delete merged.letterSpacing;
+	return merged;
 }
 function applyRunFormattingOverrides(formatting, attrs) {
 	if (attrs.bold === false) formatting.bold = false;
@@ -485,9 +496,10 @@ function paragraphToRuns(node, startPos, _options) {
 			return;
 		}
 		if (child.type.name === "tab") {
+			const formatting = extractRunFormatting(child.marks, theme);
 			const run = {
 				kind: "tab",
-				...mergeRunFormatting(paraDefaults, extractRunFormatting(child.marks, theme)),
+				...mergeRunFormatting(paraDefaults, formatting),
 				pmStart: childPos,
 				pmEnd: childPos + child.nodeSize
 			};
@@ -496,7 +508,8 @@ function paragraphToRuns(node, startPos, _options) {
 		}
 		if (child.type.name === "image") {
 			const attrs = expectImageAttrs(child);
-			const constrained = constrainImageToPage(attrs.width || 100, attrs.height || 100, _options.pageContentHeight);
+			if (!attrs.src) return;
+			const constrained = constrainImageToPage(attrs.width ?? 100, attrs.height ?? 100, _options.pageContentHeight);
 			const trackedFmt = extractRunFormatting(child.marks, theme);
 			const run = buildImageRun(attrs, constrained, childPos, childPos + child.nodeSize, trackedFmt);
 			runs.push(run);
@@ -613,6 +626,8 @@ function toPreviousListAttrs(previousFormatting) {
 	if (isNumberFormat(listNumFmt)) attrs.listNumFmt = listNumFmt;
 	const listLevelNumFmts = readNumberFormats(previousFormatting["listLevelNumFmts"]);
 	if (listLevelNumFmts) attrs.listLevelNumFmts = listLevelNumFmts;
+	const listLevelStarts = previousFormatting["listLevelStarts"];
+	if (Array.isArray(listLevelStarts) && listLevelStarts.every((value) => typeof value === "number")) attrs.listLevelStarts = listLevelStarts;
 	const listAbstractNumId = previousFormatting["listAbstractNumId"];
 	if (typeof listAbstractNumId === "number") attrs.listAbstractNumId = listAbstractNumId;
 	const listStartOverride = previousFormatting["listStartOverride"];
@@ -669,9 +684,10 @@ function convertParagraphAttrs(pmAttrs, theme, listCounters, listAbstractCounter
 		if (autoAfter) attrs.spacing.after = 14;
 		else if (typeof spaceAfter === "number") attrs.spacing.after = twipsToPixels(spaceAfter);
 		const pmSpacingExplicit = pmAttrs.spacingExplicit;
+		const spacingFromDocDefaults = pmAttrs.spacingFromDocDefaults;
 		const explicit = {};
-		if (autoBefore || pmSpacingExplicit?.before) explicit.before = true;
-		if (autoAfter || pmSpacingExplicit?.after) explicit.after = true;
+		if (autoBefore || pmSpacingExplicit?.before || spacingFromDocDefaults?.before) explicit.before = true;
+		if (autoAfter || pmSpacingExplicit?.after || spacingFromDocDefaults?.after) explicit.after = true;
 		if (explicit.before !== void 0 || explicit.after !== void 0) attrs.spacingExplicit = explicit;
 		if (typeof lineSpacing === "number") if (pmAttrs.lineSpacingRule === "exact" || pmAttrs.lineSpacingRule === "atLeast") {
 			attrs.spacing.line = twipsToPixels(lineSpacing);
@@ -730,8 +746,10 @@ function convertParagraphAttrs(pmAttrs, theme, listCounters, listAbstractCounter
 		return tabStop;
 	});
 	if (pmAttrs.pageBreakBefore) attrs.pageBreakBefore = true;
+	if (pmAttrs.renderedPageBreakBefore) attrs.renderedPageBreakBefore = true;
 	if (pmAttrs.keepNext) attrs.keepNext = true;
 	if (pmAttrs.keepLines) attrs.keepLines = true;
+	if (pmAttrs.widowControl === false) attrs.widowControl = false;
 	if (pmAttrs.contextualSpacing) attrs.contextualSpacing = true;
 	if (pmAttrs.runInWithNext) attrs.runInWithNext = true;
 	if (directionIsRtl(pmAttrs.direction)) attrs.bidi = true;
@@ -808,6 +826,17 @@ function convertParagraph(node, startPos, options) {
 	const pmAttrs = expectParagraphAttrs(node);
 	const runs = paragraphToRuns(node, startPos, options);
 	const attrs = convertParagraphAttrs(pmAttrs, options.theme, options.listCounters, options.listAbstractCounters, options.listSeenNumIds, options.defaultTabStopTwips, options.originalListCounters, options.originalListAbstractCounters, options.originalListSeenNumIds);
+	const defaultTextFormatting = pmAttrs.defaultTextFormatting;
+	if (runs.length === 0) {
+		const paragraphMarkFormatting = pmAttrs._originalFormatting?.runProperties;
+		if (paragraphMarkFormatting?.fontSize !== void 0) attrs.defaultFontSize = paragraphMarkFormatting.fontSize / 2;
+		const paragraphMarkFontFamily = paragraphMarkFormatting?.fontFamily?.ascii ?? paragraphMarkFormatting?.fontFamily?.hAnsi;
+		if (paragraphMarkFontFamily) attrs.defaultFontFamily = paragraphMarkFontFamily;
+	}
+	if (runs.length === 0 && defaultTextFormatting?.hidden === true) {
+		attrs.suppressEmptyParagraphHeight = true;
+		if (attrs.listMarker !== void 0) attrs.listMarkerHidden = true;
+	}
 	const bookmarkNames = pmAttrs.bookmarks?.map((b) => b.name);
 	return {
 		kind: "paragraph",
@@ -892,6 +921,11 @@ function convertTableCell(node, startPos, options, tableCellMargins) {
 		} else if (child.type.name === "table") blocks.push(convertTable(child, offset, options));
 		offset += child.nodeSize;
 	});
+	const trailingBlock = blocks.at(-1);
+	if (blocks.length > 1 && trailingBlock?.kind === "paragraph" && trailingBlock.runs.every((run) => run.kind === "text" && run.text.length === 0)) trailingBlock.attrs = {
+		...trailingBlock.attrs,
+		suppressEmptyParagraphHeight: true
+	};
 	const attrs = expectTableCellAttrs(node);
 	const margins = attrs.margins;
 	const resolvePaddingSide = (side, cellTwips, tableTwips) => {
@@ -941,6 +975,7 @@ function convertTableRow(node, startPos, options, tableCellMargins) {
 	if (attrs.height) row.height = twipsToPixels(attrs.height);
 	if (attrs.heightRule) row.heightRule = attrs.heightRule;
 	if (attrs.isHeader) row.isHeader = attrs.isHeader;
+	if (attrs.hidden) row.hidden = attrs.hidden;
 	return row;
 }
 /**
@@ -991,6 +1026,7 @@ function convertTable(node, startPos, options) {
 	if (columnWidths) tableBlock.columnWidths = columnWidths;
 	if (width !== void 0) tableBlock.width = width;
 	if (widthType !== void 0) tableBlock.widthType = widthType;
+	if (originalFormatting?.layout !== void 0) tableBlock.layout = originalFormatting.layout;
 	if (justification) tableBlock.justification = justification;
 	if (indentPx !== void 0) tableBlock.indent = indentPx;
 	if (floatingPx) tableBlock.floating = floatingPx;
@@ -1004,7 +1040,7 @@ function convertImage(node, startPos, pageContentHeight) {
 	const attrs = expectImageAttrs(node);
 	const wrapType = attrs.wrapType;
 	const shouldAnchor = wrapType === "behind" || wrapType === "inFront";
-	const constrained = constrainImageToPage(attrs.width || 100, attrs.height || 100, pageContentHeight);
+	const constrained = constrainImageToPage(attrs.width ?? 100, attrs.height ?? 100, pageContentHeight);
 	const imgBlock = {
 		kind: "image",
 		id: nextBlockId(),
@@ -1073,6 +1109,7 @@ function convertTextBoxNode(node, startPos, opts) {
 	if (attrs.distLeft !== void 0) textBox.distLeft = attrs.distLeft;
 	if (attrs.distRight !== void 0) textBox.distRight = attrs.distRight;
 	if (attrs.position !== void 0) textBox.position = attrs.position;
+	if (attrs._docxGroupId !== void 0) setTextBoxGroupId(textBox, attrs._docxGroupId);
 	return textBox;
 }
 /**
@@ -1233,14 +1270,16 @@ function toFlowBlocks(doc, options = {}) {
 				trackedPush(convertTextBoxNode(node, pos, opts));
 				break;
 			case "horizontalRule":
-			case "pageBreak":
-				trackedPush({
+			case "pageBreak": {
+				const pb = {
 					kind: "pageBreak",
 					id: nextBlockId(),
 					pmStart: pos,
 					pmEnd: pos + node.nodeSize
-				});
+				};
+				trackedPush(pb);
 				break;
+			}
 			default: break;
 		}
 	};

package/dist/layout-engine/index.d.ts

@@ -1,4 +1,4 @@
-import { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun } from "./types.js";
+import { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, tableColumnsArePinned } from "./types.js";
 import { PageState, Paginator, PaginatorOptions, createPaginator } from "./paginator.js";
 import { KeepNextChain, calculateChainHeight, computeKeepNextChains, getMidChainIndices, hasKeepLines, hasPageBreakBefore } from "./keep-together.js";
 import { BreakDecision, SectionState, applyPendingToActive, createInitialSectionState, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, scheduleSectionBreak } from "./section-breaks.js";
@@ -20,9 +20,10 @@ declare function collectSectionConfigs(blocks: FlowBlock[], initialConfig: Secti
 /**
  * Apply contextual spacing suppression (OOXML §17.3.1.9).
  *
- * When two consecutive paragraph blocks both have `contextualSpacing: true`
- * and share the same `styleId`, the spaceAfter of the first paragraph and
- * the spaceBefore of the second paragraph are suppressed (set to 0).
+ * Contextual spacing applies independently to each paragraph: suppress the
+ * current paragraph's spaceAfter when it opts in, and the next paragraph's
+ * spaceBefore when it opts in, provided both paragraphs share a style. Two
+ * absent style ids both refer to the document's default paragraph style.
  *
  * This mutates the block attrs in-place before layout runs.
  */
@@ -42,4 +43,4 @@ declare function layoutDocument(blocks: FlowBlock[], measures: Measure[], option
  */
 declare function getHeaderRowsHeight(measure: TableMeasure, headerRowCount: number): number;
 //#endregion
-export { BlockId, BorderStyle, type BreakDecision, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, type KeepNextChain, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, type PageState, type Paginator, type PaginatorOptions, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionLayoutConfig, type SectionState, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, applyContextualSpacing, applyPendingToActive, assertExhaustiveFlowBlock, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak };
+export { BlockId, BorderStyle, type BreakDecision, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, type KeepNextChain, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, type PageState, type Paginator, type PaginatorOptions, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionLayoutConfig, type SectionState, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, applyContextualSpacing, applyPendingToActive, assertExhaustiveFlowBlock, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak, tableColumnsArePinned };

package/dist/layout-engine/index.js

@@ -1,5 +1,6 @@
+import { emuToPixels } from "../utils/units.js";
 import { measuredLineAdvance } from "./lineFlow.js";
-import { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun } from "./types.js";
+import { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, tableColumnsArePinned } from "./types.js";
 import { calculateChainHeight, computeKeepNextChains, getMidChainIndices, hasKeepLines, hasPageBreakBefore } from "./keep-together.js";
 import { createPaginator } from "./paginator.js";
 import { getParagraphFragmentPmRange } from "./paragraphFragmentRange.js";
@@ -51,33 +52,54 @@ function isEmptyParagraph(block) {
 	if (block.runs.length === 0) return true;
 	if (block.runs.length !== 1) return false;
 	const r = block.runs[0];
-	return r?.kind === "text" && (r.text ?? "") === "";
+	return r?.kind === "text" && r.text === "";
+}
+function isPaginationEmptyParagraph(block) {
+	return block.runs.every((run) => {
+		if (run.kind === "text") return run.text.trim().length === 0;
+		return run.kind === "tab" || run.kind === "lineBreak";
+	});
+}
+function pageHasVisibleBodyContent(page, blocksById) {
+	for (const fragment of page.fragments) {
+		if (fragment.kind !== "paragraph") return true;
+		const block = blocksById.get(String(fragment.blockId));
+		if (block?.kind !== "paragraph" || !isPaginationEmptyParagraph(block)) return true;
+	}
+	return false;
 }
 /**
 * Get spacing before a paragraph block. Empty paragraphs whose
-* `before` was inherited from a paragraph style (not set inline) collapse
-* to zero — Word fidelity for incidental empty separators.
+* `before` came only from the implicit default paragraph style collapse to
+* zero. An explicit `w:pStyle` selection is authored paragraph formatting,
+* so Word keeps the selected style's spacing even when the paragraph is empty.
 */
 function getSpacingBefore(block) {
 	const value = block.attrs?.spacing?.before ?? 0;
-	if (isEmptyParagraph(block) && !block.attrs?.spacingExplicit?.before) return 0;
+	if (value === 0) return 0;
+	if (isEmptyParagraph(block) && !block.attrs?.styleId && !block.attrs?.spacingExplicit?.before) return 0;
 	return value;
 }
 /**
-* Get spacing after a paragraph block. Same empty-paragraph collapse rule
-* as `getSpacingBefore`.
+* Get spacing after a paragraph block. Same implicit-default-style collapse
+* rule as `getSpacingBefore`.
 */
 function getSpacingAfter(block) {
 	const value = block.attrs?.spacing?.after ?? 0;
-	if (isEmptyParagraph(block) && !block.attrs?.spacingExplicit?.after) return 0;
+	if (value === 0) return 0;
+	if (isEmptyParagraph(block) && !block.attrs?.styleId && !block.attrs?.spacingExplicit?.after) return 0;
 	return value;
 }
+function hasWidowControl(block) {
+	return block.attrs?.widowControl !== false;
+}
 /**
 * Apply contextual spacing suppression (OOXML §17.3.1.9).
 *
-* When two consecutive paragraph blocks both have `contextualSpacing: true`
-* and share the same `styleId`, the spaceAfter of the first paragraph and
-* the spaceBefore of the second paragraph are suppressed (set to 0).
+* Contextual spacing applies independently to each paragraph: suppress the
+* current paragraph's spaceAfter when it opts in, and the next paragraph's
+* spaceBefore when it opts in, provided both paragraphs share a style. Two
+* absent style ids both refer to the document's default paragraph style.
 *
 * This mutates the block attrs in-place before layout runs.
 */
@@ -88,16 +110,15 @@ function applyContextualSpacing(blocks) {
 		if (curr.kind !== "paragraph" || next.kind !== "paragraph") continue;
 		const currAttrs = curr.attrs;
 		const nextAttrs = next.attrs;
-		if (currAttrs?.contextualSpacing && nextAttrs?.contextualSpacing && currAttrs.styleId && currAttrs.styleId === nextAttrs.styleId) {
-			if (currAttrs.spacing) currAttrs.spacing = {
-				...currAttrs.spacing,
-				after: 0
-			};
-			if (nextAttrs.spacing) nextAttrs.spacing = {
-				...nextAttrs.spacing,
-				before: 0
-			};
-		}
+		if (currAttrs?.styleId !== nextAttrs?.styleId) continue;
+		if (currAttrs?.contextualSpacing && currAttrs.spacing) currAttrs.spacing = {
+			...currAttrs.spacing,
+			after: 0
+		};
+		if (nextAttrs?.contextualSpacing && nextAttrs.spacing) nextAttrs.spacing = {
+			...nextAttrs.spacing,
+			before: 0
+		};
 	}
 	for (const block of blocks) if (block.kind === "table") for (const row of block.rows) for (const cell of row.cells) applyContextualSpacing(cell.blocks);
 	else if (block.kind === "textBox") applyContextualSpacing(block.content);
@@ -142,6 +163,7 @@ function layoutDocument(blocks, measures, options) {
 	const paginator = createPaginator({
 		pageSize: initialConfig.pageSize,
 		margins: initialConfig.margins,
+		...options.mirrorMargins === true ? { mirrorMargins: true } : {},
 		...options.firstPageMargins !== void 0 ? { firstPageMargins: options.firstPageMargins } : {},
 		columns: initialConfig.columns ?? DEFAULT_COLUMNS,
 		...options.footnoteReservedHeights !== void 0 ? { footnoteReservedHeights: options.footnoteReservedHeights } : {},
@@ -150,21 +172,29 @@ function layoutDocument(blocks, measures, options) {
 	applyContextualSpacing(blocks);
 	const keepNextChains = computeKeepNextChains(blocks);
 	const midChainIndices = getMidChainIndices(keepNextChains);
+	const blocksById = /* @__PURE__ */ new Map();
+	for (const block of blocks) blocksById.set(String(block.id), block);
 	let sectionIdx = 0;
 	let activeSectionMarginTop = initialConfig.margins.top;
 	let activeSectionPageHeight = initialConfig.pageSize.h;
 	let activeSectionMarginBottom = initialConfig.margins.bottom;
+	let naturalPageAdvanceSinceRenderedBreak = false;
 	for (let i = 0; i < blocks.length; i++) {
 		const block = blocks[i];
 		const measure = measures[i];
+		const hasRenderedPageBreak = block.kind === "paragraph" && block.attrs?.renderedPageBreakBefore === true;
 		if (hasPageBreakBefore(block)) paginator.forcePageBreak();
+		else if (hasRenderedPageBreak) {
+			const state = paginator.getCurrentState();
+			if (!(block.kind === "paragraph" && isPaginationEmptyParagraph(block) && naturalPageAdvanceSinceRenderedBreak) && pageHasVisibleBodyContent(state.page, blocksById)) paginator.forcePageBreak();
+		}
+		if (hasRenderedPageBreak || hasPageBreakBefore(block)) naturalPageAdvanceSinceRenderedBreak = false;
 		const chain = keepNextChains.get(i);
 		if (chain && !midChainIndices.has(i)) {
 			const chainHeight = calculateChainHeight(chain, blocks, measures);
-			const state = paginator.getCurrentState();
-			const availableHeight = paginator.getAvailableHeight();
-			if (chainHeight <= state.contentBottom - state.topMargin && chainHeight > availableHeight && state.page.fragments.length > 0) paginator.forcePageBreak();
+			paginator.ensureFits(chainHeight);
 		}
+		const pageBeforeBlockLayout = paginator.getCurrentState().page.number;
 		switch (block.kind) {
 			case "paragraph":
 				layoutParagraph(block, measure, paginator, paginator.getContentWidth(), options.footnoteHeightById);
@@ -201,6 +231,9 @@ function layoutDocument(blocks, measures, options) {
 			}
 			default: break;
 		}
+		const isVisibleBodyBlock = block.kind === "paragraph" ? !isEmptyParagraph(block) : block.kind !== "pageBreak" && block.kind !== "columnBreak" && block.kind !== "sectionBreak";
+		if (block.kind === "pageBreak" || block.kind === "columnBreak" || block.kind === "sectionBreak") naturalPageAdvanceSinceRenderedBreak = false;
+		else if (isVisibleBodyBlock && paginator.getCurrentState().page.number > pageBeforeBlockLayout) naturalPageAdvanceSinceRenderedBreak = true;
 	}
 	if (paginator.pages.length === 0) paginator.getCurrentState();
 	return {
@@ -309,6 +342,28 @@ function layoutParagraph(block, measure, paginator, contentWidth, footnoteHeight
 				fittingLines++;
 			} else break;
 		}
+		let forceBreakAfterFragment = false;
+		if (hasWidowControl(block)) {
+			const remainingAfter = lines.length - (currentLineIndex + fittingLines);
+			if (fittingLines > 1 && remainingAfter === 1) {
+				if (currentLineIndex === 0 && fittingLines === 2 && state.cursorY !== state.topMargin) {
+					paginator.forceColumnBreak();
+					continue;
+				}
+				fittingLines -= 1;
+				forceBreakAfterFragment = true;
+				linesHeight = 0;
+				linesFnHeight = 0;
+				linesFnIds.length = 0;
+				for (let j = currentLineIndex; j < currentLineIndex + fittingLines; j++) {
+					const line = lines[j];
+					linesHeight += measuredLineAdvance(line);
+					const lineRefs = getLineFootnoteRefs(block, line.fromRun, line.toRun, footnoteHeightById);
+					linesFnHeight += lineRefs.height;
+					for (const id of lineRefs.ids) linesFnIds.push(id);
+				}
+			}
+		}
 		const isFirstFragment = currentLineIndex === 0;
 		const isLastFragment = currentLineIndex + fittingLines >= lines.length;
 		const effectiveSpaceBefore = isFirstFragment ? spaceBefore : 0;
@@ -336,7 +391,8 @@ function layoutParagraph(block, measure, paginator, contentWidth, footnoteHeight
 		fragment.y = paginator.addFragment(fragment, linesHeight, effectiveSpaceBefore, effectiveSpaceAfter).y;
 		if (linesFnHeight > 0) paginator.addFootnoteHeight(linesFnHeight, linesFnIds);
 		currentLineIndex += fittingLines;
-		if (currentLineIndex < lines.length) paginator.ensureFits(measuredLineAdvance(lines[currentLineIndex]));
+		if (currentLineIndex < lines.length) if (forceBreakAfterFragment) paginator.forceColumnBreak();
+		else paginator.ensureFits(measuredLineAdvance(lines[currentLineIndex]));
 	}
 }
 /**
@@ -371,7 +427,10 @@ function layoutTable(block, measure, paginator) {
 		let x = paginator.getColumnX(columnIndex);
 		if (block.justification === "center") x += (paginator.columnWidth - measure.totalWidth) / 2;
 		else if (block.justification === "right") x = x + paginator.columnWidth - measure.totalWidth;
-		else if (block.indent) x += block.indent;
+		else if (block.indent !== void 0) {
+			const leadingCellMargin = block.rows[0]?.cells[0]?.padding?.left ?? 0;
+			x += block.indent - leadingCellMargin;
+		}
 		return x;
 	};
 	const getCurrentRowCapacity = (state = paginator.getCurrentState()) => state.rawContentBottom - state.topMargin;
@@ -505,6 +564,7 @@ function layoutFloatingTable(block, measure, paginator, contentWidth) {
 	let baseY = margins.top;
 	if (floating?.horzAnchor === "page") baseX = 0;
 	if (floating?.vertAnchor === "page") baseY = 0;
+	else if (floating?.vertAnchor === "text") baseY = state.cursorY;
 	let x = paginator.getColumnX(state.columnIndex);
 	if (floating?.tblpX !== void 0) x = baseX + floating.tblpX;
 	else if (floating?.tblpXSpec) {
@@ -623,6 +683,35 @@ function layoutTextBox(block, measure, { paginator, sectionMarginTop, sectionPag
 		state.page.fragments.push(fragment);
 		return;
 	}
+	if (block.position !== void 0) {
+		const state = paginator.getCurrentState();
+		const horizontal = block.position.horizontal;
+		const x = horizontal ? bandFragmentX(horizontal, {
+			pageWidth: state.page.size.w,
+			marginLeft: state.page.margins.left,
+			marginRight: state.page.margins.right,
+			boxWidth: measure.width
+		}) : paginator.getColumnX(state.columnIndex);
+		const vertical = block.position.vertical;
+		const y = isPageFrameRelativeAnchor(vertical?.relativeTo) ? state.topMargin + bandTopContentY(vertical, {
+			pageHeight: sectionPageHeight,
+			marginTop: sectionMarginTop,
+			marginBottom: sectionMarginBottom,
+			boxHeight: measure.height
+		}) : state.cursorY + emuToPixels(vertical?.posOffset ?? 0);
+		const fragment = {
+			kind: "textBox",
+			blockId: block.id,
+			x,
+			y,
+			width: measure.width,
+			height: measure.height,
+			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {}
+		};
+		state.page.fragments.push(fragment);
+		return;
+	}
 	const state = paginator.ensureFits(measure.height);
 	const fragment = {
 		kind: "textBox",
@@ -689,4 +778,4 @@ function handleSectionBreak(_block, paginator, nextSectionConfig, nextSectionTyp
 	paginator.updateColumns(nextSectionConfig.columns ?? DEFAULT_COLUMNS);
 }
 //#endregion
-export { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, applyContextualSpacing, applyPendingToActive, assertExhaustiveFlowBlock, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak };
+export { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, applyContextualSpacing, applyPendingToActive, assertExhaustiveFlowBlock, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak, tableColumnsArePinned };

package/dist/layout-engine/keep-together.d.ts

@@ -2,28 +2,33 @@ import { FlowBlock, Measure } from "./types.js";
 
 //#region src/layout-engine/keep-together.d.ts
 /**
- * A chain of consecutive keepNext paragraphs.
+ * A chain of keepNext-linked paragraphs, including empty separators Word
+ * carries through to the next paragraph with visible content.
  */
 type KeepNextChain = {
-  /** Index of the first paragraph in the chain. */startIndex: number; /** Index of the last paragraph in the chain. */
-  endIndex: number; /** All paragraph indices in the chain. */
+  /** Index of the first paragraph in the chain. */startIndex: number; /** Index of the last keepNext or pass-through empty member. */
+  endIndex: number; /** All keepNext and pass-through empty paragraph indices in the chain. */
   memberIndices: number[]; /** Index of the anchor paragraph (first non-keepNext after chain), or -1 if none. */
   anchorIndex: number;
 };
 /**
  * Pre-scan blocks to find all keepNext chains.
  *
- * A keepNext chain is a sequence of consecutive paragraphs with keepNext=true,
- * followed by an anchor paragraph (the first non-keepNext paragraph).
- * The entire chain must stay on the same page as the anchor's first line.
+ * A keepNext chain starts with a paragraph whose keepNext=true and continues
+ * through further keepNext paragraphs and structural empty separators. The
+ * first visible non-keepNext paragraph is its anchor.
  *
  * Returns a map from chain start index to chain info.
  */
 declare function computeKeepNextChains(blocks: FlowBlock[]): Map<number, KeepNextChain>;
 /**
- * Calculate the total height needed to keep a chain together.
+ * Calculate the height needed to keep consecutive paragraph boundaries from
+ * breaking across pages.
  *
- * Includes all chain members plus the first line of the anchor paragraph.
+ * Single-line and `keepLines` members are indivisible, so the reservation must
+ * continue through them to the anchor's first line. A multi-line member without
+ * `keepLines` may itself split; only its first line is needed to satisfy the
+ * preceding member's `keepNext`, and the chain can stop there.
  */
 declare function calculateChainHeight(chain: KeepNextChain, blocks: FlowBlock[], measures: Measure[]): number;
 /**

package/dist/layout-engine/keep-together.js

@@ -1,10 +1,16 @@
 //#region src/layout-engine/keep-together.ts
+function isVisuallyEmptyParagraph(block) {
+	if (block.runs.length === 0) return true;
+	if (block.runs.length !== 1) return false;
+	const run = block.runs.at(0);
+	return run?.kind === "text" && run.text === "";
+}
 /**
 * Pre-scan blocks to find all keepNext chains.
 *
-* A keepNext chain is a sequence of consecutive paragraphs with keepNext=true,
-* followed by an anchor paragraph (the first non-keepNext paragraph).
-* The entire chain must stay on the same page as the anchor's first line.
+* A keepNext chain starts with a paragraph whose keepNext=true and continues
+* through further keepNext paragraphs and structural empty separators. The
+* first visible non-keepNext paragraph is its anchor.
 *
 * Returns a map from chain start index to chain info.
 */
@@ -22,7 +28,8 @@ function computeKeepNextChains(blocks) {
 			const nextBlock = blocks[j];
 			if (nextBlock.kind === "sectionBreak" || nextBlock.kind === "pageBreak" || nextBlock.kind === "columnBreak") break;
 			if (nextBlock.kind !== "paragraph") break;
-			if (nextBlock.attrs?.keepNext) {
+			const nextPara = nextBlock;
+			if (nextPara.attrs?.keepNext || isVisuallyEmptyParagraph(nextPara)) {
 				memberIndices.push(j);
 				endIndex = j;
 				processed.add(j);
@@ -44,30 +51,38 @@ function computeKeepNextChains(blocks) {
 	return chains;
 }
 /**
-* Calculate the total height needed to keep a chain together.
+* Calculate the height needed to keep consecutive paragraph boundaries from
+* breaking across pages.
 *
-* Includes all chain members plus the first line of the anchor paragraph.
+* Single-line and `keepLines` members are indivisible, so the reservation must
+* continue through them to the anchor's first line. A multi-line member without
+* `keepLines` may itself split; only its first line is needed to satisfy the
+* preceding member's `keepNext`, and the chain can stop there.
 */
 function calculateChainHeight(chain, blocks, measures) {
-	let totalHeight = 0;
-	for (const memberIndex of chain.memberIndices) {
-		const block = blocks[memberIndex];
-		const measure = measures[memberIndex];
-		if (!block || !measure || block.kind !== "paragraph" || measure.kind !== "paragraph") continue;
-		const para = block;
-		const paraMeasure = measure;
-		const spacingBefore = para.attrs?.spacing?.before ?? 0;
-		totalHeight += spacingBefore;
-		totalHeight += paraMeasure.totalHeight;
-		const spacingAfter = para.attrs?.spacing?.after ?? 0;
-		totalHeight += spacingAfter;
-	}
-	if (chain.anchorIndex !== -1) {
-		const anchorMeasure = measures[chain.anchorIndex];
-		if (anchorMeasure?.kind === "paragraph") {
-			const anchorPara = anchorMeasure;
-			if (anchorPara.lines.length > 0) totalHeight += anchorPara.lines[0].lineHeight;
-		}
+	const firstMemberIndex = chain.memberIndices.at(0);
+	if (firstMemberIndex === void 0) return 0;
+	const firstBlock = blocks[firstMemberIndex];
+	const firstMeasure = measures[firstMemberIndex];
+	if (firstBlock?.kind !== "paragraph" || firstMeasure?.kind !== "paragraph") return 0;
+	let totalHeight = (firstBlock.attrs?.spacing?.before ?? 0) + firstMeasure.totalHeight;
+	let trailingSpacing = firstBlock.attrs?.spacing?.after ?? 0;
+	const successorIndices = [...chain.memberIndices.slice(1)];
+	if (chain.anchorIndex !== -1) successorIndices.push(chain.anchorIndex);
+	for (let index = 0; index < successorIndices.length; index++) {
+		const successorIndex = successorIndices[index];
+		if (successorIndex === void 0) continue;
+		const successorBlock = blocks[successorIndex];
+		const successorMeasure = measures[successorIndex];
+		if (successorBlock?.kind !== "paragraph" || successorMeasure?.kind !== "paragraph") return totalHeight;
+		totalHeight += Math.max(trailingSpacing, successorBlock.attrs?.spacing?.before ?? 0);
+		const firstLine = successorMeasure.lines.at(0);
+		if (!firstLine) return totalHeight;
+		const isAnchor = index === successorIndices.length - 1 && chain.anchorIndex !== -1;
+		const isSplittable = successorMeasure.lines.length > 1 && !successorBlock.attrs?.keepLines;
+		if (isAnchor || isSplittable) return totalHeight + firstLine.lineHeight;
+		totalHeight += successorMeasure.totalHeight;
+		trailingSpacing = successorBlock.attrs?.spacing?.after ?? 0;
 	}
 	return totalHeight;
 }