@stll/folio-core 0.48.0 → 0.50.0

package/dist/layout-engine/measure/paragraphMeasureShared.d.ts

@@ -0,0 +1,109 @@
+import { FieldRun, ImageRun, LineBreakRun, MathRun, MeasuredLine, Run, TabRun, TextRun } from "../types.js";
+import { FontMetrics, FontStyle } from "./measureTypes.js";
+import { FloatingLineSegmentZone } from "./floatingZones.js";
+//#region src/layout-engine/measure/paragraphMeasureShared.d.ts
+declare const DEFAULT_FONT_SIZE = 11;
+declare const DEFAULT_LINE_HEIGHT_MULTIPLIER = 1;
+declare const WIDTH_TOLERANCE = 0.5;
+/**
+ * Typography metrics for a line
+ */
+type LineTypography = {
+  ascent: number;
+  descent: number;
+  lineHeight: number;
+};
+/**
+ * State tracking for line accumulation
+ */
+type LineState = {
+  fromRun: number;
+  fromChar: number;
+  toRun: number;
+  toChar: number;
+  width: number;
+  /** Width of collapsible ASCII whitespace at the current line tail. */
+  trailingWhitespaceWidth: number;
+  /** Spaces the layout may compress while justifying this line. */
+  regularSpaceWidth: number;
+  /** Paint plan set only when final-text contraction admits a candidate. */
+  justificationPaint?: NonNullable<MeasuredLine["justificationPaint"]>;
+  maxFontSize: number;
+  maxFontMetrics: FontMetrics | null;
+  /**
+   * Largest tab font on the line. Tabs are whitespace: their font sizes the
+   * line only when no other run on it does (a line of nothing but tabs).
+   */
+  maxTabFontSize: number;
+  maxTabFontMetrics: FontMetrics | null;
+  /** Maximum inline image height in pixels (already in px, not points) */
+  maxImageHeightPx: number;
+  /** Maximum exact-height embedded-object preview on the line. */
+  maxExactImageHeightPx: number;
+  /** Maximum inline math height in pixels (already in px, not points) */
+  maxMathHeightPx: number;
+  availableWidth: number;
+  /** Left offset from floating images (pixels from content left edge) */
+  leftOffset: number;
+  /** Right offset from floating images (pixels from content right edge) */
+  rightOffset: number;
+  /** Optional split segment zones from centered floating exclusions */
+  segmentZones?: FloatingLineSegmentZone[];
+  discretionaryHyphen?: {
+    runIndex: number;
+  };
+  renderedPageBreakBefore?: boolean;
+};
+/**
+ * Extract FontStyle from a run that carries RunFormatting (text, tab, or
+ * field). All three share the same formatting shape, so they measure the
+ * same way; widening the parameter keeps tab-following measurement
+ * (FieldRun page numbers, etc.) consistent with TextRun handling.
+ */
+declare function runToFontStyle(run: TextRun | TabRun | FieldRun | MathRun): FontStyle;
+/**
+ * Check if a run is a text run
+ */
+declare function isTextRun(run: Run): run is TextRun;
+/**
+ * Check if a run is a tab run
+ */
+declare function isTabRun(run: Run): run is TabRun;
+/**
+ * Check if a run is an image run
+ */
+declare function isImageRun(run: Run): run is ImageRun;
+/**
+ * Check if a run is a line break run
+ */
+declare function isLineBreakRun(run: Run): run is LineBreakRun;
+/**
+ * Check if a run is a field run
+ */
+declare function isFieldRun(run: Run): run is FieldRun;
+/** Text a field run is measured at: its resolved value when known (so the
+ *  measurer agrees with the painter), else the cached fallback. */
+declare function fieldMeasureText(run: FieldRun, fieldValues: ReadonlyMap<number, string> | undefined): string;
+/**
+ * Check if a run is a math equation run
+ */
+declare function isMathRun(run: Run): run is MathRun;
+/**
+ * Check if text run is empty (only whitespace or no text)
+ */
+declare function isEmptyTextRun(run: TextRun): boolean;
+/**
+ * Sum the inline pixel widths of runs after a tab, up to (but not including)
+ * the next tab or line break. Measured per-run so widths reserved match what
+ * the painter draws even when trailing runs use different fonts/sizes.
+ *
+ * Floating/anchored images are skipped — the painter lifts them out of the
+ * paragraph flow (see `isFloatingImageRun`) and `measureFollowingContentWidth`
+ * in the painter already excludes them, so counting their width here would
+ * desync measurer and painter on tab advance for paragraphs with a tab
+ * preceding a floating image.
+ */
+declare function isBlockLayoutImageRun(run: ImageRun): boolean;
+declare function isSpaceOrTab(char: string | undefined): boolean;
+//#endregion
+export { DEFAULT_FONT_SIZE, DEFAULT_LINE_HEIGHT_MULTIPLIER, LineState, LineTypography, WIDTH_TOLERANCE, fieldMeasureText, isBlockLayoutImageRun, isEmptyTextRun, isFieldRun, isImageRun, isLineBreakRun, isMathRun, isSpaceOrTab, isTabRun, isTextRun, runToFontStyle };

package/dist/layout-engine/measure/paragraphMeasureShared.js

@@ -0,0 +1,82 @@
+import { isFloatingImageRun } from "../types.js";
+import { DEFAULT_FONT_FAMILY, buildRunFontStyle } from "./measureHelpers.js";
+//#region src/layout-engine/measure/paragraphMeasureShared.ts
+const DEFAULT_FONT_SIZE = 11;
+const DEFAULT_LINE_HEIGHT_MULTIPLIER = 1;
+const WIDTH_TOLERANCE = .5;
+/**
+* Extract FontStyle from a run that carries RunFormatting (text, tab, or
+* field). All three share the same formatting shape, so they measure the
+* same way; widening the parameter keeps tab-following measurement
+* (FieldRun page numbers, etc.) consistent with TextRun handling.
+*/
+function runToFontStyle(run) {
+	return buildRunFontStyle(run, DEFAULT_FONT_FAMILY, 11);
+}
+/**
+* Check if a run is a text run
+*/
+function isTextRun(run) {
+	return run.kind === "text";
+}
+/**
+* Check if a run is a tab run
+*/
+function isTabRun(run) {
+	return run.kind === "tab";
+}
+/**
+* Check if a run is an image run
+*/
+function isImageRun(run) {
+	return run.kind === "image";
+}
+/**
+* Check if a run is a line break run
+*/
+function isLineBreakRun(run) {
+	return run.kind === "lineBreak";
+}
+/**
+* Check if a run is a field run
+*/
+function isFieldRun(run) {
+	return run.kind === "field";
+}
+/** Text a field run is measured at: its resolved value when known (so the
+*  measurer agrees with the painter), else the cached fallback. */
+function fieldMeasureText(run, fieldValues) {
+	return (run.pmStart === void 0 ? void 0 : fieldValues?.get(run.pmStart)) ?? (run.fallback || "1");
+}
+/**
+* Check if a run is a math equation run
+*/
+function isMathRun(run) {
+	return run.kind === "math";
+}
+/**
+* Check if text run is empty (only whitespace or no text)
+*/
+function isEmptyTextRun(run) {
+	return !run.text || run.text.replace(/\u00a0/gu, " ").trim().length === 0;
+}
+/**
+* Sum the inline pixel widths of runs after a tab, up to (but not including)
+* the next tab or line break. Measured per-run so widths reserved match what
+* the painter draws even when trailing runs use different fonts/sizes.
+*
+* Floating/anchored images are skipped — the painter lifts them out of the
+* paragraph flow (see `isFloatingImageRun`) and `measureFollowingContentWidth`
+* in the painter already excludes them, so counting their width here would
+* desync measurer and painter on tab advance for paragraphs with a tab
+* preceding a floating image.
+*/
+function isBlockLayoutImageRun(run) {
+	if (isFloatingImageRun(run)) return false;
+	return run.wrapType === "topAndBottom" || run.displayMode === "block";
+}
+function isSpaceOrTab(char) {
+	return char === " " || char === "	";
+}
+//#endregion
+export { DEFAULT_FONT_SIZE, DEFAULT_LINE_HEIGHT_MULTIPLIER, WIDTH_TOLERANCE, fieldMeasureText, isBlockLayoutImageRun, isEmptyTextRun, isFieldRun, isImageRun, isLineBreakRun, isMathRun, isSpaceOrTab, isTabRun, isTextRun, runToFontStyle };

package/dist/layout-engine/measure/paragraphTabs.d.ts

@@ -0,0 +1,18 @@
+import { Run } from "../types.js";
+//#region src/layout-engine/measure/paragraphTabs.d.ts
+declare function measureInlineWidthAfterTab(runs: Run[], tabIndex: number, fieldValues?: ReadonlyMap<number, string>): number;
+declare function hasFollowingTabOnLine(runs: Run[], tabIndex: number): boolean;
+declare function hasPriorTabOnLine(runs: Run[], tabIndex: number): boolean;
+declare function canClampTabToRightEdge(alignment: string, currentLineWidth: number, hasPriorTab: boolean, followingWidth: number, availableWidth: number): boolean;
+/**
+ * Width of the inline content preceding the first `.` in the runs that follow
+ * a tab, used to anchor `decimal` tab stops. Mirrors `getTextAfterTab` +
+ * decimal-prefix measurement in the painter (`renderParagraph.ts`) so the
+ * measurer and painter agree on tab advance for decimal stops.
+ *
+ * Returns 0 when no decimal separator appears before the next tab / line
+ * break — `calculateTabWidth` treats that as "no anchor adjustment".
+ */
+declare function measureDecimalPrefixWidthAfterTab(runs: Run[], tabIndex: number, fieldValues?: ReadonlyMap<number, string>): number;
+//#endregion
+export { canClampTabToRightEdge, hasFollowingTabOnLine, hasPriorTabOnLine, measureDecimalPrefixWidthAfterTab, measureInlineWidthAfterTab };

package/dist/layout-engine/measure/paragraphTabs.js

@@ -0,0 +1,78 @@
+import { inlineImageBoundingBox } from "../../utils/rotationBoundingBox.js";
+import { isFloatingImageRun } from "../types.js";
+import { measureTextWidth } from "./measureProvider.js";
+import { fieldMeasureText, isBlockLayoutImageRun, isFieldRun, isImageRun, isLineBreakRun, isMathRun, isTabRun, isTextRun, runToFontStyle } from "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/paragraphTabs.ts
+/**
+* Tab measurement on a line: the width of content following a tab, decimal
+* tab prefixes, neighbouring tabs, and right-edge clamping.
+*/
+function measureInlineWidthAfterTab(runs, tabIndex, fieldValues) {
+	let width = 0;
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isTabRun(next) || isLineBreakRun(next)) break;
+		if (isImageRun(next)) {
+			if (isBlockLayoutImageRun(next)) break;
+			if (!isFloatingImageRun(next)) width += inlineImageBoundingBox(next).width || 0;
+			continue;
+		}
+		if (isTextRun(next)) width += measureTextWidth(next.text || "", runToFontStyle(next));
+		else if (isFieldRun(next)) width += measureTextWidth(fieldMeasureText(next, fieldValues), runToFontStyle(next));
+		else if (isMathRun(next)) width += measureTextWidth(next.plainText || "[equation]", runToFontStyle(next));
+	}
+	return width;
+}
+function hasFollowingTabOnLine(runs, tabIndex) {
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isLineBreakRun(next)) break;
+		if (isImageRun(next) && isBlockLayoutImageRun(next)) break;
+		if (isTabRun(next)) return true;
+	}
+	return false;
+}
+function hasPriorTabOnLine(runs, tabIndex) {
+	for (let i = tabIndex - 1; i >= 0; i--) {
+		const prior = runs[i];
+		if (!prior || isLineBreakRun(prior) || isImageRun(prior) && isBlockLayoutImageRun(prior)) break;
+		if (isTabRun(prior)) return true;
+	}
+	return false;
+}
+function canClampTabToRightEdge(alignment, currentLineWidth, hasPriorTab, followingWidth, availableWidth) {
+	if (alignment === "start" || alignment === "default") return currentLineWidth > .5 && (hasPriorTab || followingWidth <= availableWidth);
+	return true;
+}
+/**
+* Width of the inline content preceding the first `.` in the runs that follow
+* a tab, used to anchor `decimal` tab stops. Mirrors `getTextAfterTab` +
+* decimal-prefix measurement in the painter (`renderParagraph.ts`) so the
+* measurer and painter agree on tab advance for decimal stops.
+*
+* Returns 0 when no decimal separator appears before the next tab / line
+* break — `calculateTabWidth` treats that as "no anchor adjustment".
+*/
+function measureDecimalPrefixWidthAfterTab(runs, tabIndex, fieldValues) {
+	let text = "";
+	let firstRun;
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isTabRun(next) || isLineBreakRun(next)) break;
+		if (isTextRun(next)) {
+			text += next.text || "";
+			firstRun ??= next;
+		} else if (isFieldRun(next)) {
+			text += fieldMeasureText(next, fieldValues);
+			firstRun ??= next;
+		} else if (isMathRun(next)) {
+			text += next.plainText || "[equation]";
+			firstRun ??= next;
+		}
+	}
+	const decimalIndex = text.indexOf(".");
+	if (decimalIndex === -1 || !firstRun) return 0;
+	return measureTextWidth(text.slice(0, decimalIndex), runToFontStyle(firstRun));
+}
+//#endregion
+export { canClampTabToRightEdge, hasFollowingTabOnLine, hasPriorTabOnLine, measureDecimalPrefixWidthAfterTab, measureInlineWidthAfterTab };

package/dist/layout-engine/measure/smallCapsCasing.d.ts

@@ -0,0 +1,56 @@
+//#region src/layout-engine/measure/smallCapsCasing.d.ts
+/**
+ * Casing rules for synthesized `w:smallCaps` glyphs.
+ *
+ * A face that carries no `smcp`/`c2sc` substitution has no true small-capital
+ * glyph, so it is faked: a lowercase letter is drawn as its uppercase form at
+ * a smaller point size, on the run's own baseline, at a fixed fraction of the
+ * run's declared size — 0.8, an exact ratio observed to repeat across mixed
+ * two-size runs at every point size and never round to a half-point `w:sz`
+ * step. That is not a canvas or DOM backend's own `font-variant: small-caps`,
+ * which synthesizes at its own, uncontrollable, narrower ratio (Blink and
+ * WebKit use 0.7).
+ *
+ * Pure: no canvas, no DOM. Shared by every measurement and paint backend so a
+ * run's advances and its glyphs agree on which characters shrink.
+ */
+/** Fraction of the run's declared size a synthesized small capital draws at. */
+declare const SMALL_CAPS_SCALE = 0.8;
+/**
+ * Whether `char` is a cased letter in its lowercase form — the class
+ * `w:smallCaps` draws as a shrunken, uppercased capital. Digits, punctuation,
+ * symbols and already-uppercase letters keep the run's full size; combining
+ * `char`'s upper and lower forms this way (rather than comparing to a
+ * separate "is uppercase" test) is what correctly leaves caseless scripts
+ * (CJK, most punctuation) at full size too, since neither form differs from
+ * the character itself there.
+ */
+declare function isSmallCapsLetter(char: string): boolean;
+/**
+ * Per-code-point small-caps classification for `text`, one entry per code
+ * point (iterated the same way `[...text]`/`for...of` does, so it lines up
+ * with any other code-point walk of the same string).
+ *
+ * Whitespace carries no case of its own; a run's space draws at the size of
+ * the character immediately before it — the trailing space after a
+ * synthesized word is itself synthesized — so a whitespace code point here
+ * takes the previous code point's class, and only falls back to full size
+ * when it opens the string (nothing to inherit from).
+ */
+declare function smallCapsMask(text: string): boolean[];
+/** A maximal run of `text` drawn at one size: `small` selects which. */
+type SmallCapsSegment = {
+  readonly text: string;
+  readonly small: boolean;
+};
+/**
+ * `text` split into maximal same-size segments for painting, each already
+ * uppercased where `small` — the shrunken capital a `smcp`-less face
+ * substitutes for the source lowercase letter. A run with no lowercase letter
+ * at all (already-uppercase headings, digits, punctuation) comes back as one
+ * `small: false` segment, so a caller can skip the extra painting work its
+ * mixed-size runs need.
+ */
+declare function smallCapsSegments(text: string): SmallCapsSegment[];
+//#endregion
+export { SMALL_CAPS_SCALE, SmallCapsSegment, isSmallCapsLetter, smallCapsMask, smallCapsSegments };

package/dist/layout-engine/measure/smallCapsCasing.js

@@ -0,0 +1,88 @@
+//#region src/layout-engine/measure/smallCapsCasing.ts
+/**
+* Casing rules for synthesized `w:smallCaps` glyphs.
+*
+* A face that carries no `smcp`/`c2sc` substitution has no true small-capital
+* glyph, so it is faked: a lowercase letter is drawn as its uppercase form at
+* a smaller point size, on the run's own baseline, at a fixed fraction of the
+* run's declared size — 0.8, an exact ratio observed to repeat across mixed
+* two-size runs at every point size and never round to a half-point `w:sz`
+* step. That is not a canvas or DOM backend's own `font-variant: small-caps`,
+* which synthesizes at its own, uncontrollable, narrower ratio (Blink and
+* WebKit use 0.7).
+*
+* Pure: no canvas, no DOM. Shared by every measurement and paint backend so a
+* run's advances and its glyphs agree on which characters shrink.
+*/
+/** Fraction of the run's declared size a synthesized small capital draws at. */
+const SMALL_CAPS_SCALE = .8;
+/** Whitespace never gets its own small-caps class; see `smallCapsMask`. */
+const WHITESPACE_PATTERN = /\s/u;
+/**
+* Whether `char` is a cased letter in its lowercase form — the class
+* `w:smallCaps` draws as a shrunken, uppercased capital. Digits, punctuation,
+* symbols and already-uppercase letters keep the run's full size; combining
+* `char`'s upper and lower forms this way (rather than comparing to a
+* separate "is uppercase" test) is what correctly leaves caseless scripts
+* (CJK, most punctuation) at full size too, since neither form differs from
+* the character itself there.
+*/
+function isSmallCapsLetter(char) {
+	return char.toLocaleUpperCase() !== char;
+}
+/**
+* Per-code-point small-caps classification for `text`, one entry per code
+* point (iterated the same way `[...text]`/`for...of` does, so it lines up
+* with any other code-point walk of the same string).
+*
+* Whitespace carries no case of its own; a run's space draws at the size of
+* the character immediately before it — the trailing space after a
+* synthesized word is itself synthesized — so a whitespace code point here
+* takes the previous code point's class, and only falls back to full size
+* when it opens the string (nothing to inherit from).
+*/
+function smallCapsMask(text) {
+	const mask = [];
+	let previous = false;
+	for (const char of text) {
+		const small = WHITESPACE_PATTERN.test(char) ? previous : isSmallCapsLetter(char);
+		mask.push(small);
+		previous = small;
+	}
+	return mask;
+}
+/**
+* `text` split into maximal same-size segments for painting, each already
+* uppercased where `small` — the shrunken capital a `smcp`-less face
+* substitutes for the source lowercase letter. A run with no lowercase letter
+* at all (already-uppercase headings, digits, punctuation) comes back as one
+* `small: false` segment, so a caller can skip the extra painting work its
+* mixed-size runs need.
+*/
+function smallCapsSegments(text) {
+	const mask = smallCapsMask(text);
+	const segments = [];
+	let current = "";
+	let currentSmall;
+	let index = 0;
+	for (const char of text) {
+		const small = mask[index] ?? false;
+		if (currentSmall !== void 0 && small !== currentSmall) {
+			segments.push({
+				text: current,
+				small: currentSmall
+			});
+			current = "";
+		}
+		current += small ? char.toLocaleUpperCase() : char;
+		currentSmall = small;
+		index += 1;
+	}
+	if (current) segments.push({
+		text: current,
+		small: currentSmall ?? false
+	});
+	return segments;
+}
+//#endregion
+export { SMALL_CAPS_SCALE, isSmallCapsLetter, smallCapsMask, smallCapsSegments };

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

@@ -51,6 +51,8 @@ type PaginatorOptions = {
   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;
   /** Column configuration (optional). */

package/dist/layout-engine/paginator.js

@@ -94,7 +94,11 @@ function createPaginator(options) {
 	}
 	function getPageMargins(pageNumber, logicalPageNumber) {
 		const evenMargins = logicalPageNumber % 2 === 0 ? options.sectionEvenPageMargins?.[currentSectionIndex] : void 0;
-		const pageMargins = pageNumber === 1 && options.firstPageMargins ? { ...options.firstPageMargins } : { ...evenMargins ?? margins };
+		const titlePageMargins = currentSectionPageNumber === 1 ? options.sectionFirstPageMargins?.[currentSectionIndex] : void 0;
+		let pageMargins;
+		if (titlePageMargins) pageMargins = { ...titlePageMargins };
+		else if (pageNumber === 1 && options.firstPageMargins) pageMargins = { ...options.firstPageMargins };
+		else pageMargins = { ...evenMargins ?? margins };
 		if (options.mirrorMargins === true && pageNumber % 2 === 0) return {
 			...pageMargins,
 			left: pageMargins.right,

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

@@ -0,0 +1,23 @@
+import { ParagraphBlock, ParagraphMeasure } from "./types.js";
+import { createPaginator } from "./paginator.js";
+//#region src/layout-engine/paragraphLayout.d.ts
+/**
+ * Layout a paragraph block onto pages.
+ *
+ * When `footnoteHeightById` is provided, each line carrying a footnote
+ * ref additionally reserves space on its host page for the fn's
+ * content. Pagination decisions include only the reservation growth
+ * beyond any retry floor, so a line cannot land on a page that lacks
+ * room for both body and note content.
+ */
+type LayoutParagraphOptions = {
+  block: ParagraphBlock;
+  measure: ParagraphMeasure;
+  paginator: ReturnType<typeof createPaginator>;
+  contentWidth: number;
+  footnoteHeightById: Map<number, number> | undefined;
+  suppressSpaceBefore: boolean;
+};
+declare function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeightById, suppressSpaceBefore }: LayoutParagraphOptions): void;
+//#endregion
+export { layoutParagraph };