@stll/folio-core 0.32.1 → 0.33.0

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

@@ -0,0 +1,46 @@
+import { BlockId } from "../../layout-engine/types.js";
+import { DisplayHitRegion, DisplayHitRegionKind, DisplayHitRegionModel, DisplayPrimitive, DisplayRect, DisplayStoryRef } from "../types.js";
+//#region src/display-list/build/regions.d.ts
+type RegionDescriptor = {
+  readonly kind: DisplayHitRegionKind;
+  readonly rect: DisplayRect;
+  readonly model?: DisplayHitRegionModel;
+};
+type PageComposer = {
+  /** Append primitives to the page, in paint order. */
+  readonly push: (primitives: readonly DisplayPrimitive[]) => void;
+  /**
+   * Everything `paint` appends belongs to this region. Regions opened inside
+   * `paint` become its children, so the tree is the nesting of the walk.
+   */
+  readonly region: (descriptor: RegionDescriptor, paint: () => void) => void;
+  readonly primitives: () => readonly DisplayPrimitive[];
+  readonly regions: () => readonly DisplayHitRegion[];
+};
+declare const createPageComposer: () => PageComposer;
+/**
+ * The region a whole block occupies, wherever it is painted.
+ *
+ * A body fragment, a picture inside a header, a text box inside a cell: each is
+ * one block at one place, and a surface asks the same questions of all of them.
+ * Taking the box and the range from the same fragment the painting uses is what
+ * keeps the answer the one that was drawn.
+ */
+type BlockRegionOptions = {
+  readonly fragment: {
+    readonly blockId: BlockId;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly pmStart?: number;
+    readonly pmEnd?: number;
+  };
+  readonly kind: DisplayHitRegionKind;
+  readonly context: {
+    readonly story: DisplayStoryRef;
+  };
+};
+declare const blockRegion: ({ fragment, kind, context }: BlockRegionOptions) => RegionDescriptor;
+//#endregion
+export { PageComposer, RegionDescriptor, blockRegion, createPageComposer };

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

@@ -0,0 +1,56 @@
+//#region src/display-list/build/regions.ts
+const createPageComposer = () => {
+	const primitives = [];
+	const roots = [];
+	const open = [];
+	const push = (added) => {
+		primitives.push(...added);
+	};
+	const region = (descriptor, paint) => {
+		const entry = {
+			descriptor,
+			from: primitives.length,
+			children: []
+		};
+		open.push(entry);
+		try {
+			paint();
+		} finally {
+			open.pop();
+		}
+		const closed = {
+			kind: descriptor.kind,
+			rect: descriptor.rect,
+			from: entry.from,
+			to: primitives.length,
+			children: entry.children,
+			...descriptor.model === void 0 ? {} : { model: descriptor.model }
+		};
+		(open.at(-1)?.children ?? roots).push(closed);
+	};
+	return {
+		push,
+		region,
+		primitives: () => primitives,
+		regions: () => roots
+	};
+};
+const blockRegion = ({ fragment, kind, context }) => ({
+	kind,
+	rect: {
+		xPx: fragment.x,
+		yPx: fragment.y,
+		widthPx: fragment.width,
+		heightPx: fragment.height
+	},
+	model: {
+		blockId: String(fragment.blockId),
+		...fragment.pmStart === void 0 || fragment.pmEnd === void 0 ? {} : { pmRange: {
+			start: fragment.pmStart,
+			end: fragment.pmEnd,
+			story: context.story
+		} }
+	}
+});
+//#endregion
+export { blockRegion, createPageComposer };

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

@@ -0,0 +1,29 @@
+import { FlowBlock, Measure } from "../../layout-engine/types.js";
+import { BuildContext } from "./buildContext.js";
+import { PageComposer } from "./regions.js";
+//#region src/display-list/build/storyPrimitives.d.ts
+type PaintStoryOptions = {
+  readonly composer: PageComposer;
+  readonly blocks: readonly FlowBlock[];
+  readonly measures: readonly Measure[];
+  /** Page-absolute origin of the story's own content box. */
+  readonly xPx: number;
+  readonly yPx: number;
+  readonly widthPx: number;
+  readonly context: BuildContext;
+  readonly label: string;
+};
+/**
+ * A footnote body: every block stacks by its measured height, which is the
+ * height the paginator reserved the band from.
+ */
+declare const paintFootnoteBlocks: ({ composer, blocks, measures, xPx, yPx, widthPx, context, label }: PaintStoryOptions) => void;
+/**
+ * A header or footer story. Blocks that Word takes out of the flow (a floating
+ * table, an anchored image, a positioned text box) contribute no height, and
+ * they are reported rather than painted: their position resolves against page
+ * and margin anchors the display list producer does not carry.
+ */
+declare const paintHeaderFooterBlocks: ({ composer, blocks, measures, xPx, yPx, widthPx, context, label }: PaintStoryOptions) => void;
+//#endregion
+export { PaintStoryOptions, paintFootnoteBlocks, paintHeaderFooterBlocks };

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

@@ -0,0 +1,279 @@
+import { isFloatingImageRun, isFloatingTextBoxBlock } from "../../layout-engine/types.js";
+import { HIT_REGION_KINDS } from "../primitives.js";
+import { paintImageFragment } from "./imagePrimitives.js";
+import { paintParagraphFragment } from "./paragraphPrimitives.js";
+import { blockRegion } from "./regions.js";
+import { paintTableFragment } from "./tablePrimitives.js";
+import { paintTextBoxFragment } from "./textBoxPrimitives.js";
+import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
+//#region src/display-list/build/storyPrimitives.ts
+/**
+* Stacked story blocks: the header, the footer and a footnote body.
+*
+* These three are not fragments. The layout engine paginates the body only, so
+* a story arrives as a `(blocks, measures)` pair already measured against its
+* own width, and whoever paints it stacks the blocks itself. Every block is
+* then handed to the *same* paragraph, table, image and text-box builders the
+* body uses: a second text painter for headers is exactly how a header comes to
+* disagree with the body about a tab stop or a justified space.
+*
+* The stacking rules differ between the two callers and both are the painter's:
+* `renderFootnoteContent` advances by the measured height of every block, while
+* `renderHeaderFooterContent` honours explicit `w:spacing w:before`, offsets an
+* inline table by `w:jc`/`w:tblInd`, and lets a floating or page-anchored
+* object out of the flow entirely.
+*/
+/** Mirrors `isPositionedHeaderFooterTextBoxBlock`: an explicit display mode keeps a box in the flow. */
+const isPositionedTextBox = (block) => block.displayMode !== "block" && block.displayMode !== "inline" && isFloatingTextBoxBlock(block);
+const isAnchoredImage = (block) => block.anchor?.isAnchored === true;
+/** `w:jc` / `w:tblInd` for an inline story table, as the body's `desiredX` resolves them. */
+const inlineTableOffsetPx = (block, tableWidthPx, widthPx) => {
+	if (block.justification === "center") return (widthPx - tableWidthPx) / 2;
+	if (block.justification === "right") return widthPx - tableWidthPx;
+	return block.indent ?? 0;
+};
+/**
+* Explicit `w:spacing w:before` only. `normalizeHeaderFooterMeasureBlocks`
+* strips style-inherited spacing from the measurement copy, so offsetting by an
+* inherited value would push the first line below the space its own measure
+* reserved and every following block with it.
+*/
+const explicitSpaceBeforePx = (block) => block.attrs?.spacingExplicit?.before === true ? block.attrs.spacing?.before ?? 0 : 0;
+/** One block of a story, painted at an absolute page position. */
+const paintStoryBlock = ({ composer, block, measure, xPx, yPx, widthPx, context, label, construct }) => {
+	if (block.kind === "paragraph" && measure.kind === "paragraph") {
+		const fragment = {
+			kind: "paragraph",
+			blockId: block.id,
+			x: xPx,
+			y: yPx,
+			width: widthPx,
+			height: measure.totalHeight,
+			fromLine: 0,
+			toLine: measure.lines.length
+		};
+		composer.region(blockRegion({
+			fragment,
+			kind: HIT_REGION_KINDS.paragraph,
+			context
+		}), () => {
+			paintParagraphFragment({
+				fragment,
+				block,
+				measure,
+				context,
+				composer
+			});
+		});
+		return;
+	}
+	if (block.kind === "table" && measure.kind === "table") {
+		const fragment = {
+			kind: "table",
+			blockId: block.id,
+			x: xPx,
+			y: yPx,
+			width: measure.totalWidth,
+			height: measure.totalHeight,
+			fromRow: 0,
+			toRow: block.rows.length
+		};
+		composer.region(blockRegion({
+			fragment,
+			kind: HIT_REGION_KINDS.table,
+			context
+		}), () => {
+			paintTableFragment({
+				fragment,
+				block,
+				measure,
+				context,
+				composer,
+				paintTextBox: paintTextBoxFragment
+			});
+		});
+		return;
+	}
+	if (block.kind === "image" && measure.kind === "image") {
+		const fragment = {
+			kind: "image",
+			blockId: block.id,
+			x: xPx,
+			y: yPx,
+			width: measure.width,
+			height: measure.height
+		};
+		composer.region(blockRegion({
+			fragment,
+			kind: HIT_REGION_KINDS.image,
+			context
+		}), () => {
+			composer.push(paintImageFragment(fragment, block, context));
+		});
+		return;
+	}
+	if (block.kind === "textBox" && measure.kind === "textBox") {
+		const fragment = {
+			kind: "textBox",
+			blockId: block.id,
+			x: xPx,
+			y: yPx,
+			width: measure.width,
+			height: measure.height
+		};
+		composer.region(blockRegion({
+			fragment,
+			kind: HIT_REGION_KINDS.textBox,
+			context
+		}), () => {
+			paintTextBoxFragment({
+				composer,
+				fragment,
+				block,
+				measure,
+				context
+			});
+		});
+		return;
+	}
+	context.unsupported.report(construct, context.pageIndex, `${label}: a ${block.kind} block with a ${measure.kind} measure is not painted`);
+};
+const measuredHeightPx = (measure) => {
+	switch (measure.kind) {
+		case "paragraph":
+		case "table": return measure.totalHeight;
+		case "image":
+		case "textBox": return measure.height;
+		case "sectionBreak":
+		case "pageBreak":
+		case "columnBreak": return 0;
+		default: return 0;
+	}
+};
+/**
+* A footnote body: every block stacks by its measured height, which is the
+* height the paginator reserved the band from.
+*/
+const paintFootnoteBlocks = ({ composer, blocks, measures, xPx, yPx, widthPx, context, label }) => {
+	let cursorYPx = yPx;
+	for (const [index, block] of blocks.entries()) {
+		const measure = measures[index];
+		if (measure === void 0) {
+			context.unsupported.report(UNSUPPORTED_CONSTRUCT.missingBlock, context.pageIndex, `${label}: block ${String(block.id)} has no measure`);
+			continue;
+		}
+		paintStoryBlock({
+			composer,
+			block,
+			measure,
+			xPx,
+			yPx: cursorYPx,
+			widthPx,
+			context,
+			label,
+			construct: UNSUPPORTED_CONSTRUCT.footnoteContent
+		});
+		cursorYPx += measuredHeightPx(measure);
+	}
+};
+/**
+* A header or footer story. Blocks that Word takes out of the flow (a floating
+* table, an anchored image, a positioned text box) contribute no height, and
+* they are reported rather than painted: their position resolves against page
+* and margin anchors the display list producer does not carry.
+*/
+const paintHeaderFooterBlocks = ({ composer, blocks, measures, xPx, yPx, widthPx, context, label }) => {
+	let cursorYPx = yPx;
+	const reportOutOfFlow = (detail) => {
+		context.unsupported.report(UNSUPPORTED_CONSTRUCT.headerFooterContent, context.pageIndex, `${label}: ${detail}`);
+	};
+	for (const [index, block] of blocks.entries()) {
+		const measure = measures[index];
+		if (measure === void 0) {
+			context.unsupported.report(UNSUPPORTED_CONSTRUCT.missingBlock, context.pageIndex, `${label}: block ${String(block.id)} has no measure`);
+			continue;
+		}
+		switch (block.kind) {
+			case "paragraph":
+				if (measure.kind !== "paragraph") break;
+				if (block.runs.some((run) => run.kind === "image" && (isFloatingImageRun(run) || run.position !== void 0))) reportOutOfFlow(`paragraph ${String(block.id)} anchors a floating picture, which resolves against page and margin anchors the display list does not carry`);
+				paintStoryBlock({
+					composer,
+					block,
+					measure,
+					xPx,
+					yPx: cursorYPx + explicitSpaceBeforePx(block),
+					widthPx,
+					context,
+					label,
+					construct: UNSUPPORTED_CONSTRUCT.headerFooterContent
+				});
+				cursorYPx += measure.totalHeight;
+				continue;
+			case "table":
+				if (measure.kind !== "table") break;
+				if (block.floating) {
+					reportOutOfFlow(`table ${String(block.id)} is floating (w:tblpPr) and is not painted`);
+					continue;
+				}
+				paintStoryBlock({
+					composer,
+					block,
+					measure,
+					xPx: xPx + inlineTableOffsetPx(block, measure.totalWidth, widthPx),
+					yPx: cursorYPx,
+					widthPx,
+					context,
+					label,
+					construct: UNSUPPORTED_CONSTRUCT.headerFooterContent
+				});
+				cursorYPx += measure.totalHeight;
+				continue;
+			case "image":
+				if (measure.kind !== "image") break;
+				if (isAnchoredImage(block)) {
+					reportOutOfFlow(`image ${String(block.id)} is anchored and is not painted`);
+					continue;
+				}
+				paintStoryBlock({
+					composer,
+					block,
+					measure,
+					xPx,
+					yPx: cursorYPx,
+					widthPx,
+					context,
+					label,
+					construct: UNSUPPORTED_CONSTRUCT.headerFooterContent
+				});
+				cursorYPx += measure.height;
+				continue;
+			case "textBox":
+				if (measure.kind !== "textBox") break;
+				if (isPositionedTextBox(block)) {
+					reportOutOfFlow(`text box ${String(block.id)} is positioned and is not painted`);
+					continue;
+				}
+				paintStoryBlock({
+					composer,
+					block,
+					measure,
+					xPx,
+					yPx: cursorYPx,
+					widthPx,
+					context,
+					label,
+					construct: UNSUPPORTED_CONSTRUCT.headerFooterContent
+				});
+				cursorYPx += measure.height;
+				continue;
+			case "pageBreak":
+			case "columnBreak":
+			case "sectionBreak": continue;
+			default: continue;
+		}
+		context.unsupported.report(UNSUPPORTED_CONSTRUCT.measureMismatch, context.pageIndex, `${label}: block ${String(block.id)} is a ${block.kind} with a ${measure.kind} measure`);
+	}
+};
+//#endregion
+export { paintFootnoteBlocks, paintHeaderFooterBlocks };

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

@@ -0,0 +1,19 @@
+import { BorderStyle } from "../../layout-engine/types.js";
+import { DisplayStroke, DisplayStrokePattern } from "../types.js";
+//#region src/display-list/build/strokes.d.ts
+type BorderInput = Pick<BorderStyle, "color" | "style" | "width">;
+type ResolveStrokeResult = {
+  readonly stroke?: DisplayStroke;
+  /** The authored colour, when it could not be parsed. Report it, do not paint. */
+  readonly unresolvedColor?: string;
+};
+/**
+ * Turn an authored border into a paintable stroke. `undefined` stroke means
+ * "draw nothing": an explicit `none`/`nil` style, a non-positive width, or a
+ * colour this producer cannot resolve.
+ */
+declare const resolveBorderStroke: (border: BorderInput) => ResolveStrokeResult;
+/** CSS `text-decoration-style` → the display list's stroke patterns. */
+declare const decorationPatternForStyle: (style: string | undefined) => DisplayStrokePattern;
+//#endregion
+export { ResolveStrokeResult, decorationPatternForStyle, resolveBorderStroke };

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

@@ -0,0 +1,78 @@
+import { resolveCssBorderStroke } from "../../layout-painter/borderStroke.js";
+import { parseDisplayColor } from "./colors.js";
+//#region src/display-list/build/strokes.ts
+/**
+* Border and rule strokes.
+*
+* One deliberate divergence from `layout-painter/borderStroke.ts`: that helper
+* encodes a sub-pixel border width as a `color-mix` alpha because CSS quantizes
+* a fractional border to one device pixel. A display list has no device pixel,
+* and a PDF strokes 0.4pt natively, so the authored fractional width and the
+* plain colour survive here. Everything else (colour/style/width defaults) is
+* taken from the painter's helper so the two cannot drift.
+*/
+/**
+* CSS `border-style` and the raw OOXML `w:val` names both reach
+* `BorderStyle.style` (the bridge maps most, `renderParagraph` maps the rest),
+* so both vocabularies are resolved here. Everything decorative that folio does
+* not draw degrades to a plain line, matching how Word degrades on a platform
+* without the specialised glyphs.
+*/
+const STROKE_PATTERN_BY_STYLE = {
+	none: "none",
+	nil: "none",
+	hidden: "none",
+	solid: "solid",
+	single: "solid",
+	thick: "solid",
+	inset: "solid",
+	outset: "solid",
+	ridge: "solid",
+	groove: "solid",
+	double: "double",
+	dotted: "dotted",
+	dotdash: "dashed",
+	dotdotdash: "dashed",
+	dashed: "dashed",
+	dash: "dashed",
+	dashsmallgap: "dashed",
+	dashlong: "dashed",
+	wavy: "wavy",
+	wave: "wavy",
+	wavydouble: "double"
+};
+const DEFAULT_PATTERN = "solid";
+const strokePatternForStyle = (style) => {
+	if (style === void 0) return DEFAULT_PATTERN;
+	return STROKE_PATTERN_BY_STYLE[style.trim().toLowerCase()] ?? DEFAULT_PATTERN;
+};
+/**
+* Turn an authored border into a paintable stroke. `undefined` stroke means
+* "draw nothing": an explicit `none`/`nil` style, a non-positive width, or a
+* colour this producer cannot resolve.
+*/
+const resolveBorderStroke = (border) => {
+	const pattern = strokePatternForStyle(border.style);
+	if (pattern === "none") return {};
+	const css = resolveCssBorderStroke(border);
+	const isSubPixelEncoded = css.color.startsWith("color-mix");
+	const authoredWidth = border.width ?? css.width;
+	const thicknessPx = isSubPixelEncoded ? authoredWidth : css.width;
+	if (thicknessPx <= 0) return {};
+	const colorSource = isSubPixelEncoded ? border.color ?? "#000000" : css.color;
+	const color = parseDisplayColor(colorSource);
+	if (!color) return { unresolvedColor: colorSource };
+	return { stroke: {
+		color,
+		thicknessPx,
+		pattern
+	} };
+};
+/** CSS `text-decoration-style` → the display list's stroke patterns. */
+const decorationPatternForStyle = (style) => {
+	if (style === void 0) return DEFAULT_PATTERN;
+	const pattern = STROKE_PATTERN_BY_STYLE[style.trim().toLowerCase()];
+	return pattern === void 0 || pattern === "none" ? DEFAULT_PATTERN : pattern;
+};
+//#endregion
+export { decorationPatternForStyle, resolveBorderStroke };

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

@@ -0,0 +1,38 @@
+import { TableBlock, TableFragment, TableMeasure, TextBoxBlock, TextBoxFragment, TextBoxMeasure } from "../../layout-engine/types.js";
+import { BuildContext } from "./buildContext.js";
+import { PageComposer } from "./regions.js";
+//#region src/display-list/build/tablePrimitives.d.ts
+type PaintTextBox = (options: {
+  readonly composer: PageComposer;
+  readonly fragment: TextBoxFragment;
+  readonly block: TextBoxBlock;
+  readonly measure: TextBoxMeasure;
+  readonly context: BuildContext;
+}) => void;
+type TableBlockPaintOptions = {
+  readonly composer: PageComposer;
+  readonly block: TableBlock;
+  readonly measure: TableMeasure;
+  readonly xPx: number;
+  readonly yPx: number;
+  readonly context: BuildContext;
+  readonly paintTextBox: PaintTextBox;
+};
+/** A whole, unpaginated table: what a nested table inside a cell or box is. */
+declare const paintTableBlock: ({ composer, block, measure, xPx, yPx, context, paintTextBox }: TableBlockPaintOptions) => void;
+type TablePaintOptions = {
+  readonly composer: PageComposer;
+  readonly fragment: TableFragment;
+  readonly block: TableBlock;
+  readonly measure: TableMeasure;
+  readonly context: BuildContext;
+  readonly paintTextBox: PaintTextBox;
+};
+/**
+ * A table fragment's primitives. A fragment that cuts a row mid-content wraps
+ * its rows in a `clipGroup` and starts them `topClip` px higher, which is what
+ * the painter's negative row-stack offset plus `overflow: hidden` does.
+ */
+declare const paintTableFragment: ({ composer, fragment, block, measure, context, paintTextBox }: TablePaintOptions) => void;
+//#endregion
+export { TableBlockPaintOptions, TablePaintOptions, paintTableBlock, paintTableFragment };