@stll/folio-core 0.48.0 → 0.50.0

package/dist/layout-engine/tableLayout.js

@@ -0,0 +1,369 @@
+import { projectedFootnoteReserveGrowth } from "./layoutFlowShared.js";
+import { resolveFloatingTablePageX } from "./measure/floatingTablePosition.js";
+import { resolveTableInlineOffset } from "./measure/tableInlinePlacement.js";
+import { isEmptyParagraph } from "./paragraphSpacing.js";
+import { buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak } from "./tableRowBreak.js";
+import "./types.js";
+//#region src/layout-engine/tableLayout.ts
+/**
+* Places measured tables onto pages: row splitting across pages, repeated
+* header rows, rendered-break and tracked-change row handling, row footnote
+* collection, and floating table placement.
+*/
+/**
+* Count consecutive header rows at the start of a table.
+* Header rows are marked with isHeader: true in the block data.
+*/
+function countHeaderRows(block) {
+	let count = 0;
+	for (const row of block.rows) if (row.isHeader) count++;
+	else break;
+	return count;
+}
+/**
+* Calculate total height of header rows from their measures.
+*/
+function getHeaderRowsHeight(measure, headerRowCount) {
+	let height = 0;
+	for (let i = 0; i < headerRowCount && i < measure.rows.length; i++) height += measure.rows[i].height;
+	return height;
+}
+const tableRowStartsWithRenderedPageBreak = (block, rowIndex) => {
+	const row = block.rows[rowIndex];
+	const visibleCells = row?.cells.filter((cell) => cell.blocks.some((cellBlock) => cellBlock.kind !== "paragraph" || !isEmptyParagraph(cellBlock)));
+	if (!visibleCells || visibleCells.length === 0) return false;
+	const startsWithRenderedPageBreak = (cell) => {
+		const firstVisibleBlock = cell.blocks.find((cellBlock) => cellBlock.kind !== "paragraph" || !isEmptyParagraph(cellBlock));
+		return firstVisibleBlock?.kind === "paragraph" && firstVisibleBlock.attrs?.renderedPageBreakBefore === true;
+	};
+	if (row?.heightRule === "exact") return startsWithRenderedPageBreak(visibleCells[0]);
+	return visibleCells.every(startsWithRenderedPageBreak);
+};
+const getVerticallyMergedRows = (block) => {
+	const mergedRows = /* @__PURE__ */ new Set();
+	for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+		const row = block.rows[rowIndex];
+		if (!row) continue;
+		for (const cell of row.cells) {
+			const rowSpan = cell.rowSpan ?? 1;
+			if (rowSpan <= 1) continue;
+			for (let mergedRowIndex = rowIndex; mergedRowIndex < Math.min(block.rows.length, rowIndex + rowSpan); mergedRowIndex += 1) mergedRows.add(mergedRowIndex);
+		}
+	}
+	return mergedRows;
+};
+const flowBlockHasTrackedChanges = (block) => {
+	if (block.kind === "paragraph") return block.runs.some((run) => {
+		if (run.kind === "lineBreak") return false;
+		return run.isInsertion || run.isDeletion;
+	});
+	if (block.kind === "table") return block.rows.some((row) => row.cells.some((cell) => cell.blocks.some(flowBlockHasTrackedChanges)));
+	if (block.kind === "textBox") return block.content.some(flowBlockHasTrackedChanges);
+	return false;
+};
+const tableRowHasTrackedChanges = (block, rowIndex) => block.rows[rowIndex]?.cells.some((cell) => cell.blocks.some(flowBlockHasTrackedChanges)) ?? false;
+/**
+* Layout a table block onto pages.
+*/
+function layoutTable(block, measure, paginator, footnoteHeightById) {
+	const rows = measure.rows;
+	if (rows.length === 0) return;
+	const rowFootnoteIds = block.rows.map((row) => collectTableRowFootnoteIds(row, footnoteHeightById));
+	const headerRowCount = countHeaderRows(block);
+	const headerRowsHeight = getHeaderRowsHeight(measure, headerRowCount);
+	let currentRowIndex = 0;
+	const breakInfo = buildTableRowBreakInfo(block, measure);
+	const verticallyMergedRows = getVerticallyMergedRows(block);
+	const computeTableX = ({ columnIndex, rowIndex }) => {
+		return paginator.getColumnX(columnIndex) + resolveTableInlineOffset({
+			table: block,
+			rowJustification: block.rows[rowIndex]?.justification,
+			frameWidth: paginator.columnWidth,
+			tableWidth: measure.totalWidth
+		});
+	};
+	const getCurrentRowCapacity = (state = paginator.getCurrentState()) => state.rawContentBottom - state.topMargin;
+	const hasAdjacentPriorTableRows = (rowIndex, state = paginator.getCurrentState()) => {
+		const previous = state.page.fragments.at(-1);
+		return previous?.kind === "table" && previous.blockId === block.id && previous.toRow === rowIndex && previous.y + previous.height === state.cursorY;
+	};
+	const shouldRepeatHeaderRows = (rowIndex, consumed, state = paginator.getCurrentState()) => headerRowCount > 0 && rowIndex >= headerRowCount && !(consumed === 0 && hasAdjacentPriorTableRows(rowIndex, state));
+	const rowOpensFlowRegion = (rowIndex, state) => {
+		if (state.cursorY === state.topMargin) return true;
+		const previous = state.page.fragments.at(-1);
+		return rowIndex > 0 && rowIndex <= headerRowCount && previous?.kind === "table" && previous.blockId === block.id && previous.fromRow === 0 && previous.toRow === rowIndex && previous.y === state.topMargin && previous.y + previous.height === state.cursorY;
+	};
+	const canSplitRow = (rowIndex, state = paginator.getCurrentState()) => {
+		const row = rows[rowIndex];
+		const sourceRow = block.rows[rowIndex];
+		if (!row || !sourceRow || sourceRow.isHeader || verticallyMergedRows.has(rowIndex)) return false;
+		if ((breakInfo.breakOffsets[rowIndex]?.length ?? 0) <= 1) return false;
+		const freshHeaderOverhead = headerRowCount > 0 && rowIndex >= headerRowCount ? headerRowsHeight : 0;
+		const oversized = row.height + freshHeaderOverhead > getCurrentRowCapacity(state);
+		if (sourceRow.cantSplit) return oversized && sourceRow.heightRule !== "exact" && rowOpensFlowRegion(rowIndex, state);
+		if (!oversized && (state.footnoteHeight > 0 || (rowFootnoteIds[rowIndex]?.length ?? 0) > 0)) return false;
+		const currentHeaderOverhead = shouldRepeatHeaderRows(rowIndex, 0, state) ? headerRowsHeight : 0;
+		const currentAvailableHeight = paginator.getAvailableHeight() - currentHeaderOverhead - state.trailingSpacing;
+		return oversized || row.height > currentAvailableHeight;
+	};
+	while (currentRowIndex < rows.length) {
+		const rowState = paginator.getCurrentState();
+		const rowHeaderOverhead = shouldRepeatHeaderRows(currentRowIndex, 0, rowState) ? headerRowsHeight : 0;
+		const rowAvailableHeight = paginator.getAvailableHeight() - rowHeaderOverhead - rowState.trailingSpacing;
+		const rowStartsFreshPage = rowState.cursorY === rowState.topMargin && rowState.page.fragments.length === 0;
+		if (block.rows[currentRowIndex]?.breakBefore === "page" && !rowStartsFreshPage) {
+			paginator.forcePageBreak();
+			continue;
+		}
+		if (!rowStartsFreshPage && tableRowStartsWithRenderedPageBreak(block, currentRowIndex) && !tableRowHasTrackedChanges(block, currentRowIndex) && rows[currentRowIndex].height > rowAvailableHeight) {
+			paginator.forcePageBreak();
+			continue;
+		}
+		const splittableRow = rows[currentRowIndex];
+		if (canSplitRow(currentRowIndex)) {
+			let consumed = 0;
+			const renderedBreakHints = tableRowHasTrackedChanges(block, currentRowIndex) ? [] : breakInfo.renderedBreakHints[currentRowIndex] ?? [];
+			let renderedBreakHintIndex = 0;
+			const discardPassedRenderedBreakHints = () => {
+				while ((renderedBreakHints[renderedBreakHintIndex]?.offset ?? Infinity) <= consumed) renderedBreakHintIndex += 1;
+			};
+			const advanceAfterNaturalFlowBreak = (previousPageNumber) => {
+				discardPassedRenderedBreakHints();
+				if (paginator.getCurrentState().page.number > previousPageNumber && renderedBreakHintIndex < renderedBreakHints.length) renderedBreakHintIndex += 1;
+			};
+			while (consumed < splittableRow.height) {
+				const sliceState = paginator.getCurrentState();
+				const repeatHeaderRows = shouldRepeatHeaderRows(currentRowIndex, consumed, sliceState);
+				const headerOverhead = repeatHeaderRows ? headerRowsHeight : 0;
+				const sliceAvail = paginator.getAvailableHeight() - headerOverhead - (consumed === 0 ? sliceState.trailingSpacing : 0);
+				let slice = snapRowBreak(breakInfo, currentRowIndex, consumed, sliceAvail);
+				let forceRenderedPageBreak = false;
+				if (slice <= 0) {
+					if (!(sliceState.cursorY === sliceState.topMargin && sliceState.page.fragments.length === 0)) {
+						const previousPageNumber = sliceState.page.number;
+						paginator.forceColumnBreak();
+						advanceAfterNaturalFlowBreak(previousPageNumber);
+						continue;
+					}
+					const from = consumed;
+					slice = (breakInfo.breakOffsets[currentRowIndex]?.find((o) => o > from) ?? splittableRow.height) - consumed;
+				}
+				discardPassedRenderedBreakHints();
+				const renderedBreakHint = renderedBreakHints[renderedBreakHintIndex];
+				if (renderedBreakHint && renderedBreakHint.offset <= consumed + slice && sliceAvail - (renderedBreakHint.offset - consumed) <= renderedBreakHint.lineAdvance * 3) {
+					slice = renderedBreakHint.offset - consumed;
+					renderedBreakHintIndex += 1;
+					forceRenderedPageBreak = true;
+				}
+				const sliceBottom = consumed + slice;
+				const continuationSkip = sliceBottom < splittableRow.height ? getRowContinuationSkip(breakInfo, currentRowIndex, sliceBottom) : 0;
+				const nextConsumed = Math.min(splittableRow.height, sliceBottom + continuationSkip);
+				const moreAfter = !(nextConsumed >= splittableRow.height) || currentRowIndex + 1 < rows.length;
+				const fragmentHeight = headerOverhead + slice;
+				const sliceFragment = {
+					kind: "table",
+					blockId: block.id,
+					x: computeTableX({
+						columnIndex: sliceState.columnIndex,
+						rowIndex: currentRowIndex
+					}),
+					y: 0,
+					width: measure.totalWidth,
+					height: fragmentHeight,
+					fromRow: currentRowIndex,
+					toRow: currentRowIndex + 1,
+					...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+					...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {},
+					...consumed > 0 || currentRowIndex > 0 ? { continuesFromPrev: true } : {},
+					...moreAfter ? { continuesOnNext: true } : {},
+					...repeatHeaderRows ? { headerRowCount } : {},
+					...consumed > 0 ? { topClip: consumed } : {},
+					...sliceBottom >= splittableRow.height ? {} : { bottomClip: sliceBottom },
+					...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
+				};
+				const sliceResult = paginator.addFragment(sliceFragment, fragmentHeight, 0, 0);
+				sliceFragment.y = sliceResult.y;
+				sliceFragment.x = computeTableX({
+					columnIndex: sliceResult.state.columnIndex,
+					rowIndex: currentRowIndex
+				});
+				consumed = nextConsumed;
+				if (consumed < splittableRow.height) if (forceRenderedPageBreak) paginator.forcePageBreak();
+				else {
+					const previousPageNumber = paginator.getCurrentState().page.number;
+					paginator.forceColumnBreak();
+					advanceAfterNaturalFlowBreak(previousPageNumber);
+				}
+			}
+			currentRowIndex += 1;
+			continue;
+		}
+		const state = paginator.getCurrentState();
+		const rawAvailableHeight = paginator.getAvailableHeight();
+		const isFirstFragment = currentRowIndex === 0;
+		const bandSkip = isFirstFragment ? measure.bandSkipBefore ?? 0 : 0;
+		const availableHeight = rawAvailableHeight - (isFirstFragment ? Math.max(bandSkip, state.trailingSpacing) : 0);
+		const repeatHeaderRowsForNormalFragment = shouldRepeatHeaderRows(currentRowIndex, 0, state);
+		const normalHeaderOverhead = repeatHeaderRowsForNormalFragment ? headerRowsHeight : 0;
+		let rowsHeight = 0;
+		let fittingRows = 0;
+		const pageFootnoteIds = new Set(state.page.footnoteIds ?? []);
+		const fragmentFootnoteIds = [];
+		let fragmentFootnoteHeight = 0;
+		let retryOnNextFlowRegion = false;
+		const fragmentX = computeTableX({
+			columnIndex: state.columnIndex,
+			rowIndex: currentRowIndex
+		});
+		for (let j = currentRowIndex; j < rows.length; j++) {
+			if (j > currentRowIndex && block.rows[j]?.breakBefore === "page") break;
+			if (j > currentRowIndex && computeTableX({
+				columnIndex: state.columnIndex,
+				rowIndex: j
+			}) !== fragmentX) break;
+			const rowHeight = rows[j].height;
+			const currentRowFootnoteIds = rowFootnoteIds[j] ?? [];
+			const fragmentFootnoteCountBeforeRow = fragmentFootnoteIds.length;
+			let rowFootnoteHeight = 0;
+			for (const id of currentRowFootnoteIds) {
+				if (pageFootnoteIds.has(id) || fragmentFootnoteIds.includes(id)) continue;
+				fragmentFootnoteIds.push(id);
+				rowFootnoteHeight += footnoteHeightById?.get(id) ?? 0;
+			}
+			const candidateFootnoteHeight = fragmentFootnoteHeight + rowFootnoteHeight;
+			const footnoteGrowth = projectedFootnoteReserveGrowth(state, candidateFootnoteHeight + (state.footnoteDemandHeight === 0 && candidateFootnoteHeight > 0 ? 12 : 0));
+			if (rowsHeight + rowHeight + normalHeaderOverhead + footnoteGrowth <= availableHeight) {
+				rowsHeight += rowHeight;
+				fragmentFootnoteHeight += rowFootnoteHeight;
+				fittingRows++;
+			} else if (fittingRows === 0) {
+				if (state.cursorY === state.topMargin && state.page.fragments.length === 0) {
+					rowsHeight += rowHeight;
+					fragmentFootnoteHeight += rowFootnoteHeight;
+					fittingRows++;
+					break;
+				}
+				fragmentFootnoteIds.splice(fragmentFootnoteCountBeforeRow);
+				paginator.forceColumnBreak();
+				retryOnNextFlowRegion = true;
+				break;
+			} else {
+				fragmentFootnoteIds.splice(fragmentFootnoteCountBeforeRow);
+				break;
+			}
+		}
+		if (retryOnNextFlowRegion) continue;
+		const fragmentHeight = rowsHeight + normalHeaderOverhead;
+		const isLastFragment = currentRowIndex + fittingRows >= rows.length;
+		const desiredX = fragmentX;
+		const fragment = {
+			kind: "table",
+			blockId: block.id,
+			x: desiredX,
+			y: 0,
+			width: measure.totalWidth,
+			height: fragmentHeight,
+			fromRow: currentRowIndex,
+			toRow: currentRowIndex + fittingRows,
+			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {},
+			...!isFirstFragment ? { continuesFromPrev: true } : {},
+			...!isLastFragment ? { continuesOnNext: true } : {},
+			...repeatHeaderRowsForNormalFragment ? { headerRowCount } : {},
+			...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
+		};
+		if (fragmentFootnoteHeight > 0) paginator.addFootnoteHeight(fragmentFootnoteHeight, fragmentFootnoteIds);
+		fragment.y = paginator.addFragment(fragment, fragmentHeight, bandSkip, 0).y;
+		fragment.x = desiredX;
+		currentRowIndex += fittingRows;
+		if (currentRowIndex < rows.length) {
+			if (canSplitRow(currentRowIndex)) {
+				const nextState = paginator.getCurrentState();
+				const nextHeaderOverhead = shouldRepeatHeaderRows(currentRowIndex, 0, nextState) ? headerRowsHeight : 0;
+				const nextSliceAvail = paginator.getAvailableHeight() - nextHeaderOverhead - nextState.trailingSpacing;
+				if (snapRowBreak(breakInfo, currentRowIndex, 0, nextSliceAvail) > 0) continue;
+			}
+			const nextState = paginator.getCurrentState();
+			const nextRowHeight = rows[currentRowIndex].height + (shouldRepeatHeaderRows(currentRowIndex, 0, nextState) ? headerRowsHeight : 0);
+			paginator.ensureFits(nextRowHeight);
+		}
+	}
+}
+function collectTableRowFootnoteIds(row, footnoteHeightById) {
+	if (!row || !footnoteHeightById || row.hidden) return [];
+	const ids = [];
+	const walk = (blocks) => {
+		for (const block of blocks) {
+			if (block.kind === "paragraph") {
+				for (const run of block.runs) if (run.kind === "text" && run.footnoteRefId !== void 0 && footnoteHeightById.has(run.footnoteRefId) && !ids.includes(run.footnoteRefId)) ids.push(run.footnoteRefId);
+				continue;
+			}
+			if (block.kind === "table") {
+				for (const nestedRow of block.rows) {
+					if (nestedRow.hidden) continue;
+					for (const cell of nestedRow.cells) walk(cell.blocks);
+				}
+				continue;
+			}
+			if (block.kind === "textBox") walk(block.content);
+		}
+	};
+	for (const cell of row.cells) walk(cell.blocks);
+	return ids;
+}
+/**
+* Layout a floating table (anchored) without advancing the cursor.
+*/
+function layoutFloatingTable(block, measure, paginator, contentWidth) {
+	const state = paginator.getCurrentState();
+	const floating = block.floating;
+	const page = state.page;
+	const margins = page.margins;
+	const tableWidth = measure.totalWidth;
+	const tableHeight = measure.totalHeight;
+	const contentHeight = page.size.h - margins.top - margins.bottom;
+	let baseY = margins.top;
+	if (floating?.vertAnchor === "page") baseY = 0;
+	else if (floating?.vertAnchor === "text") baseY = state.cursorY;
+	let x = paginator.getColumnX(state.columnIndex);
+	if (floating) x = resolveFloatingTablePageX({
+		anchor: floating,
+		justification: block.justification,
+		tableWidth,
+		marginWidth: contentWidth,
+		pageWidth: page.size.w,
+		marginLeft: margins.left,
+		textFrameWidth: paginator.columnWidth,
+		textFrameLeft: paginator.getColumnX(state.columnIndex)
+	});
+	let y = state.cursorY;
+	let usedExplicitY = false;
+	if (floating?.tblpY !== void 0) {
+		y = baseY + floating.tblpY;
+		usedExplicitY = true;
+	} else if (floating?.tblpYSpec) {
+		usedExplicitY = true;
+		const spec = floating.tblpYSpec;
+		if (spec === "top") y = baseY;
+		else if (spec === "bottom") y = baseY + contentHeight - tableHeight;
+		else if (spec === "center") y = baseY + (contentHeight - tableHeight) / 2;
+	}
+	if (!usedExplicitY) y = paginator.ensureFits(tableHeight).cursorY;
+	const fragment = {
+		kind: "table",
+		blockId: block.id,
+		x,
+		y,
+		width: tableWidth,
+		height: tableHeight,
+		fromRow: 0,
+		toRow: block.rows.length,
+		...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+		...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {},
+		isFloating: true,
+		...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
+	};
+	paginator.addUnflowedFragment(fragment);
+}
+//#endregion
+export { getHeaderRowsHeight, layoutFloatingTable, layoutTable };

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

@@ -19,6 +19,13 @@ type TableRowBreakInfo = {
   /** Suppressible leading paragraph whitespace after each matching break offset. */
   continuationSkips: number[][];
 };
+/**
+ * Height of the start of a table that a preceding `w:keepNext` paragraph
+ * (§17.3.1.15) must share a page with: the leading header rows (§17.4.49) and
+ * the first body row. A row that may break across pages (no `w:cantSplit`,
+ * §17.4.6) needs only its first line there; an unbreakable row needs all of it.
+ */
+declare function tableKeepNextOpeningHeight(block: TableBlock, measure: TableMeasure): number;
 /** Build break geometry for a table from its block + measure. */
 declare function buildTableRowBreakInfo(block: TableBlock, measure: TableMeasure): TableRowBreakInfo;
 /** Leading empty-paragraph whitespace to consume when a row resumes after `offset`. */
@@ -30,4 +37,4 @@ declare function getRowContinuationSkip(info: TableRowBreakInfo, rowIndex: numbe
  */
 declare function snapRowBreak(info: TableRowBreakInfo, rowIndex: number, fromOffset: number, maxSlice: number): number;
 //#endregion
-export { TableRowBreakInfo, buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak };
+export { TableRowBreakInfo, buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak, tableKeepNextOpeningHeight };

package/dist/layout-engine/tableRowBreak.js

@@ -141,6 +141,27 @@ const continuationSkipAfter = (geometries, offset) => {
 	if (skips.length === 0 || skips.some((skip) => skip <= BREAK_OFFSET_EPSILON)) return 0;
 	return Math.min(...skips);
 };
+/**
+* Height of the start of a table that a preceding `w:keepNext` paragraph
+* (§17.3.1.15) must share a page with: the leading header rows (§17.4.49) and
+* the first body row. A row that may break across pages (no `w:cantSplit`,
+* §17.4.6) needs only its first line there; an unbreakable row needs all of it.
+*/
+function tableKeepNextOpeningHeight(block, measure) {
+	let height = 0;
+	let rowIndex = 0;
+	while (rowIndex < measure.rows.length && block.rows[rowIndex]?.isHeader === true) {
+		height += measure.rows[rowIndex]?.height ?? 0;
+		rowIndex += 1;
+	}
+	const row = measure.rows[rowIndex];
+	const sourceRow = block.rows[rowIndex];
+	if (!row || !sourceRow) return height;
+	const breakOffsets = buildTableRowBreakInfo(block, measure).breakOffsets[rowIndex] ?? [];
+	const firstBreak = breakOffsets.at(0);
+	const rowMayBreak = sourceRow.cantSplit !== true && breakOffsets.length > 1;
+	return height + (rowMayBreak && firstBreak !== void 0 ? firstBreak : row.height);
+}
 /** Build break geometry for a table from its block + measure. */
 function buildTableRowBreakInfo(block, measure) {
 	const rowCount = measure.rows.length;
@@ -208,4 +229,4 @@ function snapRowBreak(info, rowIndex, fromOffset, maxSlice) {
 	return best;
 }
 //#endregion
-export { buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak };
+export { buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak, tableKeepNextOpeningHeight };

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

@@ -0,0 +1,15 @@
+import { TextBoxBlock, TextBoxMeasure } from "./types.js";
+import { createPaginator } from "./paginator.js";
+//#region src/layout-engine/textBoxLayout.d.ts
+type LayoutTextBoxOptions = {
+  paginator: ReturnType<typeof createPaginator>;
+  sectionMarginTop: number;
+  sectionPageHeight: number;
+  sectionMarginBottom: number;
+};
+/**
+ * Layout a text box block onto pages.
+ */
+declare function layoutTextBox(block: TextBoxBlock, measure: TextBoxMeasure, { paginator, sectionMarginTop, sectionPageHeight, sectionMarginBottom }: LayoutTextBoxOptions): void;
+//#endregion
+export { layoutTextBox };

package/dist/layout-engine/textBoxLayout.js

@@ -0,0 +1,137 @@
+import { emuToPixels } from "../utils/units.js";
+import { bandFragmentX, bandTopContentY, isPageFrameRelativeAnchor } from "./textBoxFlow.js";
+import { floatingTextBoxReservesBand } from "./types.js";
+//#region src/layout-engine/textBoxLayout.ts
+/**
+* Places text boxes onto pages: inline and anchored placement, page-pinned
+* wrap bands, and host-paragraph line offsets.
+*/
+const TEXT_BOX_ANCHOR_BLOCK_ID = Symbol.for("stll.textBoxAnchorBlockId");
+const readTextBoxAnchorBlockId = (block) => Reflect.get(block, TEXT_BOX_ANCHOR_BLOCK_ID);
+/**
+* Layout a text box block onto pages.
+*/
+function layoutTextBox(block, measure, { paginator, sectionMarginTop, sectionPageHeight, sectionMarginBottom }) {
+	if (isPagePinnedBandTextBox(block)) {
+		const state = paginator.getCurrentState();
+		const bandTop = bandTopContentY(block.position?.vertical, {
+			pageHeight: sectionPageHeight,
+			marginTop: sectionMarginTop,
+			marginBottom: sectionMarginBottom,
+			boxHeight: measure.height
+		});
+		const x = bandFragmentX(block.position?.horizontal, {
+			pageWidth: state.page.size.w,
+			marginLeft: state.page.margins.left,
+			marginRight: state.page.margins.right,
+			activeColumnLeft: paginator.getColumnX(state.columnIndex),
+			activeColumnWidth: paginator.columnWidth,
+			boxWidth: measure.width
+		});
+		const fragment = {
+			kind: "textBox",
+			blockId: block.id,
+			x,
+			y: block.position?.vertical?.relativeTo === "page" ? sectionMarginTop + bandTop : state.topMargin + bandTop,
+			width: measure.width,
+			height: measure.height,
+			isPositioned: true,
+			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {}
+		};
+		paginator.addUnflowedFragment(fragment);
+		return;
+	}
+	if (block.position !== void 0) {
+		const state = paginator.getCurrentState();
+		const x = bandFragmentX(block.position.horizontal, {
+			pageWidth: state.page.size.w,
+			marginLeft: state.page.margins.left,
+			marginRight: state.page.margins.right,
+			activeColumnLeft: paginator.getColumnX(state.columnIndex),
+			activeColumnWidth: paginator.columnWidth,
+			boxWidth: measure.width
+		});
+		const vertical = block.position.vertical;
+		const anchorBlockId = readTextBoxAnchorBlockId(block);
+		const anchorParagraph = vertical?.relativeTo === "paragraph" && typeof anchorBlockId === "string" ? state.page.fragments.find((fragment) => fragment.kind === "paragraph" && fragment.blockId === anchorBlockId) : void 0;
+		const bandGeometry = {
+			pageHeight: sectionPageHeight,
+			marginTop: sectionMarginTop,
+			marginBottom: sectionMarginBottom,
+			boxHeight: measure.height
+		};
+		let y;
+		if (vertical?.relativeTo === "page") y = sectionMarginTop + bandTopContentY(vertical, bandGeometry);
+		else if (isPageFrameRelativeAnchor(vertical?.relativeTo)) y = state.topMargin + bandTopContentY(vertical, {
+			pageHeight: sectionPageHeight,
+			marginTop: sectionMarginTop,
+			marginBottom: sectionMarginBottom,
+			boxHeight: measure.height
+		});
+		else y = (anchorParagraph?.y ?? state.cursorY) + emuToPixels(vertical?.posOffset ?? 0);
+		const fragment = {
+			kind: "textBox",
+			blockId: block.id,
+			x,
+			y,
+			width: measure.width,
+			height: measure.height,
+			isPositioned: true,
+			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {}
+		};
+		paginator.addUnflowedFragment(fragment);
+		return;
+	}
+	const effect = block.effectExtent;
+	const occupiedHeight = measure.height + (effect?.top ?? 0) + (effect?.bottom ?? 0);
+	const occupiedWidth = measure.width + (effect?.left ?? 0) + (effect?.right ?? 0);
+	const host = block.hostParagraph;
+	const fragment = {
+		kind: "textBox",
+		blockId: block.id,
+		x: 0,
+		y: 0,
+		width: measure.width,
+		height: measure.height,
+		...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+		...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {}
+	};
+	const result = paginator.addFragment(fragment, occupiedHeight, host?.spacing?.before ?? 0, host?.spacing?.after ?? 0);
+	fragment.x = result.x + hostParagraphLineOffset(host, paginator.columnWidth, occupiedWidth) + (effect?.left ?? 0);
+	fragment.y = result.y + (effect?.top ?? 0);
+}
+/**
+* Where a line holding only an object of `width` starts within a column:
+* after the host paragraph's start and first-line indents, then aligned in
+* what remains before its end indent.
+*/
+function hostParagraphLineOffset(host, columnWidth, width) {
+	if (!host) return 0;
+	const indent = host.indent;
+	const start = (indent?.left ?? 0) + (indent?.firstLine ?? 0) - (indent?.hanging ?? 0);
+	const slack = Math.max(0, columnWidth - start - (indent?.right ?? 0) - width);
+	switch (host.alignment) {
+		case "center": return start + slack / 2;
+		case "right": return start + slack;
+		case "left":
+		case "justify":
+		case void 0: return start;
+		default:
+			host.alignment;
+			return start;
+	}
+}
+/**
+* A topAndBottom text box whose vertical anchor pins it to the page frame
+* (page/margin/margin-strip) — it floats to a fixed page position rather than
+* flowing in document order. Must agree with the measure pass's band extraction
+* (extractFloatingZones), which uses the same predicate. eigenpal #694.
+*/
+function isPagePinnedBandTextBox(block) {
+	if (!floatingTextBoxReservesBand(block)) return false;
+	return isPageFrameRelativeAnchor(block.position?.vertical?.relativeTo);
+}
+//#endregion
+export { layoutTextBox };

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

@@ -2,7 +2,7 @@ import { OutlineStyleAttr } from "../types/documentEnumValues.js";
 import { CssBorderStyle } from "../utils/borderCss.js";
 import { ImagePosition, ImageWrap, InlineWrapper, NumberFormat, OutlineLevel, ParagraphNumberingOverride, PreviewDescriptor, SdtProperties, SdtType, SectionStart, ShapeTextBody, TableCellFormatting, TableWidthType, UnderlineStyle, VerticalAlign } from "@stll/docx-core/model";
 declare namespace types_d_exports {
-  export { 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, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned };
+  export { 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, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxGradientFill, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned };
 }
 /**
  * Unique identifier for a block in the document.
@@ -849,6 +849,21 @@ declare const DEFAULT_TEXTBOX_MARGINS: {
 };
 /** Default text box width in pixels when no width is specified */
 declare const DEFAULT_TEXTBOX_WIDTH = 200;
+/**
+ * A linear DrawingML gradient fill with its colors resolved (ECMA-376
+ * §20.1.8.33, §20.1.8.41). It runs along `angle`, in degrees clockwise from
+ * the positive x axis; when `scaled`, that angle is stated in the unit square
+ * and stretched with the box.
+ */
+type TextBoxGradientFill = {
+  angle: number;
+  scaled: boolean;
+  /** Stops in ascending order; `offset` runs 0 to 1. */
+  stops: {
+    offset: number;
+    color: string;
+  }[];
+};
 /**
  * Text box block — positioned container with block content.
  */
@@ -869,6 +884,8 @@ type TextBoxBlock = {
   verticalAlign?: ShapeTextBody["anchor"];
   /** Fill/background color */
   fillColor?: string;
+  /** Gradient fill, painted when no `fillColor` states a solid one. */
+  fillGradient?: TextBoxGradientFill;
   /** Border width in pixels */
   outlineWidth?: number;
   /** Border color */
@@ -1341,6 +1358,8 @@ type LayoutOptions = {
   firstPageMargins?: PageMargins;
   /** Per-section body margins used on even authored page numbers. */
   sectionEvenPageMargins?: (PageMargins | undefined)[];
+  /** Per-section body margins used on the first page of a `w:titlePg` section. */
+  sectionFirstPageMargins?: (PageMargins | undefined)[];
   /** Page-number policy for the initial section. */
   pageNumbering?: SectionPageNumbering;
   /** Body-level final section page size. */
@@ -1576,4 +1595,4 @@ declare const getTableRowLeadingWidth: (row: TableRow, columnWidths: readonly nu
  */
 declare function stripFlowBlockPmAnchors(block: FlowBlock): FlowBlock;
 //#endregion
-export { 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, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned, types_d_exports };
+export { 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, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxGradientFill, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned, types_d_exports };

package/dist/layout-painter/renderPage.js

@@ -1,3 +1,4 @@
+import "../layout-engine/measure/floatingLineClearance.js";
 import { resolveFloatingTableX } from "../layout-engine/measure/floatingTablePosition.js";
 import { rectsToFloatingZones } from "../layout-engine/measure/floatingZones.js";
 import { DEFAULT_FONT_FAMILY } from "../layout-engine/measure/measureHelpers.js";