reamkit 1.30.0 → 1.32.0

package/dist/esm/layout/page-doc.d.ts

@@ -198,12 +198,19 @@ export interface Line {
     readonly mathAscentPt?: number;
     readonly mathDescentPt?: number;
     /**
-     * E-PARITY: metric-derived single-line height and descent (Pt), the max over
-     * the line's text-token fonts under a non-default `layoutProfile`. Absent under
-     * `'ream'`, where leading stays the flat 1.2×/0.2 model (byte-identical).
+     * §17.3.1.33 — the line's single height and descent (Pt) from the faces on
+     * it, pictures included, where the line model reads faces (a Word document,
+     * or a renderer-compat `layoutProfile`). Absent under the flat 1.2×/0.2
+     * model.
      */
     readonly metricHeightPt?: number;
     readonly metricDescentPt?: number;
+    /**
+     * The line of its TEXT alone (the paragraph mark's, on a line with none):
+     * what a spacing of more lines adds per line, where a picture on the line
+     * adds nothing.
+     */
+    readonly metricTextHeightPt?: number;
 }
 /** An image bound into a {@link LaidOutDocument}: its resource name plus the decoded/validated bytes. */
 /**
@@ -289,6 +296,21 @@ export interface PageItemBase {
      * photograph the slide is made of (corpus: tdf156808, tdf157635, tdf156856).
      */
     readonly behind?: boolean;
+    /**
+     * The item stands IN FRONT of the page's text and covers it — a drawing
+     * floating over a spreadsheet's cells. A page paints its text after its
+     * shapes, so such items are painted as a second layer, every pass again,
+     * once the first layer's text is down.
+     */
+    readonly over?: boolean;
+    /**
+     * The part of the page the item may paint, when it is cut off — a
+     * spreadsheet's drawing printed in pieces, each piece seen only over the
+     * rows and columns of its own page (TableOverlay). Top-left frame, like the
+     * item itself. Items sharing a window paint together, in their own order,
+     * after the rest of their layer.
+     */
+    readonly window?: PageWindow;
     /**
      * The picture this item belongs to, when it is part of one. A metafile is a
      * list of drawing orders, and text among them is BOTH over what came before
@@ -306,6 +328,13 @@ export interface PageItemBase {
      */
     readonly artifact?: 'pagination';
 }
+/** A rectangle of the page, top-left frame: what a {@link PageItemBase.window} lets through. */
+export interface PageWindow {
+    readonly x: Pt;
+    readonly y: Pt;
+    readonly width: Pt;
+    readonly height: Pt;
+}
 /** A laid-out line of text (tokens carry their fonts/sizes/positions). */
 export interface TextLineItem extends PageItemBase {
     readonly type: 'line';
@@ -459,6 +488,35 @@ export interface PagePaintPlan {
     readonly ordered: ReadonlyArray<ReadonlyArray<PageItem>>;
 }
 export declare function paintPlan(commands: ReadonlyArray<PageItem>): PagePaintPlan;
+/**
+ * A page's items in the layers they paint in: first the page's own, then each
+ * group seen through a window of its own, then the same again for the items
+ * that stand in front of the page's text (PageItemBase.over). Each layer is
+ * painted pass by pass on its own, so a writer can cut a windowed one off with
+ * a single clip. A page with neither comes back as one layer, its items as
+ * they were.
+ *
+ * @param commands The page's items, in the order the layout placed them.
+ * @returns The layers, in paint order; empty ones left out.
+ */
+export declare function pageLayers(commands: ReadonlyArray<PageItem>): Array<{
+    readonly items: Array<PageItem>;
+    readonly window?: PageWindow;
+}>;
+/**
+ * The part of the page an item can paint, top-left frame — generous where it
+ * cannot be exact (a turned line, a turned picture), so that what falls
+ * outside it surely paints nothing there.
+ *
+ * @param item The item.
+ * @returns Its box: left, top, right and bottom edges.
+ */
+export declare function pageItemBounds(item: PageItem): {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+};
 export interface LaidOutDocument {
     readonly pages: ReadonlyArray<LaidOutPage>;
     readonly resources: ResourceStore;

package/dist/esm/layout/page-doc.js

@@ -60,8 +60,148 @@ function paintPlan(commands) {
 		ordered: [...ordered.entries()].sort((a, b) => (orderOf.get(a[0]) ?? 0) - (orderOf.get(b[0]) ?? 0)).map(([, run]) => run)
 	};
 }
+/**
+* A page's items in the layers they paint in: first the page's own, then each
+* group seen through a window of its own, then the same again for the items
+* that stand in front of the page's text (PageItemBase.over). Each layer is
+* painted pass by pass on its own, so a writer can cut a windowed one off with
+* a single clip. A page with neither comes back as one layer, its items as
+* they were.
+*
+* @param commands The page's items, in the order the layout placed them.
+* @returns The layers, in paint order; empty ones left out.
+*/
+function pageLayers(commands) {
+	if (!commands.some((c) => c.over === true || c.window !== void 0)) return [{ items: [...commands] }];
+	const out = [];
+	for (const over of [false, true]) {
+		const layer = commands.filter((c) => c.over === true === over);
+		const plain = layer.filter((c) => c.window === void 0);
+		if (plain.length > 0 || !over) out.push({ items: plain });
+		const windows = /* @__PURE__ */ new Map();
+		for (const c of layer) {
+			const w = c.window;
+			if (!w) continue;
+			const key = `${w.x} ${w.y} ${w.width} ${w.height}`;
+			const group = windows.get(key);
+			if (group) group.items.push(c);
+			else windows.set(key, {
+				items: [c],
+				window: w
+			});
+		}
+		out.push(...windows.values());
+	}
+	return out;
+}
+/**
+* The part of the page an item can paint, top-left frame — generous where it
+* cannot be exact (a turned line, a turned picture), so that what falls
+* outside it surely paints nothing there.
+*
+* @param item The item.
+* @returns Its box: left, top, right and bottom edges.
+*/
+function pageItemBounds(item) {
+	switch (item.type) {
+		case "fill": return {
+			x0: item.x,
+			y0: item.y,
+			x1: item.x + item.width,
+			y1: item.y + item.height
+		};
+		case "border": {
+			const half = item.borderSizePt / 2;
+			return {
+				x0: item.x - half,
+				y0: item.y - half,
+				x1: item.x + item.width + half,
+				y1: item.y + item.height + half
+			};
+		}
+		case "image": {
+			if (!item.rotationDeg) return {
+				x0: item.x,
+				y0: item.y,
+				x1: item.x + item.width,
+				y1: item.y + item.height
+			};
+			const r = Math.hypot(item.width, item.height) / 2;
+			const cx = item.x + item.width / 2;
+			const cy = item.y + item.height / 2;
+			return {
+				x0: cx - r,
+				y0: cy - r,
+				x1: cx + r,
+				y1: cy + r
+			};
+		}
+		case "line": {
+			if (item.clip) return {
+				x0: item.clip.x,
+				y0: item.clip.y,
+				x1: item.clip.x + item.clip.width,
+				y1: item.clip.y + item.clip.height
+			};
+			const size = item.line.maxFontSizePt;
+			const width = item.line.contentWidthPt;
+			if (item.rotationDeg || item.warp) {
+				const r = width + size;
+				return {
+					x0: item.originX - r,
+					y0: item.baselineY - r,
+					x1: item.originX + r,
+					y1: item.baselineY + r
+				};
+			}
+			return {
+				x0: item.originX,
+				y0: item.baselineY - size,
+				x1: item.originX + width,
+				y1: item.baselineY + (item.line.metricDescentPt ?? size * .25)
+			};
+		}
+		case "shape": {
+			const [a, b, c, d, e, f] = item.shape.transform;
+			let x0 = Infinity;
+			let y0 = Infinity;
+			let x1 = -Infinity;
+			let y1 = -Infinity;
+			const take = (x, y) => {
+				const px = a * x + c * y + e;
+				const py = b * x + d * y + f;
+				x0 = Math.min(x0, px);
+				y0 = Math.min(y0, py);
+				x1 = Math.max(x1, px);
+				y1 = Math.max(y1, py);
+			};
+			for (const path of item.shape.paths) for (const seg of path.segments) {
+				if (seg.op === "close") continue;
+				if (seg.op === "cubic") {
+					take(seg.x1, seg.y1);
+					take(seg.x2, seg.y2);
+				}
+				take(seg.x, seg.y);
+			}
+			if (x0 > x1) return {
+				x0: 0,
+				y0: 0,
+				x1: 0,
+				y1: 0
+			};
+			const pad = (item.shape.stroke?.widthPt ?? 0) / 2 + 1;
+			const sh = item.shape.shadow;
+			return {
+				x0: x0 - pad + Math.min(0, sh?.dxPt ?? 0) - (sh?.blurPt ?? 0),
+				y0: y0 - pad + Math.min(0, sh?.dyPt ?? 0) - (sh?.blurPt ?? 0),
+				x1: x1 + pad + Math.max(0, sh?.dxPt ?? 0) + (sh?.blurPt ?? 0),
+				y1: y1 + pad + Math.max(0, sh?.dyPt ?? 0) + (sh?.blurPt ?? 0)
+			};
+		}
+	}
+}
 function assertNeverPageItem(item) {
 	throw new Error(`Unhandled PageItem kind: ${String(item.type)}`);
 }
 //#endregion
-export { paintPlan };
+export { pageItemBounds, pageLayers, paintPlan };

package/dist/esm/layout/styled-layout.d.ts

@@ -7,6 +7,7 @@ import { LaidOutDocument, PageItem } from './page-doc.js';
 import { AttachedFile } from '../pdf/embedded-file.js';
 import { SignaturePlaceholder } from '../pdf/signature.js';
 import { PdfEncryptOptions } from '../pdf/encryption.js';
+import { Sheet } from './turned-section.js';
 import { StructTreeBuilder } from '../pdf/struct-tree.js';
 /**
  * PDF/A conformance string: part 1 (ISO 19005-1, PDF 1.4) / 2 (ISO 19005-2) / 3
@@ -24,15 +25,27 @@ export interface PdfAProfile {
     readonly version: '1.4' | '1.7';
 }
 /**
- * E-PARITY: renderer-compatibility profile for the line-height model.
- *   `'ream'` (default) — Ream's flat 1.2× leading; byte-identical to before.
- *   `'word'` — leading from the font's OS/2 usWin metrics (the GDI cell box).
- *   `'libreoffice'` — leading from hhea (or OS/2 typo when USE_TYPO_METRICS is set).
+ * E-PARITY: renderer-compatibility profile — how lines are measured, broken
+ * and stacked.
+ *   `'ream'` (default) — kerned measuring, Knuth-Plass breaking, and the line
+ *     height the document asks for (see {@link TypesetBy}).
+ *   `'word'` — kern-free measuring, first-fit breaking, and lines as Word sets
+ *     them whatever the document.
+ *   `'libreoffice'` — first-fit breaking, lines from the face in hand: hhea, or
+ *     the OS/2 typo line when USE_TYPO_METRICS is set.
  *
- * Opt-in: a profile emulates that renderer's vertical rhythm for closer visual
- * parity. It never changes default (`'ream'`) output.
+ * Opt-in: a profile emulates that renderer for closer visual parity.
  */
 export type LayoutProfile = 'ream' | 'word' | 'libreoffice';
+/**
+ * The application whose rules a document is set by: `'word'` stands its
+ * lines as tall as the faces on them make them (§17.3.1.33, see
+ * `fontLeadingPt`) rather than Ream's flat 1.2× of the size, and gives every
+ * horizontal table border the room it is wide (§17.4.38, see
+ * `withBorderBands`) rather than none. A Word document's reader asks for it
+ * (see `FlowDoc.typesetBy`).
+ */
+export type TypesetBy = 'word';
 /**
  * The full option set the layout engine and PDF emitter consume: the resolved
  * font registry, the style/numbering tables, the section model and page
@@ -46,6 +59,15 @@ export interface StyledRenderOptions {
     readonly registry: FontRegistry;
     /** Renderer-compatibility profile for the line-height model (default `'ream'`). */
     readonly layoutProfile?: LayoutProfile;
+    /** The application whose rules the document is set by (see {@link TypesetBy}). */
+    readonly typesetBy?: TypesetBy;
+    /**
+     * The document's front floats COVER the text under them. A spreadsheet's
+     * drawings float over its cells — a note's box hides the value beside its
+     * cell, a chart the data it sits on — where the passes a page is painted in
+     * put every line of text over every shape. See `FlowDoc.floatsOverText`.
+     */
+    readonly floatsOverText?: boolean;
     /**
      * Per-run font resolution: when supplied, each text run picks the registry of
      * its declared family (sans→arimo / serif→tinos / mono→cousine via the run's
@@ -173,6 +195,12 @@ export interface StyledRenderOptions {
      * TOP margin, not the left.
      */
     readonly gutterAtTop?: boolean;
+    /**
+     * [MS-DOCX] `compatibilityMode` — the version of Word whose layout the
+     * document asks for; a Word document that states none is an older Word's
+     * (see {@link legacyTableOutdent}).
+     */
+    readonly compatibilityMode?: number;
     /**
      * §7.6 PDF encryption (AES-256, R6). Only honoured on the ASYNC conversion
      * path (WebCrypto); mutually exclusive with `pdfA` (ISO 19005 forbids
@@ -302,6 +330,12 @@ export interface SectionRenderCtx {
     }>;
     readonly headerSet: HeaderFooterSet;
     readonly footerSet: HeaderFooterSet;
+    /**
+     * §17.10 — where the body starts and ends on a page that shows each band:
+     * below the header band and above the footer band that page carries, each
+     * as tall as it is. Absent ⇒ every page takes `marginTop`/`marginBottom`.
+     */
+    readonly bandMargins?: Readonly<Record<HfBand, BodyMargins>>;
     readonly titlePg: boolean;
     readonly evenAndOddHeaders: boolean;
     /**
@@ -316,10 +350,24 @@ export interface SectionRenderCtx {
      * paragraph in it. Absent on a bare context built outside a layout run.
      */
     readonly options?: StyledRenderOptions;
+    /**
+     * §17.6.20 — the sheet a section whose lines run DOWN it prints on. Such a
+     * section's body is laid out in the frame its text reads in, which the
+     * geometry above describes — the sheet turned back a quarter — and turned
+     * onto this sheet page by page, while its header and footer are laid out
+     * on the sheet itself (see ./turned-section). Absent ⇒ the frame is the sheet.
+     */
+    readonly sheet?: Sheet;
+}
+type HfBand = 'default' | 'first' | 'even';
+/** The distances from the paper's top and bottom edges to the body's. */
+interface BodyMargins {
+    readonly top: number;
+    readonly bottom: number;
 }
 interface HfBandEntry {
     readonly commands: Array<PageItem>;
-    readonly renderDynamic?: (pageNumber: number, totalPages: number) => Array<PageItem>;
+    readonly renderDynamic?: (pageText: string, totalPages: number) => Array<PageItem>;
     /** Laid-out height of the band, so the body can be kept clear of it. */
     readonly heightPt?: number;
 }