@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/layout-engine/section-breaks.js

@@ -0,0 +1,182 @@
+//#region src/layout-engine/section-breaks.ts
+/**
+* Default single-column layout.
+*/
+const DEFAULT_COLUMNS = {
+	count: 1,
+	gap: 0
+};
+/**
+* Create initial section state from default options.
+*/
+function createInitialSectionState(margins, pageSize, columns) {
+	return {
+		activeTopMargin: margins.top,
+		activeBottomMargin: margins.bottom,
+		activeLeftMargin: margins.left,
+		activeRightMargin: margins.right,
+		pendingTopMargin: null,
+		pendingBottomMargin: null,
+		pendingLeftMargin: null,
+		pendingRightMargin: null,
+		activePageSize: { ...pageSize },
+		pendingPageSize: null,
+		activeColumns: columns ? { ...columns } : { ...DEFAULT_COLUMNS },
+		pendingColumns: null,
+		activeOrientation: null,
+		pendingOrientation: null,
+		hasAnyPages: false
+	};
+}
+/**
+* Check if column configuration is changing.
+*/
+function isColumnsChanging(newColumns, activeColumns) {
+	if (newColumns) return newColumns.count !== activeColumns.count || newColumns.gap !== activeColumns.gap;
+	return activeColumns.count > 1;
+}
+/**
+* Get column configuration, defaulting to single column if not specified.
+*/
+function getColumnConfig(columns) {
+	return columns ? {
+		count: columns.count,
+		gap: columns.gap
+	} : { ...DEFAULT_COLUMNS };
+}
+/**
+* Schedule section break effects by analyzing the break type and updating state.
+*
+* This determines what layout changes should occur (page break, column changes)
+* and schedules the new section properties to be applied at the appropriate boundary.
+*/
+function scheduleSectionBreak(block, state, _baseMargins) {
+	const next = { ...state };
+	const sectionType = block.type ?? "continuous";
+	const sectionMargins = block.margins;
+	const sectionPageSize = block.pageSize;
+	const sectionOrientation = block.orientation;
+	if (sectionMargins) {
+		if (typeof sectionMargins.top === "number") next.pendingTopMargin = Math.max(0, sectionMargins.top);
+		if (typeof sectionMargins.bottom === "number") next.pendingBottomMargin = Math.max(0, sectionMargins.bottom);
+		if (typeof sectionMargins.left === "number") next.pendingLeftMargin = Math.max(0, sectionMargins.left);
+		if (typeof sectionMargins.right === "number") next.pendingRightMargin = Math.max(0, sectionMargins.right);
+	}
+	if (sectionPageSize) next.pendingPageSize = {
+		w: sectionPageSize.w,
+		h: sectionPageSize.h
+	};
+	if (sectionOrientation) next.pendingOrientation = sectionOrientation;
+	const columnsChanging = isColumnsChanging(void 0, next.activeColumns);
+	switch (sectionType) {
+		case "nextPage":
+			next.pendingColumns = getColumnConfig();
+			return {
+				decision: {
+					forcePageBreak: true,
+					forceMidPageRegion: false
+				},
+				state: next
+			};
+		case "evenPage":
+			next.pendingColumns = getColumnConfig();
+			return {
+				decision: {
+					forcePageBreak: true,
+					forceMidPageRegion: false,
+					requiredParity: "even"
+				},
+				state: next
+			};
+		case "oddPage":
+			next.pendingColumns = getColumnConfig();
+			return {
+				decision: {
+					forcePageBreak: true,
+					forceMidPageRegion: false,
+					requiredParity: "odd"
+				},
+				state: next
+			};
+		default:
+			if (columnsChanging) {
+				next.pendingColumns = getColumnConfig();
+				return {
+					decision: {
+						forcePageBreak: false,
+						forceMidPageRegion: true
+					},
+					state: next
+				};
+			}
+			return {
+				decision: {
+					forcePageBreak: false,
+					forceMidPageRegion: false
+				},
+				state: next
+			};
+	}
+}
+/**
+* Apply pending section state to active state at a page boundary.
+* Transfers all pending values to active and clears pending.
+*/
+function applyPendingToActive(state) {
+	const next = { ...state };
+	if (next.pendingTopMargin !== null) {
+		next.activeTopMargin = next.pendingTopMargin;
+		next.pendingTopMargin = null;
+	}
+	if (next.pendingBottomMargin !== null) {
+		next.activeBottomMargin = next.pendingBottomMargin;
+		next.pendingBottomMargin = null;
+	}
+	if (next.pendingLeftMargin !== null) {
+		next.activeLeftMargin = next.pendingLeftMargin;
+		next.pendingLeftMargin = null;
+	}
+	if (next.pendingRightMargin !== null) {
+		next.activeRightMargin = next.pendingRightMargin;
+		next.pendingRightMargin = null;
+	}
+	if (next.pendingPageSize !== null) {
+		next.activePageSize = next.pendingPageSize;
+		next.pendingPageSize = null;
+	}
+	if (next.pendingColumns !== null) {
+		next.activeColumns = next.pendingColumns;
+		next.pendingColumns = null;
+	}
+	if (next.pendingOrientation !== null) {
+		next.activeOrientation = next.pendingOrientation;
+		next.pendingOrientation = null;
+	}
+	return next;
+}
+/**
+* Get the effective margins for the current section state.
+* Returns active margins, or pending if scheduled.
+*/
+function getEffectiveMargins(state) {
+	return {
+		top: state.pendingTopMargin ?? state.activeTopMargin,
+		bottom: state.pendingBottomMargin ?? state.activeBottomMargin,
+		left: state.pendingLeftMargin ?? state.activeLeftMargin,
+		right: state.pendingRightMargin ?? state.activeRightMargin
+	};
+}
+/**
+* Get the effective page size for the current section state.
+*/
+function getEffectivePageSize(state) {
+	return state.pendingPageSize ?? state.activePageSize;
+}
+/**
+* Get the effective columns for the current section state.
+*/
+function getEffectiveColumns(state) {
+	return state.pendingColumns ?? state.activeColumns;
+}
+//#endregion
+export { applyPendingToActive, createInitialSectionState, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, scheduleSectionBreak };

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

@@ -0,0 +1,23 @@
+import { TableBlock, TableMeasure } from "./types.js";
+
+//#region src/layout-engine/tableRowBreak.d.ts
+/** Precomputed break geometry for a table. */
+type TableRowBreakInfo = {
+  /** Cumulative y of the top of each row; `rowTops[rows.length]` is the table height. */rowTops: number[];
+  /**
+   * Per-row sorted, de-duplicated line-bottom offsets (relative to the row top)
+   * at which a break is clean. Always includes the row's full height as the
+   * final boundary.
+   */
+  breakOffsets: number[][];
+};
+/** Build break geometry for a table from its block + measure. */
+declare function buildTableRowBreakInfo(block: TableBlock, measure: TableMeasure): TableRowBreakInfo;
+/**
+ * Given a row and how much of it has already been placed (`fromOffset`), return
+ * how many more px can be placed ending on a whole line, without exceeding
+ * `maxSlice`. Returns 0 when not even the first line fits.
+ */
+declare function snapRowBreak(info: TableRowBreakInfo, rowIndex: number, fromOffset: number, maxSlice: number): number;
+//#endregion
+export { TableRowBreakInfo, buildTableRowBreakInfo, snapRowBreak };

package/dist/layout-engine/tableRowBreak.js

@@ -0,0 +1,147 @@
+import { measureParagraph } from "./measure/measureParagraph.js";
+import { buildTableCellFloatingZones, getTableCellContentWidth, getTableCellFloatingImages } from "./measure/tableCellFloating.js";
+//#region src/layout-engine/tableRowBreak.ts
+/**
+* Table row-break geometry. Ported from eigenpal/docx-editor#698 (folio subset).
+*
+* Word lets a table row break across a page boundary ("allow row to break
+* across pages", on by default). When a row is taller than a whole page it
+* cannot fit anywhere, so the portion that fits stays and the rest continues on
+* the next page — broken between whole text lines, never through a glyph.
+* Without this folio forced the oversized row onto one page and the overflow
+* was clipped (content lost; upstream #570).
+*
+* This computes, per row, the safe break offsets (the y of every line bottom in
+* the row's cells) so the paginator can snap a break to the deepest whole line
+* that still fits. Vertically-merged cells that span into a row are not modeled
+* here yet (a separate follow-up); each row uses its own cells' content.
+*/
+const DEFAULT_TABLE_CELL_PADDING_TOP = 1;
+function getAtomicBlockHeight(measure) {
+	if ("totalHeight" in measure) return measure.totalHeight;
+	if ("height" in measure) return measure.height;
+	return 0;
+}
+function isInsideRange(offset, range) {
+	return offset > range.top && offset < range.bottom;
+}
+function getVerticalAlignmentOffset(cell, measure, rowHeight) {
+	const spareHeight = Math.max(0, rowHeight - measure.height);
+	if (cell?.verticalAlign === "bottom") return spareHeight;
+	if (cell?.verticalAlign === "center") return spareHeight / 2;
+	return 0;
+}
+function shiftCellGeometry(geometry, offset) {
+	if (offset <= 0) return geometry;
+	return {
+		bottoms: geometry.bottoms.map((bottom) => bottom + offset),
+		unsafeRanges: geometry.unsafeRanges.map((range) => ({
+			top: range.top + offset,
+			bottom: range.bottom + offset
+		}))
+	};
+}
+/** Cumulative break geometry within a single cell's content. */
+function cellBreakGeometry(cell, measure) {
+	const bottoms = [];
+	const unsafeRanges = [];
+	const cellBlocks = cell?.blocks;
+	const blockMeasures = measure.blocks;
+	const padTop = cell?.padding?.top ?? DEFAULT_TABLE_CELL_PADDING_TOP;
+	const contentWidth = getTableCellContentWidth(cell, measure);
+	const floatingZones = buildTableCellFloatingZones(cell !== void 0 ? getTableCellFloatingImages(cell, measure, contentWidth) : [], contentWidth);
+	let y = padTop;
+	let paragraphY = 0;
+	for (let i = 0; i < blockMeasures.length; i++) {
+		let blockMeasure = blockMeasures[i];
+		if (blockMeasure?.kind === "paragraph") {
+			const block = cellBlocks?.[i];
+			if (block?.kind === "paragraph" && floatingZones.length > 0) blockMeasure = measureParagraph(block, contentWidth, {
+				floatingZones,
+				paragraphYOffset: paragraphY
+			});
+			const blockTop = y;
+			for (const line of blockMeasure.lines) {
+				y += line.floatSkipBefore ?? 0;
+				const top = y;
+				y += line.lineHeight;
+				unsafeRanges.push({
+					top,
+					bottom: y
+				});
+				bottoms.push(y);
+			}
+			y = blockTop + blockMeasure.totalHeight;
+			paragraphY += blockMeasure.totalHeight;
+		} else if (blockMeasure) {
+			const blockHeight = getAtomicBlockHeight(blockMeasure);
+			if (blockHeight > 0) {
+				const top = y;
+				y += blockHeight;
+				paragraphY += blockHeight;
+				unsafeRanges.push({
+					top,
+					bottom: y
+				});
+				bottoms.push(y);
+			}
+		}
+	}
+	return {
+		bottoms,
+		unsafeRanges
+	};
+}
+/** Build break geometry for a table from its block + measure. */
+function buildTableRowBreakInfo(block, measure) {
+	const rowCount = measure.rows.length;
+	const rowTops = [];
+	let acc = 0;
+	for (let r = 0; r < rowCount; r++) {
+		rowTops.push(acc);
+		acc += measure.rows[r]?.height ?? 0;
+	}
+	rowTops.push(acc);
+	const breakOffsets = [];
+	for (let r = 0; r < rowCount; r++) {
+		const rowHeight = measure.rows[r]?.height ?? 0;
+		const offsets = /* @__PURE__ */ new Set();
+		offsets.add(rowHeight);
+		const sourceCells = block.rows[r]?.cells ?? [];
+		const measuredCells = measure.rows[r]?.cells ?? [];
+		const cellGeometries = [];
+		for (let c = 0; c < measuredCells.length; c++) {
+			const measuredCell = measuredCells[c];
+			if (!measuredCell) continue;
+			const sourceCell = sourceCells[c];
+			const geometry = shiftCellGeometry(cellBreakGeometry(sourceCell, measuredCell), getVerticalAlignmentOffset(sourceCell, measuredCell, rowHeight));
+			cellGeometries.push(geometry);
+			for (const b of geometry.bottoms) if (b > 0 && b < rowHeight) offsets.add(b);
+		}
+		const safeOffsets = [...offsets].filter((offset) => offset === rowHeight || cellGeometries.every((geometry) => geometry.unsafeRanges.every((range) => !isInsideRange(offset, range))));
+		breakOffsets.push(safeOffsets.sort((a, b) => a - b));
+	}
+	return {
+		rowTops,
+		breakOffsets
+	};
+}
+/**
+* Given a row and how much of it has already been placed (`fromOffset`), return
+* how many more px can be placed ending on a whole line, without exceeding
+* `maxSlice`. Returns 0 when not even the first line fits.
+*/
+function snapRowBreak(info, rowIndex, fromOffset, maxSlice) {
+	const offsets = info.breakOffsets[rowIndex];
+	if (!offsets || offsets.length === 0) return 0;
+	const limit = fromOffset + maxSlice;
+	let best = 0;
+	for (const off of offsets) {
+		if (off <= fromOffset) continue;
+		if (off <= limit) best = off - fromOffset;
+		else break;
+	}
+	return best;
+}
+//#endregion
+export { buildTableRowBreakInfo, snapRowBreak };

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

@@ -0,0 +1,50 @@
+import { ImageRunPosition } from "./types.js";
+
+//#region src/layout-engine/textBoxFlow.d.ts
+type VerticalRelativeTo = NonNullable<ImageRunPosition["vertical"]>["relativeTo"];
+/**
+ * `true` when a vertical anchor pins the box to a fixed position on the page
+ * (page body, text margin, or a margin strip) rather than to the surrounding
+ * text flow. A `topAndBottom` box with such an anchor reserves a full-width
+ * band; `paragraph`/`line` anchors keep folio's in-flow handling. Exhaustive
+ * over the OOXML `ST_RelFromV` set so a new relativeFrom value forces a decision
+ * here instead of silently falling through. eigenpal #694.
+ */
+declare function isPageFrameRelativeAnchor(relativeTo: VerticalRelativeTo): boolean;
+/** Page geometry needed to resolve a band box's vertical anchor. */
+type BandVerticalGeometry = {
+  pageHeight: number;
+  marginTop: number;
+  marginBottom: number;
+  boxHeight: number;
+};
+/**
+ * Content-area top Y (px) of a `topAndBottom` band box's reserved band, resolved
+ * from its OOXML vertical anchor. Shared by the measure pass
+ * (`extractFloatingZones`) and the layout pass (`layoutTextBox`) so the reserved
+ * band and the painted box land at the same Y. Within the anchor's frame an
+ * explicit `posOffset` wins, then `align` (top/center/bottom/inside/outside);
+ * otherwise the box sits at the frame top. The result is content-relative
+ * (0 = content top), so a page/margin-strip frame is converted by subtracting
+ * the top margin. Ported from eigenpal #694.
+ */
+declare function bandTopContentY(vertical: ImageRunPosition["vertical"], geometry: BandVerticalGeometry): number;
+/** Page geometry needed to resolve a band box's horizontal anchor. */
+type BandHorizontalGeometry = {
+  pageWidth: number;
+  marginLeft: number;
+  marginRight: number;
+  boxWidth: number;
+};
+/**
+ * Page-absolute left X (px) of a `topAndBottom` band box, resolved from its
+ * OOXML horizontal anchor. Picks the anchor's frame (page, content box, or a
+ * left/right margin strip), then within it an explicit `posOffset` wins, else
+ * `align` (left/center/right/inside/outside); otherwise the box sits at the
+ * frame's left edge. The band itself is always full-width, so this only shifts
+ * where the box paints, not the reserved vertical space. Ported from eigenpal
+ * #694.
+ */
+declare function bandFragmentX(horizontal: ImageRunPosition["horizontal"], geometry: BandHorizontalGeometry): number;
+//#endregion
+export { BandHorizontalGeometry, BandVerticalGeometry, bandFragmentX, bandTopContentY, isPageFrameRelativeAnchor };

package/dist/layout-engine/textBoxFlow.js

@@ -0,0 +1,160 @@
+import { emuToPixels } from "../utils/units.js";
+//#region src/layout-engine/textBoxFlow.ts
+/**
+* Floating text-box band geometry. Ported from eigenpal docx-editor #474/#694.
+*
+* The floating-box predicates (`isFloatingTextBoxBlock`,
+* `floatingTextBoxWrapsText`, `floatingTextBoxReservesBand`) and the
+* `TextBoxFlowAttrs` type are pure data and live in the model layer
+* (`./types`); this module holds the page-anchor band geometry that depends on
+* pixel/EMU unit conversion.
+*/
+/**
+* `true` when a vertical anchor pins the box to a fixed position on the page
+* (page body, text margin, or a margin strip) rather than to the surrounding
+* text flow. A `topAndBottom` box with such an anchor reserves a full-width
+* band; `paragraph`/`line` anchors keep folio's in-flow handling. Exhaustive
+* over the OOXML `ST_RelFromV` set so a new relativeFrom value forces a decision
+* here instead of silently falling through. eigenpal #694.
+*/
+function isPageFrameRelativeAnchor(relativeTo) {
+	switch (relativeTo) {
+		case "page":
+		case "margin":
+		case "topMargin":
+		case "bottomMargin":
+		case "insideMargin":
+		case "outsideMargin": return true;
+		case "paragraph":
+		case "line":
+		case void 0: return false;
+		default: return false;
+	}
+}
+/**
+* Page-absolute `[top, bottom]` (px) of the frame a vertical anchor positions
+* within. `insideMargin`/`outsideMargin` map to the top/bottom margin strips
+* (vertical page parity is not modelled); flow-relative anchors fall back to the
+* content box, which is also where a page-pinned band with no usable anchor
+* sits. eigenpal #694.
+*/
+function bandVerticalFrame(relativeTo, geometry) {
+	const { pageHeight, marginTop, marginBottom } = geometry;
+	switch (relativeTo) {
+		case "page": return {
+			top: 0,
+			bottom: pageHeight
+		};
+		case "topMargin":
+		case "insideMargin": return {
+			top: 0,
+			bottom: marginTop
+		};
+		case "bottomMargin":
+		case "outsideMargin": return {
+			top: pageHeight - marginBottom,
+			bottom: pageHeight
+		};
+		case "margin":
+		case "paragraph":
+		case "line":
+		case void 0: return {
+			top: marginTop,
+			bottom: pageHeight - marginBottom
+		};
+		default: return {
+			top: marginTop,
+			bottom: pageHeight - marginBottom
+		};
+	}
+}
+/** Page-absolute top Y (px) of the box within its frame for a bare `align`. */
+function alignedFrameTop(align, frame, boxHeight) {
+	switch (align) {
+		case "center": return frame.top + (frame.bottom - frame.top - boxHeight) / 2;
+		case "bottom":
+		case "outside": return frame.bottom - boxHeight;
+		case "top":
+		case "inside":
+		case void 0: return frame.top;
+		default: return frame.top;
+	}
+}
+/**
+* Content-area top Y (px) of a `topAndBottom` band box's reserved band, resolved
+* from its OOXML vertical anchor. Shared by the measure pass
+* (`extractFloatingZones`) and the layout pass (`layoutTextBox`) so the reserved
+* band and the painted box land at the same Y. Within the anchor's frame an
+* explicit `posOffset` wins, then `align` (top/center/bottom/inside/outside);
+* otherwise the box sits at the frame top. The result is content-relative
+* (0 = content top), so a page/margin-strip frame is converted by subtracting
+* the top margin. Ported from eigenpal #694.
+*/
+function bandTopContentY(vertical, geometry) {
+	const frame = bandVerticalFrame(vertical?.relativeTo, geometry);
+	return (vertical?.posOffset !== void 0 ? frame.top + emuToPixels(vertical.posOffset) : alignedFrameTop(vertical?.align, frame, geometry.boxHeight)) - geometry.marginTop;
+}
+/**
+* Page-absolute `[left, right]` (px) of the frame a horizontal anchor positions
+* within. `inside`/`outsideMargin` map to the left/right margin strips (page
+* parity is not modelled); `column`/`character` fall back to the content box
+* (folio has no per-column/character X here). eigenpal #694.
+*/
+function bandHorizontalFrame(relativeTo, geometry) {
+	const { pageWidth, marginLeft, marginRight } = geometry;
+	switch (relativeTo) {
+		case "page": return {
+			left: 0,
+			right: pageWidth
+		};
+		case "leftMargin":
+		case "insideMargin": return {
+			left: 0,
+			right: marginLeft
+		};
+		case "rightMargin":
+		case "outsideMargin": return {
+			left: pageWidth - marginRight,
+			right: pageWidth
+		};
+		case "margin":
+		case "column":
+		case "character":
+		case void 0: return {
+			left: marginLeft,
+			right: pageWidth - marginRight
+		};
+		default: return {
+			left: marginLeft,
+			right: pageWidth - marginRight
+		};
+	}
+}
+/** Page-absolute left X (px) of the box within its frame for a bare `align`. */
+function alignedFrameLeft(align, frame, boxWidth) {
+	switch (align) {
+		case "center": return frame.left + (frame.right - frame.left - boxWidth) / 2;
+		case "right":
+		case "outside": return frame.right - boxWidth;
+		case "left":
+		case "inside":
+		case void 0: return frame.left;
+		default: return frame.left;
+	}
+}
+/**
+* Page-absolute left X (px) of a `topAndBottom` band box, resolved from its
+* OOXML horizontal anchor. Picks the anchor's frame (page, content box, or a
+* left/right margin strip), then within it an explicit `posOffset` wins, else
+* `align` (left/center/right/inside/outside); otherwise the box sits at the
+* frame's left edge. The band itself is always full-width, so this only shifts
+* where the box paints, not the reserved vertical space. Ported from eigenpal
+* #694.
+*/
+function bandFragmentX(horizontal, geometry) {
+	const frame = bandHorizontalFrame(horizontal?.relativeTo, geometry);
+	if (horizontal?.posOffset !== void 0) return frame.left + emuToPixels(horizontal.posOffset);
+	return alignedFrameLeft(horizontal?.align, frame, geometry.boxWidth);
+}
+//#endregion
+export { bandFragmentX, bandTopContentY, isPageFrameRelativeAnchor };