@stll/folio-core 0.32.1 → 0.33.0

package/dist/display-list/editor/displayListPagePainter.js

@@ -0,0 +1,63 @@
+import { createDisplayListBuilder } from "../build/buildDisplayList.js";
+import { renderDisplayPageToDom } from "../dom/renderDisplayListToDom.js";
+import { panic } from "better-result";
+//#region src/display-list/editor/displayListPagePainter.ts
+/**
+* Paint the editor's pages from the display list instead of from `Layout`.
+*
+* This is a composition root, not a backend: it is the one place that knows
+* both the producer and the DOM backend, which is why it may import each of
+* them and why neither may import it.
+*
+* ## What it replaces, and what it deliberately does not
+*
+* `renderPages` owns two separable jobs. One is *painting* a page, which is
+* what diverges between two renderers and what the display list exists to make
+* single. The other is the page *container*: shells, virtualization, the
+* fingerprint comparison that skips an unchanged page, the intersection
+* observer, the painted event. That second job is renderer-independent, so
+* this module supplies only a `paintPage` and leaves the container alone.
+* Reimplementing the container behind a second renderer would be exactly the
+* second copy the display list was introduced to remove, and it would silently
+* lose incremental repaint on documents past the virtualization threshold.
+*
+* ## Why a page is built when it is painted
+*
+* `renderPage` is called per page, so building the whole list per call would be
+* quadratic in page count. Building it once per layout run is not right either:
+* the container paints a window of pages and skips every page whose fingerprint
+* has not changed, so a document of ninety pages would build ninety to paint
+* three, on every keystroke. The builder computes what belongs to the document
+* once and each page when it is asked for, so the work follows the screen.
+*/
+/**
+* Page numbers are the engine's own and may restart or skip across sections,
+* so a display page is found by its position in the layout rather than by its
+* number. Both sequences come from the same `Layout`, so they align by
+* construction; a mismatch is a programming error, not a document one.
+*/
+const indexByPageNumber = (layout) => new Map(layout.pages.map((page, index) => [page.number, index]));
+const createDisplayListPagePainter = (options) => {
+	const { doc, ...build } = options;
+	const builder = createDisplayListBuilder(build);
+	const indexOf = indexByPageNumber(build.layout);
+	const paintPage = ({ page }) => {
+		const index = indexOf.get(page.number);
+		if (index === void 0) return null;
+		const displayPage = builder.pageAt(index);
+		if (displayPage === void 0) panic(`display list page ${String(index)} is indexed but absent`);
+		const { fonts, images } = builder.snapshot();
+		return renderDisplayPageToDom(displayPage, {
+			doc,
+			fonts,
+			images,
+			pageIndex: index
+		});
+	};
+	return {
+		paintPage,
+		list: builder.snapshot
+	};
+};
+//#endregion
+export { createDisplayListPagePainter };

package/dist/display-list/editor/pageRenderer.d.ts

@@ -0,0 +1,24 @@
+import { RenderPageOptions } from "../../layout-painter/renderPage.js";
+import { PageFurnitureInputs } from "../build/furniture.js";
+//#region src/display-list/editor/pageRenderer.d.ts
+declare const PAGE_RENDERER: {
+  /** The painter that has always painted the editor. */
+  readonly legacy: "legacy";
+  /** Builds the paint IR from the layout and paints the pages from it. */
+  readonly displayList: "display-list";
+};
+type PageRendererName = (typeof PAGE_RENDERER)[keyof typeof PAGE_RENDERER];
+declare const isPageRendererName: (value: unknown) => value is PageRendererName;
+/**
+ * Read the display-list producer's furniture inputs out of the render options
+ * the pipeline already computed.
+ *
+ * Both sides describe the same constructs, and the pipeline is the only place
+ * that knows how to derive them from a package, so the display-list path reads
+ * what the existing path receives rather than deriving them a second time. A
+ * second derivation is how the two renderers would come to disagree about
+ * which header a page carries.
+ */
+declare const displayListFurnitureFrom: (options: RenderPageOptions) => PageFurnitureInputs;
+//#endregion
+export { PAGE_RENDERER, PageRendererName, displayListFurnitureFrom, isPageRendererName };

package/dist/display-list/editor/pageRenderer.js

@@ -0,0 +1,36 @@
+//#region src/display-list/editor/pageRenderer.ts
+const PAGE_RENDERER = {
+	/** The painter that has always painted the editor. */
+	legacy: "legacy",
+	/** Builds the paint IR from the layout and paints the pages from it. */
+	displayList: "display-list"
+};
+const isPageRendererName = (value) => value === PAGE_RENDERER.legacy || value === PAGE_RENDERER.displayList;
+/**
+* Read the display-list producer's furniture inputs out of the render options
+* the pipeline already computed.
+*
+* Both sides describe the same constructs, and the pipeline is the only place
+* that knows how to derive them from a package, so the display-list path reads
+* what the existing path receives rather than deriving them a second time. A
+* second derivation is how the two renderers would come to disagree about
+* which header a page carries.
+*/
+const displayListFurnitureFrom = (options) => ({
+	...options.pageBorders === void 0 ? {} : { pageBorders: options.pageBorders },
+	...options.theme === void 0 ? {} : { theme: options.theme },
+	...options.watermark === void 0 ? {} : { watermark: options.watermark },
+	...options.watermarkByHeaderRId === void 0 ? {} : { watermarkByHeaderRId: options.watermarkByHeaderRId },
+	...options.watermarkImageSrc === void 0 ? {} : { watermarkImageSrc: options.watermarkImageSrc },
+	...options.headerContent === void 0 ? {} : { headerContent: options.headerContent },
+	...options.footerContent === void 0 ? {} : { footerContent: options.footerContent },
+	...options.headerContentByRId === void 0 ? {} : { headerContentByRId: options.headerContentByRId },
+	...options.footerContentByRId === void 0 ? {} : { footerContentByRId: options.footerContentByRId },
+	...options.firstPageHeaderContent === void 0 ? {} : { firstPageHeaderContent: options.firstPageHeaderContent },
+	...options.firstPageFooterContent === void 0 ? {} : { firstPageFooterContent: options.firstPageFooterContent },
+	...options.titlePg === void 0 ? {} : { titlePg: options.titlePg },
+	...options.headerDistance === void 0 ? {} : { headerDistancePx: options.headerDistance },
+	...options.footerDistance === void 0 ? {} : { footerDistancePx: options.footerDistance }
+});
+//#endregion
+export { PAGE_RENDERER, displayListFurnitureFrom, isPageRendererName };

package/dist/display-list/primitives.d.ts

@@ -0,0 +1,95 @@
+import { DisplayColor, DisplayGlyphRun, DisplayHitRegion, DisplayPrimitive } from "./types.js";
+import { hasCursiveLetter, joinsAcrossBoundary } from "../utils/cursiveJoining.js";
+import { hasComplexScript, isComplexScriptCodePoint } from "../utils/scriptSegments.js";
+//#region src/display-list/primitives.d.ts
+/**
+ * Left edge of every code point of a run, as an offset from the run's `xPx`.
+ *
+ * One implementation for both backends. The ordering rule is prose in
+ * `types.ts`, and two backends reading that prose separately is the
+ * divergence the display list exists to prevent: a run occupies
+ * `[xPx, xPx + sum(advancesPx)]` whichever way it runs, so under `ltr` code
+ * point `i` starts at `sum(advancesPx[0..i))` and under `rtl` it ends there,
+ * counted back from the run's right edge. A backend adds its own origin: the
+ * left edge is where a glyph is placed in either direction, because a glyph
+ * advances rightward from its origin whatever the paragraph does.
+ */
+declare const glyphCellOffsetsPx: (run: DisplayGlyphRun) => readonly number[];
+declare const DISPLAY_PRIMITIVE_KINDS: ("glyphRun" | "rect" | "line" | "image" | "clipGroup" | "rotateGroup" | "opacityGroup")[];
+/**
+ * Dash geometry of each stroke pattern, as multiples of the stroke thickness.
+ *
+ * `null` means the pattern is not a dash: `solid` draws one unbroken line,
+ * `double` two parallel lines, `wavy` a periodic curve. Sharing the factors is
+ * what keeps a dashed underline in the editor and a dashed underline in the
+ * export the same dash: with the pattern name alone, each backend would pick
+ * its own period and nobody would notice until the two were laid side by side.
+ */
+declare const STROKE_DASH_FACTORS: {
+  readonly solid: null;
+  readonly dashed: {
+    readonly dash: 3;
+    readonly gap: 2;
+  };
+  readonly dotted: {
+    readonly dash: 1;
+    readonly gap: 1;
+  };
+  readonly double: null;
+  readonly wavy: null;
+};
+/**
+ * Gap between the two lines of a `double` stroke, as a multiple of thickness.
+ * Word draws the pair at the authored width with an equal gap between them.
+ */
+declare const DOUBLE_STROKE_GAP_FACTOR = 1;
+/**
+ * Period and peak-to-peak amplitude of a `wavy` stroke, in thicknesses.
+ *
+ * The amplitude is measured between the centres of the curve at its extremes,
+ * so the stroke's own thickness lies outside it: a wavy stroke's total cross
+ * extent is `(WAVY_STROKE_AMPLITUDE_FACTOR + 1) * thicknessPx`, centred on the
+ * path. Stated because "amplitude" alone leaves each backend to decide whether
+ * the thickness is inside or outside, and the two answers differ by a
+ * thickness on every wavy underline in the document.
+ */
+declare const WAVY_STROKE_PERIOD_FACTOR = 6;
+declare const WAVY_STROKE_AMPLITUDE_FACTOR = 2;
+declare const BLACK: DisplayColor;
+declare const WHITE: DisplayColor;
+/**
+ * The kinds of region a click can land in, as a total map over the union: a
+ * new kind that is not listed fails to compile, and so does a name that is not
+ * a kind.
+ */
+declare const HIT_REGION_KINDS: {
+  readonly pageContent: "pageContent";
+  readonly headerSlot: "headerSlot";
+  readonly footerSlot: "footerSlot";
+  readonly note: "note";
+  readonly paragraph: "paragraph";
+  readonly line: "line";
+  readonly emptyRun: "emptyRun";
+  readonly tab: "tab";
+  readonly image: "image";
+  readonly table: "table";
+  readonly tableRow: "tableRow";
+  readonly tableCell: "tableCell";
+  readonly textBox: "textBox";
+};
+/**
+ * Walk a region tree with the primitives each level owns directly.
+ *
+ * A backend that paints structure needs both, interleaved in paint order: the
+ * primitives before a child, then the child, then the ones after it. Reading
+ * the tree any other way would paint a page in an order the producer did not
+ * choose.
+ */
+type RegionVisitor = {
+  readonly onPrimitive: (primitive: DisplayPrimitive, index: number) => void;
+  readonly enter: (region: DisplayHitRegion) => void;
+  readonly exit: (region: DisplayHitRegion) => void;
+};
+declare const walkRegions: (primitives: readonly DisplayPrimitive[], regions: readonly DisplayHitRegion[], visitor: RegionVisitor) => void;
+//#endregion
+export { BLACK, DISPLAY_PRIMITIVE_KINDS, DOUBLE_STROKE_GAP_FACTOR, HIT_REGION_KINDS, RegionVisitor, STROKE_DASH_FACTORS, WAVY_STROKE_AMPLITUDE_FACTOR, WAVY_STROKE_PERIOD_FACTOR, WHITE, glyphCellOffsetsPx, hasComplexScript, hasCursiveLetter, isComplexScriptCodePoint, joinsAcrossBoundary, walkRegions };

package/dist/display-list/primitives.js

@@ -0,0 +1,127 @@
+import { hasCursiveLetter, joinsAcrossBoundary } from "../utils/cursiveJoining.js";
+import { hasComplexScript, isComplexScriptCodePoint } from "../utils/scriptSegments.js";
+//#region src/display-list/primitives.ts
+/**
+* Left edge of every code point of a run, as an offset from the run's `xPx`.
+*
+* One implementation for both backends. The ordering rule is prose in
+* `types.ts`, and two backends reading that prose separately is the
+* divergence the display list exists to prevent: a run occupies
+* `[xPx, xPx + sum(advancesPx)]` whichever way it runs, so under `ltr` code
+* point `i` starts at `sum(advancesPx[0..i))` and under `rtl` it ends there,
+* counted back from the run's right edge. A backend adds its own origin: the
+* left edge is where a glyph is placed in either direction, because a glyph
+* advances rightward from its origin whatever the paragraph does.
+*/
+const glyphCellOffsetsPx = (run) => {
+	const totalPx = run.advancesPx.reduce((total, advance) => total + advance, 0);
+	const offsetsPx = [];
+	let consumedPx = 0;
+	for (const advancePx of run.advancesPx) {
+		offsetsPx.push(run.direction === "ltr" ? consumedPx : totalPx - consumedPx - advancePx);
+		consumedPx += advancePx;
+	}
+	return offsetsPx;
+};
+const DISPLAY_PRIMITIVE_KINDS = Object.values({
+	glyphRun: "glyphRun",
+	rect: "rect",
+	line: "line",
+	image: "image",
+	clipGroup: "clipGroup",
+	rotateGroup: "rotateGroup",
+	opacityGroup: "opacityGroup"
+});
+/**
+* Dash geometry of each stroke pattern, as multiples of the stroke thickness.
+*
+* `null` means the pattern is not a dash: `solid` draws one unbroken line,
+* `double` two parallel lines, `wavy` a periodic curve. Sharing the factors is
+* what keeps a dashed underline in the editor and a dashed underline in the
+* export the same dash: with the pattern name alone, each backend would pick
+* its own period and nobody would notice until the two were laid side by side.
+*/
+const STROKE_DASH_FACTORS = {
+	solid: null,
+	dashed: {
+		dash: 3,
+		gap: 2
+	},
+	dotted: {
+		dash: 1,
+		gap: 1
+	},
+	double: null,
+	wavy: null
+};
+/**
+* Gap between the two lines of a `double` stroke, as a multiple of thickness.
+* Word draws the pair at the authored width with an equal gap between them.
+*/
+const DOUBLE_STROKE_GAP_FACTOR = 1;
+/**
+* Period and peak-to-peak amplitude of a `wavy` stroke, in thicknesses.
+*
+* The amplitude is measured between the centres of the curve at its extremes,
+* so the stroke's own thickness lies outside it: a wavy stroke's total cross
+* extent is `(WAVY_STROKE_AMPLITUDE_FACTOR + 1) * thicknessPx`, centred on the
+* path. Stated because "amplitude" alone leaves each backend to decide whether
+* the thickness is inside or outside, and the two answers differ by a
+* thickness on every wavy underline in the document.
+*/
+const WAVY_STROKE_PERIOD_FACTOR = 6;
+const WAVY_STROKE_AMPLITUDE_FACTOR = 2;
+const BLACK = {
+	r: 0,
+	g: 0,
+	b: 0,
+	a: 1
+};
+const WHITE = {
+	r: 255,
+	g: 255,
+	b: 255,
+	a: 1
+};
+/**
+* The kinds of region a click can land in, as a total map over the union: a
+* new kind that is not listed fails to compile, and so does a name that is not
+* a kind.
+*/
+const HIT_REGION_KINDS = {
+	pageContent: "pageContent",
+	headerSlot: "headerSlot",
+	footerSlot: "footerSlot",
+	note: "note",
+	paragraph: "paragraph",
+	line: "line",
+	emptyRun: "emptyRun",
+	tab: "tab",
+	image: "image",
+	table: "table",
+	tableRow: "tableRow",
+	tableCell: "tableCell",
+	textBox: "textBox"
+};
+const walkRegions = (primitives, regions, visitor) => {
+	const visit = (from, to, children) => {
+		let cursor = from;
+		for (const child of children) {
+			for (; cursor < child.from; cursor += 1) {
+				const primitive = primitives[cursor];
+				if (primitive !== void 0) visitor.onPrimitive(primitive, cursor);
+			}
+			visitor.enter(child);
+			visit(child.from, child.to, child.children);
+			visitor.exit(child);
+			cursor = child.to;
+		}
+		for (; cursor < to; cursor += 1) {
+			const primitive = primitives[cursor];
+			if (primitive !== void 0) visitor.onPrimitive(primitive, cursor);
+		}
+	};
+	visit(0, primitives.length, regions);
+};
+//#endregion
+export { BLACK, DISPLAY_PRIMITIVE_KINDS, DOUBLE_STROKE_GAP_FACTOR, HIT_REGION_KINDS, STROKE_DASH_FACTORS, WAVY_STROKE_AMPLITUDE_FACTOR, WAVY_STROKE_PERIOD_FACTOR, WHITE, glyphCellOffsetsPx, hasComplexScript, hasCursiveLetter, isComplexScriptCodePoint, joinsAcrossBoundary, walkRegions };