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

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

@@ -0,0 +1,84 @@
+import { ColumnLayout, FOOTNOTE_SEPARATOR_HEIGHT, Fragment, Page, PageHeaderFooterRefs, PageMargins } from "./types.js";
+
+//#region src/layout-engine/paginator.d.ts
+/**
+ * Current state of a page being laid out.
+ */
+type PageState = {
+  /** The page being built. */page: Page; /** Current Y position (cursor) from page top. */
+  cursorY: number; /** Current column index (0-based). */
+  columnIndex: number; /** Top margin of content area. */
+  topMargin: number;
+  /**
+   * Bottom boundary of usable body content area.
+   * Equals `pageBottom - footnoteHeight`. Recomputed when footnote
+   * demand grows (a line carrying a fn ref is placed on this page).
+   */
+  contentBottom: number; /** Raw bottom of content area (page height - bottom margin); excludes fn area. */
+  rawContentBottom: number; /** Total height reserved for footnotes on this page (grows as refs are placed). */
+  footnoteHeight: number; /** Accumulated trailing spacing (space after previous block). */
+  trailingSpacing: number;
+};
+/**
+ * Options for creating a paginator.
+ */
+type PaginatorOptions = {
+  /** Page size (width, height). */pageSize: {
+    w: number;
+    h: number;
+  }; /** Page margins. */
+  margins: PageMargins;
+  /**
+   * Margins applied only to the very first page (page 1) of the paginator.
+   * Used when a `<w:titlePg/>`-enabled section needs different margins for
+   * its title page (typically extended top margin to clear an overflowing
+   * first-page header) vs. its body pages. Pages 2+ use `margins`.
+   */
+  firstPageMargins?: PageMargins; /** Column configuration (optional). */
+  columns?: ColumnLayout; /** Per-page footnote reserved heights (pageNumber → height in pixels). */
+  footnoteReservedHeights?: Map<number, number>; /** Header/footer refs by section index. */
+  sectionHeaderFooterRefs?: PageHeaderFooterRefs[]; /** Callback when a new page is created. */
+  onNewPage?: (state: PageState) => void;
+};
+type ForcePageBreakOptions = {
+  coalesceBlankPage?: boolean;
+};
+/**
+ * Creates a paginator for managing page layout state.
+ */
+declare function createPaginator(options: PaginatorOptions): {
+  /** All pages created so far. */pages: Page[]; /** All page states. */
+  states: PageState[]; /** Column width in pixels (use getColumnWidth() for current value after updates). */
+  readonly columnWidth: number; /** Get current column layout (returns copy to prevent external mutation). */
+  readonly columns: {
+    count: number;
+    gap: number;
+    equalWidth?: boolean;
+    separator?: boolean;
+  }; /** Get current state. */
+  getCurrentState: () => PageState; /** Get available height in current column. */
+  getAvailableHeight: () => number; /** Full content height of a fresh page in the active section. */
+  getContentHeight: () => number; /** Get content width for the active section. */
+  getContentWidth: () => number; /** Check if height fits in current column. */
+  fits: (height: number) => boolean; /** Ensure height fits, advancing if needed. */
+  ensureFits: (height: number) => PageState; /** Add a fragment to current page. */
+  addFragment: (fragment: Fragment, height: number, spaceBefore?: number, spaceAfter?: number) => {
+    state: PageState;
+    x: number;
+    y: number;
+  }; /** Reserve additional footnote area on the current page. */
+  addFootnoteHeight: (additionalHeight: number, footnoteIds?: number[]) => void; /** Force a page break. */
+  forcePageBreak: (breakOptions?: ForcePageBreakOptions) => PageState; /** Reuse an already blank current page for the active section/layout. */
+  retargetCurrentBlankPage: () => boolean; /** Force a column break. */
+  forceColumnBreak: () => PageState; /** Get X position for column. */
+  getColumnX: (columnIndex: number) => number; /** Update column layout (for section breaks). */
+  updateColumns: (newColumns: ColumnLayout) => void; /** Update page size/margins for subsequent pages. */
+  updatePageLayout: (newPageSize?: {
+    w: number;
+    h: number;
+  }, newMargins?: PageMargins, applyImmediately?: boolean) => void; /** Mark the next created page as the first page of a new section. */
+  startSection: (sectionIndex: number) => void;
+};
+type Paginator = ReturnType<typeof createPaginator>;
+//#endregion
+export { FOOTNOTE_SEPARATOR_HEIGHT, PageState, Paginator, PaginatorOptions, createPaginator };

package/dist/layout-engine/paginator.js

@@ -0,0 +1,348 @@
+import { FOOTNOTE_SEPARATOR_HEIGHT } from "./types.js";
+import { panic } from "better-result";
+//#region src/layout-engine/paginator.ts
+/**
+* Paginator - manages page state during layout
+*
+* Tracks the current page, cursor position, and available space.
+* Creates new pages when content doesn't fit.
+*/
+/**
+* Calculate the width of a single column.
+*/
+function calculateColumnWidth(pageWidth, leftMargin, rightMargin, columns) {
+	return (pageWidth - leftMargin - rightMargin - (columns.count - 1) * columns.gap) / columns.count;
+}
+function arePageSizesEqual(left, right) {
+	return left.w === right.w && left.h === right.h;
+}
+function areMarginsEqual(left, right) {
+	return left.top === right.top && left.right === right.right && left.bottom === right.bottom && left.left === right.left && left.header === right.header && left.footer === right.footer;
+}
+/**
+* Creates a paginator for managing page layout state.
+*/
+function createPaginator(options) {
+	let pageSize = { ...options.pageSize };
+	let margins = { ...options.margins };
+	let columns = options.columns ?? {
+		count: 1,
+		gap: 0
+	};
+	let pendingPageSize;
+	let pendingMargins;
+	let currentSectionIndex = 0;
+	let currentSectionPageNumber = 0;
+	const pages = [];
+	const states = [];
+	function getContentBottom() {
+		return pageSize.h - margins.bottom;
+	}
+	function getContentHeight() {
+		return getContentBottom() - margins.top;
+	}
+	function getContentWidth() {
+		return pageSize.w - margins.left - margins.right;
+	}
+	function currentPageUsesActiveLayout(state) {
+		if (pendingPageSize || pendingMargins) return false;
+		return arePageSizesEqual(state.page.size, pageSize) && areMarginsEqual(state.page.margins, margins);
+	}
+	if (getContentHeight() <= 0) panic("Paginator: page size and margins yield no content area");
+	let columnWidth = calculateColumnWidth(pageSize.w, margins.left, margins.right, columns);
+	function recalculateColumnWidth() {
+		columnWidth = calculateColumnWidth(pageSize.w, margins.left, margins.right, columns);
+	}
+	function applyPendingLayout() {
+		if (pendingPageSize) pageSize = pendingPageSize;
+		if (pendingMargins) margins = pendingMargins;
+		pendingPageSize = void 0;
+		pendingMargins = void 0;
+		if (getContentHeight() <= 0) panic("Paginator: section page size and margins yield no content area");
+		recalculateColumnWidth();
+	}
+	function getPageMargins(pageNumber) {
+		return pageNumber === 1 && options.firstPageMargins ? { ...options.firstPageMargins } : { ...margins };
+	}
+	let columnRegionTop = margins.top;
+	/**
+	* Get X position for a given column index.
+	*/
+	function getColumnX(columnIndex) {
+		return margins.left + columnIndex * (columnWidth + columns.gap);
+	}
+	/**
+	* Create a new page and add it to the list.
+	*/
+	function createNewPage() {
+		if (pendingPageSize || pendingMargins) applyPendingLayout();
+		const pageNumber = pages.length + 1;
+		currentSectionPageNumber += 1;
+		const pageMargins = getPageMargins(pageNumber);
+		const topMargin = pageMargins.top;
+		const contentBottom = pageSize.h - pageMargins.bottom;
+		const footnoteHeight = options.footnoteReservedHeights?.get(pageNumber) ?? 0;
+		const pageContentBottom = contentBottom - footnoteHeight;
+		const page = {
+			number: pageNumber,
+			fragments: [],
+			margins: pageMargins,
+			size: { ...pageSize },
+			...footnoteHeight > 0 ? { footnoteReservedHeight: footnoteHeight } : {},
+			...columns.count > 1 ? { columns: { ...columns } } : {}
+		};
+		applySectionMetadata(page);
+		const state = {
+			page,
+			cursorY: topMargin,
+			columnIndex: 0,
+			topMargin,
+			contentBottom: pageContentBottom,
+			rawContentBottom: contentBottom,
+			footnoteHeight,
+			trailingSpacing: 0
+		};
+		pages.push(page);
+		states.push(state);
+		columnRegionTop = topMargin;
+		if (options.onNewPage) options.onNewPage(state);
+		return state;
+	}
+	/**
+	* Get the current page state, creating one if none exists.
+	*/
+	function getCurrentState() {
+		if (states.length === 0) return createNewPage();
+		const last = states.at(-1);
+		if (!last) return createNewPage();
+		return last;
+	}
+	/**
+	* Get available height remaining on the current column.
+	*/
+	function getAvailableHeight(state) {
+		return state.contentBottom - state.cursorY;
+	}
+	/**
+	* Check if the given height fits in the current column.
+	*/
+	function fits(height, state) {
+		return getAvailableHeight(state || getCurrentState()) >= height;
+	}
+	/**
+	* Advance to the next column, or create a new page if no more columns.
+	*/
+	function advanceColumn(state) {
+		if (state.columnIndex < columns.count - 1) {
+			state.columnIndex += 1;
+			state.cursorY = columnRegionTop;
+			state.trailingSpacing = 0;
+			return state;
+		}
+		return createNewPage();
+	}
+	/**
+	* Ensure content of given height can fit.
+	* Advances column or creates new page if needed.
+	* Returns the state to use for placement.
+	*/
+	function ensureFits(height) {
+		let state = getCurrentState();
+		const safeHeight = Number.isFinite(height) && height > 0 ? height : 0;
+		while (!fits(safeHeight, state)) {
+			if (safeHeight > state.contentBottom - state.topMargin) {
+				if (state.cursorY !== state.topMargin) state = advanceColumn(state);
+				return state;
+			}
+			state = advanceColumn(state);
+		}
+		return state;
+	}
+	/**
+	* Add a fragment to the current page at the cursor position.
+	* Updates cursor position after placement.
+	*/
+	function addFragment(fragment, height, spaceBefore = 0, spaceAfter = 0) {
+		const initialState = getCurrentState();
+		const initialColumnIndex = initialState.columnIndex;
+		const effectiveSpaceBefore = Math.max(spaceBefore, initialState.trailingSpacing);
+		const state = ensureFits(effectiveSpaceBefore + height);
+		const actualSpaceBefore = state === initialState && state.columnIndex === initialColumnIndex ? effectiveSpaceBefore : spaceBefore;
+		const x = getColumnX(state.columnIndex);
+		const y = state.cursorY + actualSpaceBefore;
+		fragment.x = x;
+		fragment.y = y;
+		state.page.fragments.push(fragment);
+		state.cursorY = y + height;
+		state.trailingSpacing = spaceAfter;
+		return {
+			state,
+			x,
+			y
+		};
+	}
+	/**
+	* Reserve additional footnote area on the current page.
+	*
+	* Called by the layout engine each time a body line carrying a
+	* footnote ref is placed: the page must shrink its body area by
+	* the fn content's height so the fn can render below without
+	* overflowing into the footer. Updates both `state.contentBottom`
+	* (so subsequent line-fitting checks see the reduced space) and
+	* `state.page.footnoteReservedHeight` (so the painter draws the fn
+	* area at the correct top).
+	*
+	* On the first fn added to a page, additionally reserves
+	* `FOOTNOTE_SEPARATOR_HEIGHT` for the divider line + its margins so
+	* the separator stays inside the reserved slot.
+	*
+	* Caller is responsible for ensuring the line itself fits *with*
+	* `additionalHeight` already accounted for; if the line should have
+	* advanced to the next page, the engine must check that *before*
+	* committing the line + reservation.
+	*/
+	function addFootnoteHeight(additionalHeight, footnoteIds) {
+		if (!Number.isFinite(additionalHeight) || additionalHeight <= 0) return;
+		const state = getCurrentState();
+		const separatorOverhead = state.footnoteHeight === 0 ? 12 : 0;
+		state.footnoteHeight += additionalHeight + separatorOverhead;
+		state.contentBottom = state.rawContentBottom - state.footnoteHeight;
+		state.page.footnoteReservedHeight = state.footnoteHeight;
+		if (footnoteIds && footnoteIds.length > 0) {
+			const existing = state.page.footnoteIds ?? [];
+			for (const id of footnoteIds) if (!existing.includes(id)) existing.push(id);
+			state.page.footnoteIds = existing;
+		}
+	}
+	/**
+	* Force a page break - move to a new page.
+	*/
+	function forcePageBreak(breakOptions = {}) {
+		const current = states.at(-1);
+		if (breakOptions.coalesceBlankPage && current && current.page.fragments.length === 0 && current.cursorY === current.topMargin && currentPageUsesActiveLayout(current)) {
+			if (current.page.sectionIndex !== currentSectionIndex) {
+				currentSectionPageNumber = 1;
+				applySectionMetadata(current.page);
+			}
+			return current;
+		}
+		return createNewPage();
+	}
+	function retargetCurrentBlankPage() {
+		const current = states.at(-1);
+		if (!current || current.page.fragments.length > 0 || current.cursorY !== current.topMargin) return false;
+		if (pendingPageSize || pendingMargins) applyPendingLayout();
+		const pageMargins = getPageMargins(current.page.number);
+		const topMargin = pageMargins.top;
+		const rawContentBottom = pageSize.h - pageMargins.bottom;
+		const footnoteHeight = options.footnoteReservedHeights?.get(current.page.number) ?? 0;
+		current.page.size = { ...pageSize };
+		current.page.margins = pageMargins;
+		if (footnoteHeight > 0) current.page.footnoteReservedHeight = footnoteHeight;
+		else delete current.page.footnoteReservedHeight;
+		if (columns.count > 1) current.page.columns = { ...columns };
+		else delete current.page.columns;
+		current.topMargin = topMargin;
+		current.cursorY = topMargin;
+		current.columnIndex = 0;
+		current.rawContentBottom = rawContentBottom;
+		current.footnoteHeight = footnoteHeight;
+		current.contentBottom = rawContentBottom - footnoteHeight;
+		current.trailingSpacing = 0;
+		columnRegionTop = topMargin;
+		currentSectionPageNumber = 1;
+		applySectionMetadata(current.page);
+		return true;
+	}
+	/**
+	* Force a column break - move to next column or new page.
+	*/
+	function forceColumnBreak() {
+		return advanceColumn(getCurrentState());
+	}
+	/**
+	* Update column configuration mid-document (for section breaks).
+	* Recalculates column width based on current page/margin dimensions.
+	* Sets columnRegionTop to the current cursor position so that
+	* column advancement stays below existing content (for continuous breaks).
+	*/
+	function updateColumns(newColumns) {
+		columns = newColumns;
+		columnWidth = calculateColumnWidth(pageSize.w, margins.left, margins.right, columns);
+		const state = getCurrentState();
+		if (columns.count > 1) state.page.columns = { ...columns };
+		else delete state.page.columns;
+		columnRegionTop = state.cursorY;
+		state.columnIndex = 0;
+	}
+	function updatePageLayout(newPageSize, newMargins, applyImmediately = true) {
+		if (!applyImmediately) {
+			pendingPageSize = newPageSize ? { ...newPageSize } : pendingPageSize;
+			pendingMargins = newMargins ? { ...newMargins } : pendingMargins;
+			return;
+		}
+		if (newPageSize) pageSize = { ...newPageSize };
+		if (newMargins) margins = { ...newMargins };
+		if (getContentHeight() <= 0) panic("Paginator: section page size and margins yield no content area");
+		recalculateColumnWidth();
+		pendingPageSize = void 0;
+		pendingMargins = void 0;
+	}
+	function startSection(sectionIndex) {
+		currentSectionIndex = sectionIndex;
+		currentSectionPageNumber = 0;
+	}
+	function applySectionMetadata(page) {
+		page.sectionIndex = currentSectionIndex;
+		page.sectionPageNumber = currentSectionPageNumber;
+		const refs = options.sectionHeaderFooterRefs?.[currentSectionIndex];
+		if (refs) page.headerFooterRefs = refs;
+		else delete page.headerFooterRefs;
+	}
+	return {
+		/** All pages created so far. */
+		pages,
+		/** All page states. */
+		states,
+		/** Column width in pixels (use getColumnWidth() for current value after updates). */
+		get columnWidth() {
+			return columnWidth;
+		},
+		/** Get current column layout (returns copy to prevent external mutation). */
+		get columns() {
+			return { ...columns };
+		},
+		/** Get current state. */
+		getCurrentState,
+		/** Get available height in current column. */
+		getAvailableHeight: () => getAvailableHeight(getCurrentState()),
+		/** Full content height of a fresh page in the active section. */
+		getContentHeight,
+		/** Get content width for the active section. */
+		getContentWidth,
+		/** Check if height fits in current column. */
+		fits: (height) => fits(height),
+		/** Ensure height fits, advancing if needed. */
+		ensureFits,
+		/** Add a fragment to current page. */
+		addFragment,
+		/** Reserve additional footnote area on the current page. */
+		addFootnoteHeight,
+		/** Force a page break. */
+		forcePageBreak,
+		/** Reuse an already blank current page for the active section/layout. */
+		retargetCurrentBlankPage,
+		/** Force a column break. */
+		forceColumnBreak,
+		/** Get X position for column. */
+		getColumnX,
+		/** Update column layout (for section breaks). */
+		updateColumns,
+		/** Update page size/margins for subsequent pages. */
+		updatePageLayout,
+		/** Mark the next created page as the first page of a new section. */
+		startSection
+	};
+}
+//#endregion
+export { FOOTNOTE_SEPARATOR_HEIGHT, createPaginator };

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

@@ -0,0 +1,9 @@
+import { ParagraphBlock, ParagraphMeasure } from "./types.js";
+
+//#region src/layout-engine/paragraphFragmentRange.d.ts
+declare function getParagraphFragmentPmRange(block: ParagraphBlock, measure: ParagraphMeasure, fromLine: number, toLine: number): {
+  pmStart?: number;
+  pmEnd?: number;
+};
+//#endregion
+export { getParagraphFragmentPmRange };

package/dist/layout-engine/paragraphFragmentRange.js

@@ -0,0 +1,40 @@
+//#region src/layout-engine/paragraphFragmentRange.ts
+function clampCharOffset(value, length) {
+	if (value == null || !Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(length, value));
+}
+function runBoundaryPmPos(run, charOffset, edge) {
+	if (!run) return;
+	if (run.kind === "text") {
+		if (typeof run.pmStart === "number") return run.pmStart + clampCharOffset(charOffset, run.text.length);
+		return edge === "end" ? run.pmEnd : void 0;
+	}
+	if (edge === "end") {
+		if (typeof run.pmEnd === "number") return run.pmEnd;
+		return typeof run.pmStart === "number" ? run.pmStart + 1 : void 0;
+	}
+	return run.pmStart;
+}
+function getParagraphFragmentPmRange(block, measure, fromLine, toLine) {
+	if (measure.lines.length === 0 || fromLine >= toLine) {
+		const res = {};
+		if (block.pmStart !== void 0) res.pmStart = block.pmStart;
+		if (block.pmEnd !== void 0) res.pmEnd = block.pmEnd;
+		return res;
+	}
+	const firstLine = measure.lines[fromLine];
+	const lastLine = measure.lines[toLine - 1];
+	const firstRun = firstLine ? block.runs[firstLine.fromRun] : void 0;
+	const lastRun = lastLine ? block.runs[lastLine.toRun] : void 0;
+	let pmStart = fromLine === 0 ? block.pmStart ?? runBoundaryPmPos(firstRun, firstLine?.fromChar ?? 0, "start") : runBoundaryPmPos(firstRun, firstLine?.fromChar ?? 0, "start");
+	let pmEnd = toLine >= measure.lines.length ? block.pmEnd ?? runBoundaryPmPos(lastRun, lastLine?.toChar ?? 0, "end") : runBoundaryPmPos(lastRun, lastLine?.toChar ?? 0, "end");
+	if (pmStart == null) pmStart = block.pmStart;
+	if (pmEnd == null) pmEnd = block.pmEnd;
+	if (pmStart != null && pmEnd != null && pmEnd <= pmStart) pmEnd = pmStart + 1;
+	const result = {};
+	if (pmStart !== void 0) result.pmStart = pmStart;
+	if (pmEnd !== void 0) result.pmEnd = pmEnd;
+	return result;
+}
+//#endregion
+export { getParagraphFragmentPmRange };

package/dist/layout-engine/section-breaks.d.ts

@@ -0,0 +1,78 @@
+import { ColumnLayout, PageMargins, SectionBreakBlock } from "./types.js";
+
+//#region src/layout-engine/section-breaks.d.ts
+/**
+ * State tracking for sections during layout.
+ * Uses active/pending pattern to schedule changes at page boundaries.
+ */
+type SectionState = {
+  /** Currently active top margin. */activeTopMargin: number; /** Currently active bottom margin. */
+  activeBottomMargin: number; /** Currently active left margin. */
+  activeLeftMargin: number; /** Currently active right margin. */
+  activeRightMargin: number; /** Scheduled top margin for next page. */
+  pendingTopMargin: number | null; /** Scheduled bottom margin for next page. */
+  pendingBottomMargin: number | null; /** Scheduled left margin for next page. */
+  pendingLeftMargin: number | null; /** Scheduled right margin for next page. */
+  pendingRightMargin: number | null; /** Currently active page size. */
+  activePageSize: {
+    w: number;
+    h: number;
+  }; /** Scheduled page size for next page. */
+  pendingPageSize: {
+    w: number;
+    h: number;
+  } | null; /** Currently active column layout. */
+  activeColumns: ColumnLayout; /** Scheduled column layout for next page. */
+  pendingColumns: ColumnLayout | null; /** Currently active orientation. */
+  activeOrientation: "portrait" | "landscape" | null; /** Scheduled orientation for next page. */
+  pendingOrientation: "portrait" | "landscape" | null; /** Whether any pages have been created yet. */
+  hasAnyPages: boolean;
+};
+/**
+ * Decision about what happens at a section break.
+ */
+type BreakDecision = {
+  /** Force a page break. */forcePageBreak: boolean; /** Force a mid-page region change (for column layout changes). */
+  forceMidPageRegion: boolean; /** Required page parity (even or odd). */
+  requiredParity?: "even" | "odd";
+};
+/**
+ * Create initial section state from default options.
+ */
+declare function createInitialSectionState(margins: PageMargins, pageSize: {
+  w: number;
+  h: number;
+}, columns?: ColumnLayout): SectionState;
+/**
+ * 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.
+ */
+declare function scheduleSectionBreak(block: SectionBreakBlock, state: SectionState, _baseMargins: PageMargins): {
+  decision: BreakDecision;
+  state: SectionState;
+};
+/**
+ * Apply pending section state to active state at a page boundary.
+ * Transfers all pending values to active and clears pending.
+ */
+declare function applyPendingToActive(state: SectionState): SectionState;
+/**
+ * Get the effective margins for the current section state.
+ * Returns active margins, or pending if scheduled.
+ */
+declare function getEffectiveMargins(state: SectionState): PageMargins;
+/**
+ * Get the effective page size for the current section state.
+ */
+declare function getEffectivePageSize(state: SectionState): {
+  w: number;
+  h: number;
+};
+/**
+ * Get the effective columns for the current section state.
+ */
+declare function getEffectiveColumns(state: SectionState): ColumnLayout;
+//#endregion
+export { BreakDecision, SectionState, applyPendingToActive, createInitialSectionState, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, scheduleSectionBreak };