@stll/folio-core 0.32.2 → 0.33.0

package/dist/display-list/build/furniture.d.ts

@@ -0,0 +1,86 @@
+import { document_d_exports } from "../../types/document.js";
+import { FootnoteContent, HeaderFooterContent, Page } from "../../layout-engine/types.js";
+import { DisplayPrimitive } from "../types.js";
+import { BuildContext } from "./buildContext.js";
+import { PageBorders } from "./pageBorderPrimitives.js";
+import { PageComposer } from "./regions.js";
+//#region src/display-list/build/furniture.d.ts
+/**
+ * Everything the builder cannot derive from a `Layout`. Every field is
+ * optional, and every one of them means the same thing when absent: the
+ * construct is not painted, and it is reported wherever the layout or the
+ * caller's `documentFeatures` shows the document had one.
+ */
+type PageFurnitureInputs = {
+  /**
+   * `w:pgBorders` for the section. Absent: no border is painted, and the gap is
+   * reported unless `documentFeatures` says the document has none.
+   */
+  readonly pageBorders?: PageBorders;
+  /** Resolves `w:themeColor` on a page border. Absent: authored colours only. */
+  readonly theme?: document_d_exports.Theme | null;
+  /**
+   * The watermark for every page with no more specific match in
+   * {@link watermarkByHeaderRId}. Absent with that map also absent: no
+   * watermark is painted, and the gap is reported unless `documentFeatures`
+   * says the document has none.
+   */
+  readonly watermark?: document_d_exports.Watermark;
+  /**
+   * Per-header-rId watermarks, authoritative when present: a page whose active
+   * header carries none paints none, rather than inheriting {@link watermark}.
+   */
+  readonly watermarkByHeaderRId?: ReadonlyMap<string, document_d_exports.Watermark>;
+  /**
+   * Resolved `data:` source for a picture watermark. Absent: the picture is
+   * reported, because the relationship id → asset mapping belongs to the
+   * package layer and the builder does no I/O.
+   */
+  readonly watermarkImageSrc?: string;
+  /**
+   * The header for every page, or for pages 2+ when `titlePg` is set. Absent
+   * with the per-rId map also absent: no header is painted, and a page whose
+   * `headerFooterRefs` name one says so through `unsupported`.
+   */
+  readonly headerContent?: HeaderFooterContent;
+  /** The footer counterpart of {@link headerContent}. */
+  readonly footerContent?: HeaderFooterContent;
+  /** Headers by part relationship id, for section-scoped and even/odd headers. */
+  readonly headerContentByRId?: ReadonlyMap<string, HeaderFooterContent>;
+  /** Footers by part relationship id. */
+  readonly footerContentByRId?: ReadonlyMap<string, HeaderFooterContent>;
+  /** The first page's header when `titlePg` is set and the layout carries no section refs. */
+  readonly firstPageHeaderContent?: HeaderFooterContent;
+  /** The first page's footer when `titlePg` is set and the layout carries no section refs. */
+  readonly firstPageFooterContent?: HeaderFooterContent;
+  /** `w:titlePg` for the first section. Absent: the first page is not special-cased. */
+  readonly titlePg?: boolean;
+  /** Overrides `w:pgMar`'s `w:header`. Absent: the page's own margin is used. */
+  readonly headerDistancePx?: number;
+  /** Overrides `w:pgMar`'s `w:footer`. Absent: the page's own margin is used. */
+  readonly footerDistancePx?: number;
+  /**
+   * Footnote bodies by `w:footnote` id. Absent, or missing an id a page
+   * carries: the band still opens with its rule and reserves the paginator's
+   * height, and the missing bodies are reported.
+   */
+  readonly footnoteContentById?: ReadonlyMap<number, FootnoteContent>;
+};
+/**
+ * Furniture split by where it sits in the page's paint order: `behind` goes
+ * under the body, `above` over it. `renderPage.ts` establishes both.
+ */
+type PageFurniturePrimitives = {
+  /** Painted under the body: a back page border, the watermark. */
+  readonly behind: readonly DisplayPrimitive[];
+  /** Painted over it, into the composer, so its regions nest. */
+  readonly above: (composer: PageComposer) => void;
+};
+type PaintPageFurnitureOptions = {
+  readonly page: Page;
+  readonly furniture: PageFurnitureInputs;
+  readonly context: BuildContext;
+};
+declare const paintPageFurniture: ({ page, furniture, context }: PaintPageFurnitureOptions) => PageFurniturePrimitives;
+//#endregion
+export { PageFurnitureInputs, PageFurniturePrimitives, PaintPageFurnitureOptions, paintPageFurniture };

package/dist/display-list/build/furniture.js

@@ -0,0 +1,98 @@
+import { applySectionHeaderFooterOptions, selectSectionHeaderFooterRIds } from "../../layout-painter/renderPage.js";
+import { paintHeaderFooter } from "./headerFooterPrimitives.js";
+import { paintPageBorders } from "./pageBorderPrimitives.js";
+import { paintFootnoteArea } from "./pageFurniture.js";
+import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
+import { paintWatermark } from "./watermarkPrimitives.js";
+//#region src/display-list/build/furniture.ts
+const suppliesHeaderFooter = (furniture) => furniture.headerContent !== void 0 || furniture.footerContent !== void 0 || furniture.headerContentByRId !== void 0 || furniture.footerContentByRId !== void 0 || furniture.firstPageHeaderContent !== void 0 || furniture.firstPageFooterContent !== void 0;
+const suppliesWatermark = (furniture) => furniture.watermark !== void 0 || furniture.watermarkByHeaderRId !== void 0;
+/**
+* The header, footer and watermark this page paints, chosen by the painter's
+* own rule (`w:titlePg` first-page swap, `w:evenAndOddHeaders`, section-scoped
+* parts) rather than by a second implementation of it.
+*/
+const selectForPage = (page, furniture) => {
+	const source = {
+		...furniture.headerContent === void 0 ? {} : { headerContent: furniture.headerContent },
+		...furniture.footerContent === void 0 ? {} : { footerContent: furniture.footerContent },
+		...furniture.headerContentByRId === void 0 ? {} : { headerContentByRId: furniture.headerContentByRId },
+		...furniture.footerContentByRId === void 0 ? {} : { footerContentByRId: furniture.footerContentByRId },
+		...furniture.watermark === void 0 ? {} : { watermark: furniture.watermark },
+		...furniture.watermarkByHeaderRId === void 0 ? {} : { watermarkByHeaderRId: furniture.watermarkByHeaderRId }
+	};
+	const selected = { ...source };
+	if (applySectionHeaderFooterOptions(page, selected, source)) return selected;
+	if (furniture.titlePg !== true || page.number !== 1) return selected;
+	if (furniture.firstPageHeaderContent === void 0) delete selected.headerContent;
+	else selected.headerContent = furniture.firstPageHeaderContent;
+	if (furniture.firstPageFooterContent === void 0) delete selected.footerContent;
+	else selected.footerContent = furniture.firstPageFooterContent;
+	return selected;
+};
+/**
+* Name a header or footer the page asks for and the caller did not supply. A
+* backend cannot tell a page with no header from a page whose header never
+* reached the producer.
+*/
+const reportMissingStories = (page, furniture, selected, context) => {
+	if (page.headerFooterRefs === void 0) return;
+	if (!suppliesHeaderFooter(furniture)) {
+		context.unsupported.report(UNSUPPORTED_CONSTRUCT.headerFooterContent, context.pageIndex, "the page names header and footer parts, but no story content was supplied to the builder");
+		return;
+	}
+	const { headerRId, footerRId } = selectSectionHeaderFooterRIds(page);
+	const namesHeader = headerRId !== void 0;
+	const namesFooter = footerRId !== void 0;
+	const headerCarriedAWatermark = headerRId !== void 0 && furniture.watermarkByHeaderRId?.has(headerRId) === true;
+	if (namesHeader && !headerCarriedAWatermark && selected.headerContent === void 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.headerFooterContent, context.pageIndex, "the header part this page selects was not among the supplied stories");
+	if (namesFooter && selected.footerContent === void 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.headerFooterContent, context.pageIndex, "the footer part this page selects was not among the supplied stories");
+};
+const paintPageFurniture = ({ page, furniture, context }) => {
+	const selected = selectForPage(page, furniture);
+	reportMissingStories(page, furniture, selected, context);
+	const borders = furniture.pageBorders === void 0 ? [] : paintPageBorders({
+		page,
+		borders: furniture.pageBorders,
+		...furniture.theme === void 0 ? {} : { theme: furniture.theme },
+		context
+	});
+	const paintsBorderBehind = furniture.pageBorders?.zOrder === "back";
+	const watermark = !suppliesWatermark(furniture) || selected.watermark === void 0 ? [] : paintWatermark({
+		page,
+		watermark: selected.watermark,
+		...furniture.watermarkImageSrc === void 0 ? {} : { imageSrc: furniture.watermarkImageSrc },
+		context
+	});
+	const above = (composer) => {
+		paintFootnoteArea({
+			composer,
+			page,
+			context,
+			...furniture.footnoteContentById === void 0 ? {} : { contentById: furniture.footnoteContentById }
+		});
+		if (selected.headerContent !== void 0) paintHeaderFooter({
+			composer,
+			page,
+			section: "header",
+			content: selected.headerContent,
+			...furniture.headerDistancePx === void 0 ? {} : { distancePx: furniture.headerDistancePx },
+			context
+		});
+		if (selected.footerContent !== void 0) paintHeaderFooter({
+			composer,
+			page,
+			section: "footer",
+			content: selected.footerContent,
+			...furniture.footerDistancePx === void 0 ? {} : { distancePx: furniture.footerDistancePx },
+			context
+		});
+		if (!paintsBorderBehind) composer.push(borders);
+	};
+	return {
+		behind: [...paintsBorderBehind ? borders : [], ...watermark],
+		above
+	};
+};
+//#endregion
+export { paintPageFurniture };

package/dist/display-list/build/glyphs.d.ts

@@ -0,0 +1,55 @@
+import { DisplayRunAdjustments } from "../types.js";
+import { FontStyle } from "../../layout-engine/measure/measureTypes.js";
+//#region src/display-list/build/glyphs.d.ts
+type Glyphs = {
+  readonly text: string;
+  readonly advancesPx: number[];
+  readonly widthPx: number;
+  /** Whether these advances were measured with kerning on. */
+  readonly kerning: boolean;
+  /** Whether they were measured as small capitals. */
+  readonly smallCaps: boolean;
+  /**
+   * What went into the advances beyond the glyphs' own widths. Absent when
+   * nothing did, which keeps the common run's primitive as small as it was.
+   */
+  readonly adjustments?: DisplayRunAdjustments;
+};
+type BuildGlyphsOptions = {
+  readonly text: string;
+  readonly style: FontStyle;
+  readonly allCaps: boolean;
+  /** Justification delta applied to every compressible space. */
+  readonly spaceDeltaPx: number;
+  /**
+   * A line-edge space run Word keeps addressable but paints with no advance
+   * (the painter zeroes the split-off span's font size instead).
+   */
+  readonly collapsed: boolean;
+};
+/**
+ * `measureRun` returns `charWidths` indexed by UTF-16 unit with the trailing
+ * unit of a surrogate pair set to 0, because that is what ProseMirror offsets
+ * need. The display list wants code points, so the pair folds into one entry.
+ * An uppercase transform that expands a code point (ß → SS) keeps the source
+ * advance on the first output code point and gives the rest zero, so the sum
+ * still equals what the measurer decided the line on.
+ */
+declare const buildGlyphs: (options: BuildGlyphsOptions) => Glyphs;
+/**
+ * Everything a measured run contributes to a `glyphRun`.
+ *
+ * One helper rather than three fields at each emission site: what went into the
+ * advances has to travel with them, and a call site that carried the advances
+ * and forgot the adjustments would silently paint a run the line was not fitted
+ * with.
+ */
+declare const glyphRunText: (glyphs: Glyphs) => {
+  adjustments?: DisplayRunAdjustments;
+  text: string;
+  advancesPx: number[];
+  kerning: boolean;
+  smallCaps: boolean;
+};
+//#endregion
+export { BuildGlyphsOptions, Glyphs, buildGlyphs, glyphRunText };

package/dist/display-list/build/glyphs.js

@@ -0,0 +1,103 @@
+import { measureRun, measureTextWidth } from "../../layout-engine/measure/measureProvider.js";
+import { FONT_KERNING_MODE, getFontKerningMode } from "../../layout-engine/measure/textMeasurementPolicy.js";
+import { getHorizontalScaleFactor } from "../../utils/horizontalScale.js";
+//#region src/display-list/build/glyphs.ts
+/**
+* Text → one advance per code point, taken from the measure seam.
+*
+* Shared by everything that paints glyphs (body lines, list markers, tab
+* leaders, watermark text) so no caller invents a width of its own: the numbers
+* here are the numbers line breaking and pagination were decided on.
+*/
+/**
+* `measureRun` returns `charWidths` indexed by UTF-16 unit with the trailing
+* unit of a surrogate pair set to 0, because that is what ProseMirror offsets
+* need. The display list wants code points, so the pair folds into one entry.
+* An uppercase transform that expands a code point (ß → SS) keeps the source
+* advance on the first output code point and gives the rest zero, so the sum
+* still equals what the measurer decided the line on.
+*/
+const buildGlyphs = (options) => {
+	const { text, style, allCaps, spaceDeltaPx, collapsed } = options;
+	const adjustments = adjustmentsOf(options);
+	const { charWidths } = measureRun(text, style);
+	const advancesPx = [];
+	let painted = "";
+	let widthPx = 0;
+	let unitOffset = 0;
+	const shapedScale = shapedScaleOf(text, style, charWidths);
+	for (const char of text) {
+		const measured = (charWidths[unitOffset] ?? 0) * shapedScale;
+		unitOffset += char.length;
+		const advance = collapsed ? 0 : measured + (char === " " ? spaceDeltaPx : 0);
+		widthPx += advance;
+		let isFirst = true;
+		for (const outputChar of allCaps ? char.toLocaleUpperCase() : char) {
+			painted += outputChar;
+			advancesPx.push(isFirst ? advance : 0);
+			isFirst = false;
+		}
+	}
+	return {
+		text: painted,
+		advancesPx,
+		widthPx,
+		kerning: getFontKerningMode(style) === FONT_KERNING_MODE.enabled,
+		smallCaps: style.fontVariant === "small-caps",
+		...adjustments === void 0 ? {} : { adjustments }
+	};
+};
+/**
+* What every per-character width has to be multiplied by for the run to occupy
+* the width the line was fitted at.
+*
+* The two numbers come from the same measurer and differ by what shaping does
+* across a boundary: a pair that kerns or ligates is narrower in the string
+* than the two characters are apart. Line breaking used the string's width, so
+* that is the run's width, and advances that summed to anything else would
+* declare an extent no backend paints.
+*
+* Spread over every character rather than dropped on the last, because the
+* difference is not one boundary's: concentrating it would move the run's final
+* glyph by the whole of it.
+*/
+const shapedScaleOf = (text, style, charWidths) => {
+	const perCharacterPx = charWidths.reduce((total, width) => total + width, 0);
+	if (perCharacterPx <= 0) return 1;
+	return measureTextWidth(text, style) / perCharacterPx;
+};
+/**
+* The three adjustments named, or nothing when none applies.
+*
+* A collapsed run carries no advances at all, so it has nothing to reapply
+* either: naming a spacing on a run painted at zero width would have a backend
+* widen what the line was fitted without.
+*/
+const adjustmentsOf = ({ style, spaceDeltaPx, collapsed }) => {
+	const horizontalScale = getHorizontalScaleFactor(style.horizontalScale);
+	const letterSpacingPx = collapsed ? 0 : (style.letterSpacing ?? 0) * horizontalScale;
+	const wordSpacingPx = collapsed ? 0 : spaceDeltaPx;
+	if (letterSpacingPx === 0 && wordSpacingPx === 0 && horizontalScale === 1) return;
+	return {
+		letterSpacingPx,
+		horizontalScale,
+		wordSpacingPx
+	};
+};
+/**
+* Everything a measured run contributes to a `glyphRun`.
+*
+* One helper rather than three fields at each emission site: what went into the
+* advances has to travel with them, and a call site that carried the advances
+* and forgot the adjustments would silently paint a run the line was not fitted
+* with.
+*/
+const glyphRunText = (glyphs) => ({
+	text: glyphs.text,
+	advancesPx: glyphs.advancesPx,
+	kerning: glyphs.kerning,
+	smallCaps: glyphs.smallCaps,
+	...glyphs.adjustments === void 0 ? {} : { adjustments: glyphs.adjustments }
+});
+//#endregion
+export { buildGlyphs, glyphRunText };

package/dist/display-list/build/headerFooterPrimitives.d.ts

@@ -0,0 +1,17 @@
+import { HeaderFooterContent, Page } from "../../layout-engine/types.js";
+import { BuildContext } from "./buildContext.js";
+import { PageComposer } from "./regions.js";
+//#region src/display-list/build/headerFooterPrimitives.d.ts
+type HeaderFooterSection = "header" | "footer";
+type HeaderFooterPaintOptions = {
+  readonly composer: PageComposer;
+  readonly page: Page;
+  readonly section: HeaderFooterSection;
+  readonly content: HeaderFooterContent;
+  /** Overrides `w:pgMar`'s `w:header` / `w:footer` for this page. */
+  readonly distancePx?: number;
+  readonly context: BuildContext;
+};
+declare const paintHeaderFooter: ({ composer, page, section, content, distancePx, context }: HeaderFooterPaintOptions) => void;
+//#endregion
+export { HeaderFooterPaintOptions, HeaderFooterSection, paintHeaderFooter };

package/dist/display-list/build/headerFooterPrimitives.js

@@ -0,0 +1,40 @@
+import { HIT_REGION_KINDS } from "../primitives.js";
+import { paintHeaderFooterBlocks } from "./storyPrimitives.js";
+//#region src/display-list/build/headerFooterPrimitives.ts
+/** `renderPage.ts`: the fallback when neither the caller nor `w:pgMar` states one. */
+const DEFAULT_DISTANCE_PX = 48;
+const paintHeaderFooter = ({ composer, page, section, content, distancePx, context }) => {
+	if (content.blocks.length === 0) return;
+	const distance = distancePx ?? (section === "header" ? page.margins.header : page.margins.footer) ?? DEFAULT_DISTANCE_PX;
+	const originYPx = section === "header" ? distance : page.size.h - distance - content.height;
+	const story = {
+		kind: section,
+		rId: content.rId ?? null
+	};
+	composer.region({
+		kind: section === "header" ? HIT_REGION_KINDS.headerSlot : HIT_REGION_KINDS.footerSlot,
+		rect: {
+			xPx: page.margins.left,
+			yPx: originYPx,
+			widthPx: page.size.w - page.margins.left - page.margins.right,
+			heightPx: content.height
+		},
+		model: { story }
+	}, () => {
+		paintHeaderFooterBlocks({
+			composer,
+			blocks: content.blocks,
+			measures: content.measures,
+			xPx: page.margins.left,
+			yPx: originYPx,
+			widthPx: page.size.w - page.margins.left - page.margins.right,
+			context: {
+				...context,
+				story
+			},
+			label: content.rId === void 0 ? section : `${section} ${content.rId}`
+		});
+	});
+};
+//#endregion
+export { paintHeaderFooter };

package/dist/display-list/build/imagePrimitives.d.ts

@@ -0,0 +1,35 @@
+import { ImageBlock, ImageFragment } from "../../layout-engine/types.js";
+import { DisplayImageRef, DisplayImageSource, DisplayPrimitive, DisplayRect } from "../types.js";
+import { BuildContext } from "./buildContext.js";
+//#region src/display-list/build/imagePrimitives.d.ts
+/**
+ * Sources interned in first-use order, so two builds of one layout produce the
+ * same `DisplayImageRef` for the same picture.
+ */
+declare class ImageTable {
+  private readonly sources;
+  private readonly refBySrc;
+  private readonly failureBySrc;
+  /** `undefined` means "do not paint"; the reason is available via {@link failureFor}. */
+  intern(src: string): DisplayImageRef | undefined;
+  failureFor(src: string): string | undefined;
+  snapshot(): readonly DisplayImageSource[];
+}
+type ImageVisualSource = Pick<ImageBlock, "src" | "opacity" | "cropTop" | "cropRight" | "cropBottom" | "cropLeft" | "borderWidth" | "borderColor" | "borderStyle" | "transform">;
+type PaintImageOptions = {
+  readonly source: ImageVisualSource;
+  readonly rect: DisplayRect;
+  readonly context: BuildContext;
+  /** Names the construct in an `unsupported` entry, e.g. `"anchored image"`. */
+  readonly label: string;
+};
+/**
+ * The primitives one picture draws: the bitmap (rotated and/or washed as the
+ * source asks) followed by its border. Empty when the bytes are unusable, with
+ * the reason already reported.
+ */
+declare const paintImage: ({ source, rect, context, label }: PaintImageOptions) => readonly DisplayPrimitive[];
+/** An anchored or block image fragment placed by the layout engine. */
+declare const paintImageFragment: (fragment: ImageFragment, block: ImageBlock, context: BuildContext) => readonly DisplayPrimitive[];
+//#endregion
+export { ImageTable, PaintImageOptions, paintImage, paintImageFragment };