reamkit 1.21.0 → 1.22.0

package/dist/esm/core/metafile/emf.js

@@ -1,5 +1,6 @@
 import { PathBuilder } from "../vector.js";
 import { applyTransform, cloneDc, colorRef, newDeviceContext } from "./picture.js";
+import { fromSymbolFont } from "./symbol-fonts.js";
 //#region src/core/metafile/emf.ts
 /** Whether the bytes open with an EMF header (MS-EMF §2.3.4.2: type 1 + " EMF"). */
 function isEmf(bytes) {
@@ -371,7 +372,7 @@ function readEmf(bytes) {
 						const font = dc.font;
 						prims.push({
 							kind: "text",
-							text,
+							text: fromSymbolFont(text, font?.family),
 							x: p.x,
 							y: p.y,
 							alignH: dc.alignH,

package/dist/esm/core/metafile/symbol-fonts.d.ts

@@ -0,0 +1,42 @@
+import { VectorPath } from '../vector.js';
+/**
+ * The geometry a symbol character DRAWS, for the handful that are plain shapes.
+ *
+ * Translating them to Unicode is not enough on its own: the substitute font a
+ * document renders with has no `●` either, and a missing glyph is a box with
+ * its code number in it — which is what 45541_Footer's table filled sixty-eight
+ * cells with. A shape this simple is better drawn than spelled.
+ *
+ * Measured off the fonts themselves: both fill the em square, one unit wide,
+ * from 0.2 em below the baseline to 0.8 em above it.
+ */
+export type SymbolGeometry = 'circle' | 'square' | 'diamond';
+/**
+ * The shapes a symbol string draws, one per character, or `undefined` when any
+ * character is not one of them — a string that mixes a pictogram with a circle
+ * stays text, which is the safer half of the trade.
+ *
+ * @param text   The string as stored.
+ * @param family The typeface it is drawn with.
+ */
+export declare function symbolGeometryOf(text: string, family: string | undefined): Array<SymbolGeometry> | undefined;
+/**
+ * The outline of one symbol in a box, as the path segments a picture draws.
+ *
+ * @param shape  Which symbol.
+ * @param left   The box's left edge, in the metafile's logical units.
+ * @param top    Its top edge (y grows DOWN, as a metafile has it).
+ * @param size   The em, which is both the width and the height of the box.
+ * @returns The closed outline.
+ */
+export declare function symbolOutline(shape: SymbolGeometry, left: number, top: number, size: number): VectorPath;
+/** Whether a typeface's characters are symbols rather than letters. */
+export declare function isSymbolFont(family: string | undefined): boolean;
+/**
+ * Translate a string drawn in a symbol font to the Unicode that means the same.
+ *
+ * @param text   The string as the metafile stored it.
+ * @param family The typeface it was drawn with.
+ * @returns The translated string; characters with no counterpart are kept.
+ */
+export declare function fromSymbolFont(text: string, family: string | undefined): string;

package/dist/esm/core/metafile/symbol-fonts.js

@@ -0,0 +1,154 @@
+import { PathBuilder } from "../vector.js";
+//#region src/core/metafile/symbol-fonts.ts
+/** Half a circle's control-point distance for a cubic quarter-arc. */
+var KAPPA = .5522847498307936;
+/**
+* The shapes a symbol string draws, one per character, or `undefined` when any
+* character is not one of them — a string that mixes a pictogram with a circle
+* stays text, which is the safer half of the trade.
+*
+* @param text   The string as stored.
+* @param family The typeface it is drawn with.
+*/
+function symbolGeometryOf(text, family) {
+	const table = family === void 0 ? void 0 : GEOMETRY_TABLES.get(normalize(family));
+	if (!table || text.length === 0) return void 0;
+	const out = [];
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		const key = code >= 61440 && code <= 61695 ? code - 61440 : code;
+		const shape = table.get(key);
+		if (shape === void 0) return void 0;
+		out.push(shape);
+	}
+	return out;
+}
+/**
+* The outline of one symbol in a box, as the path segments a picture draws.
+*
+* @param shape  Which symbol.
+* @param left   The box's left edge, in the metafile's logical units.
+* @param top    Its top edge (y grows DOWN, as a metafile has it).
+* @param size   The em, which is both the width and the height of the box.
+* @returns The closed outline.
+*/
+function symbolOutline(shape, left, top, size) {
+	const b = new PathBuilder();
+	const r = size / 2;
+	const [cx, cy] = [left + r, top + r];
+	if (shape === "circle") {
+		const k = r * KAPPA;
+		return b.moveTo(cx, top).cubicTo(cx + k, top, left + size, cy - k, left + size, cy).cubicTo(left + size, cy + k, cx + k, top + size, cx, top + size).cubicTo(cx - k, top + size, left, cy + k, left, cy).cubicTo(left, cy - k, cx - k, top, cx, top).close().build();
+	}
+	if (shape === "diamond") return b.moveTo(cx, top).lineTo(left + size, cy).lineTo(cx, top + size).lineTo(left, cy).close().build();
+	return b.moveTo(left, top).lineTo(left + size, top).lineTo(left + size, top + size).lineTo(left, top + size).close().build();
+}
+/**
+* Translate a string drawn in a symbol font to the Unicode that means the same.
+*
+* @param text   The string as the metafile stored it.
+* @param family The typeface it was drawn with.
+* @returns The translated string; characters with no counterpart are kept.
+*/
+function fromSymbolFont(text, family) {
+	const table = family === void 0 ? void 0 : SYMBOL_TABLES.get(normalize(family));
+	if (!table) return text;
+	let out = "";
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		const key = code >= 61440 && code <= 61695 ? code - 61440 : code;
+		out += table.get(key) ?? ch;
+	}
+	return out;
+}
+function normalize(family) {
+	return family.trim().toLowerCase();
+}
+var WINGDINGS = new Map([
+	[108, "●"],
+	[109, "❍"],
+	[110, "■"],
+	[111, "□"],
+	[112, "❑"],
+	[113, "❒"],
+	[114, "▪"],
+	[115, "▪"],
+	[116, "▫"],
+	[117, "◆"],
+	[118, "❖"],
+	[119, "◇"],
+	[120, "✗"],
+	[159, "•"],
+	[167, "▪"],
+	[252, "✔"],
+	[253, "✘"],
+	[254, "☑"],
+	[255, "☒"]
+]);
+var WEBDINGS = new Map([
+	[103, "■"],
+	[108, "■"],
+	[110, "●"],
+	[111, "○"],
+	[112, "□"],
+	[114, "◆"],
+	[115, "▲"],
+	[116, "▼"],
+	[161, "●"]
+]);
+var SYMBOL = new Map([
+	[97, "α"],
+	[98, "β"],
+	[99, "χ"],
+	[100, "δ"],
+	[101, "ε"],
+	[102, "φ"],
+	[103, "γ"],
+	[104, "η"],
+	[108, "λ"],
+	[109, "μ"],
+	[112, "π"],
+	[114, "ρ"],
+	[115, "σ"],
+	[116, "τ"],
+	[119, "ω"],
+	[183, "•"],
+	[215, "×"],
+	[177, "±"],
+	[163, "≤"],
+	[179, "≥"],
+	[185, "≠"],
+	[187, "≈"]
+]);
+var WINGDINGS_GEOMETRY = new Map([
+	[108, "circle"],
+	[110, "square"],
+	[111, "square"],
+	[114, "square"],
+	[115, "square"],
+	[117, "diamond"],
+	[119, "diamond"]
+]);
+var GEOMETRY_TABLES = new Map([
+	["wingdings", WINGDINGS_GEOMETRY],
+	["wingdings 2", WINGDINGS_GEOMETRY],
+	["wingdings 3", WINGDINGS_GEOMETRY],
+	["webdings", new Map([
+		[103, "square"],
+		[108, "square"],
+		[110, "circle"]
+	])],
+	["monotype sorts", WINGDINGS_GEOMETRY],
+	["zapfdingbats", WINGDINGS_GEOMETRY]
+]);
+var SYMBOL_TABLES = new Map([
+	["wingdings", WINGDINGS],
+	["wingdings 2", WINGDINGS],
+	["wingdings 3", WINGDINGS],
+	["webdings", WEBDINGS],
+	["symbol", SYMBOL],
+	["monotype sorts", WINGDINGS],
+	["zapfdingbats", WINGDINGS]
+]);
+//#endregion
+export { fromSymbolFont, symbolGeometryOf, symbolOutline };

package/dist/esm/core/metafile/wmf.js

@@ -1,5 +1,6 @@
 import { PathBuilder } from "../vector.js";
 import { cloneDc, colorRef, newDeviceContext } from "./picture.js";
+import { fromSymbolFont, symbolGeometryOf, symbolOutline } from "./symbol-fonts.js";
 import { ellipseSegments } from "./emf.js";
 //#region src/core/metafile/wmf.ts
 var PLACEABLE_KEY = 2596720087;
@@ -289,14 +290,20 @@ function readWmf(bytes) {
 }
 function pushText(prims, dc, text, x, y) {
 	if (text.trim() === "") return;
+	const em = Math.abs(dc.font?.heightLu ?? 12);
+	const drawn = symbolPrims(text, dc, x, y, em);
+	if (drawn) {
+		prims.push(...drawn);
+		return;
+	}
 	prims.push({
 		kind: "text",
-		text,
+		text: fromSymbolFont(text, dc.font?.family),
 		x,
 		y,
 		alignH: dc.alignH,
 		alignBaseline: dc.alignBaseline,
-		sizeLu: Math.abs(dc.font?.heightLu ?? 12),
+		sizeLu: em,
 		colorHex: dc.textColorHex,
 		...dc.font?.family ? { fontFamily: dc.font.family } : {},
 		...dc.font?.bold ? { bold: true } : {},
@@ -367,5 +374,31 @@ function polySegments(pts, closed) {
 	if (closed) segs.push({ op: "close" });
 	return segs;
 }
+/**
+* The symbols a text record draws, as filled outlines, or `undefined` when the
+* string is not one the shapes cover.
+*
+* Both fonts advance one em per symbol and fill that em, sitting from 0.2 em
+* below the baseline to 0.8 em above it — measured off Webdings itself.
+*
+* @param text The string as stored.
+* @param dc   The device context (font, colour, alignment).
+* @param x    The reference point's x, in logical units.
+* @param y    Its y — the text's top unless the context says baseline.
+* @param em   The font's height in logical units.
+* @returns One filled path per character, or `undefined`.
+*/
+function symbolPrims(text, dc, x, y, em) {
+	const shapes = symbolGeometryOf(text, dc.font?.family);
+	if (!shapes) return void 0;
+	const width = em * shapes.length;
+	const left = dc.alignH === "center" ? x - width / 2 : dc.alignH === "right" ? x - width : x;
+	const top = dc.alignBaseline ? y - em * .8 : y;
+	return shapes.map((shape, i) => ({
+		kind: "path",
+		paths: [symbolOutline(shape, left + i * em, top, em)],
+		fillColorHex: dc.textColorHex
+	}));
+}
 //#endregion
 export { isWmf, readWmf };

package/dist/esm/core/vector.d.ts

@@ -49,6 +49,11 @@ export interface GradientStop {
     readonly offset: number;
     /** Stop colour as 6-hex, no leading `#`. */
     readonly colorHex: string;
+    /**
+     * §20.1.2.3.1 `a:alpha` — how opaque THIS stop is, `0..1`; absent is opaque.
+     * The colour beside it is the stop's own, not composited over the paper.
+     */
+    readonly alpha?: number;
 }
 /**
  * A gradient fill — the format-agnostic vocabulary shared by the shape model

package/dist/esm/excel/sheet-shape-parser.js

@@ -1,6 +1,6 @@
 import { emuToPt, pt } from "../core/ir/units.js";
 import { poAttr, poChildren, poFirstChild, poIntAttr, poIs, poTag, poText } from "../core/po-helpers.js";
-import { applyColorMods, resolveColorNode } from "../core/drawingml/colors.js";
+import { placeholderColors, resolveColorNode } from "../core/drawingml/colors.js";
 import { parseFill, parseLine, parseShadow, parseXfrm, shadowFromOuterShdw } from "../word/drawing-parser.js";
 import { parseGeometry, parseTxBody } from "../pptx/slide-parser.js";
 import { parseXml } from "../pptx/pptx-reader.js";
@@ -387,17 +387,6 @@ function styleFill(sp, ns, colors, themeFillStyles) {
 	} : themed;
 }
 /**
-* §20.1.4.2.10 — inside a theme's style list, `phClr` stands for "the colour the
-* reference names". Every other colour resolves as it always did.
-*
-* @param colors The workbook's own resolver.
-* @param phHex  The colour the `a:fillRef` / `a:lnRef` carries.
-* @returns A resolver that answers `phClr` with that colour, transforms and all.
-*/
-function placeholderColors(colors, phHex) {
-	return (raw) => "scheme" in raw && raw.scheme === "phClr" ? applyColorMods(phHex, raw.mods ?? []) : colors(raw);
-}
-/**
 * The shadow `<xdr:style><a:effectRef>` names, if it names one.
 *
 * §20.1.4.2.8, the same mechanism as the fill and the outline beside it: a

package/dist/esm/excel/xlsx-reader.d.ts

@@ -29,7 +29,7 @@ export declare function readXlsx(xlsx: Uint8Array, options?: ProjectSheetOptions
  */
 export declare function readXlsxToSheetDoc(xlsx: Uint8Array): SheetDoc;
 /**
- * The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP for
+ * The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP's directory for
  * `xl/workbook.xml` and reads it into a {@link SheetDoc}. The reader's native
  * tree is the SheetDoc; the facade/Ream project it to a {@link FlowDoc} for
  * rendering (E-SHEET SB1).

package/dist/esm/excel/xlsx-reader.js

@@ -1,7 +1,7 @@
 import { ResourceStore } from "../core/ir/resources.js";
 import { FEATURES } from "../core/ir/features.js";
 import { detectImageFormat } from "../core/images.js";
-import { bytesInclude, bytesIncludePartName } from "../core/bytes.js";
+import { bytesInclude, packageHasPart } from "../core/bytes.js";
 import { DEFAULT_THEME_PALETTE, makeColorResolver } from "../core/drawingml/colors.js";
 import { parseChart, withChartColorStyle } from "../core/drawingml/chart-parser.js";
 import { parseTheme, parseThemeEffectStyles, parseThemeFillStyles, parseThemeLineWidths } from "../core/drawingml/theme-parser.js";
@@ -651,7 +651,7 @@ function lighten(hex, amount) {
 	return `${hx(ch(16))}${hx(ch(8))}${hx(ch(0))}`;
 }
 /**
-* The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP for
+* The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP's directory for
 * `xl/workbook.xml` and reads it into a {@link SheetDoc}. The reader's native
 * tree is the SheetDoc; the facade/Ream project it to a {@link FlowDoc} for
 * rendering (E-SHEET SB1).
@@ -660,7 +660,7 @@ var xlsxReader = {
 	id: "xlsx",
 	produces: "sheet",
 	supports: new Set([FEATURES.text, FEATURES.tables]),
-	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesIncludePartName(bytes, "xl/workbook.xml"),
+	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && packageHasPart(bytes, "xl/workbook.xml"),
 	read: (bytes) => ({
 		doc: readXlsxToSheetDoc(bytes),
 		losses: []

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

@@ -242,6 +242,24 @@ export interface PageItemBase {
      * is treated as an artifact. Ignored when not tagging.
      */
     readonly structId?: number;
+    /**
+     * §20.4.2.3 `@behindDoc` — the item is BEHIND the page's content: a
+     * watermark, a slide's backdrop. Such items paint before everything else, in
+     * their own order. Without that they rode the ordinary passes, where every
+     * shape paints after every image — so a slide's white backdrop covered the
+     * photograph the slide is made of (corpus: tdf156808, tdf157635, tdf156856).
+     */
+    readonly behind?: boolean;
+    /**
+     * 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
+     * and under what comes after: an embedded diagram writes a label, lays a
+     * panel over it and writes the label again, offset, as its own drop shadow.
+     * Painted in the ordinary passes — every shape, then every line — the buried
+     * copy would show through the panel. Items sharing this id are held out of
+     * those passes and painted together, in list order.
+     */
+    readonly pictureId?: number;
     /**
      * Tagged PDF: explicitly mark this item as a pagination artifact (running
      * header/footer, §14.8.2.2.2). Distinguishes header/footer text from
@@ -314,6 +332,19 @@ export interface ImageItem extends PageItemBase {
         readonly gain: number;
         readonly black: number;
     };
+    /**
+     * §20.1.8.4 `a:alphaModFix` — how opaque the picture is drawn, 0…1. A slide
+     * backed by a photograph at 70 % shows a pale wash of it, not the photograph.
+     */
+    readonly alpha?: number;
+    /**
+     * §20.1.8.23 `a:duotone` — the picture painted between two colours instead of
+     * its own: its dark end is the first, its light end the second.
+     */
+    readonly duotone?: {
+        readonly shadowHex: string;
+        readonly highlightHex: string;
+    };
     /** §20.1.7.6 — degrees clockwise about the box's centre. */
     readonly rotationDeg?: number;
     /** §20.1.7.6 — the picture drawn mirrored in its box. */
@@ -340,11 +371,18 @@ export interface ShapeItem extends PageItemBase {
 /** A positioned item on a laid-out page: a text line, border, fill, image, or vector shape. */
 export type PageItem = TextLineItem | BorderItem | FillItem | ImageItem | ShapeItem;
 export interface PagePaintPlan {
+    /** What sits behind the page's content, in its own order — painted first. */
+    readonly behind: ReadonlyArray<PageItem>;
     readonly fills: ReadonlyArray<FillItem>;
     readonly images: ReadonlyArray<ImageItem>;
     readonly borders: ReadonlyArray<BorderItem>;
     readonly shapes: ReadonlyArray<ShapeItem>;
     readonly lines: ReadonlyArray<TextLineItem>;
+    /**
+     * Pictures, each as its own list in the order the picture draws — one entry
+     * per {@link PageItemBase.pictureId}. They paint where the shape pass does.
+     */
+    readonly pictures: ReadonlyArray<ReadonlyArray<PageItem>>;
 }
 export declare function paintPlan(commands: ReadonlyArray<PageItem>): PagePaintPlan;
 export interface LaidOutDocument {

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

@@ -5,30 +5,46 @@ function paintPlan(commands) {
 	const borders = [];
 	const shapes = [];
 	const lines = [];
-	for (const c of commands) switch (c.type) {
-		case "fill":
-			fills.push(c);
-			break;
-		case "image":
-			images.push(c);
-			break;
-		case "border":
-			borders.push(c);
-			break;
-		case "shape":
-			shapes.push(c);
-			break;
-		case "line":
-			lines.push(c);
-			break;
-		default: assertNeverPageItem(c);
+	const pictures = /* @__PURE__ */ new Map();
+	const behind = [];
+	for (const c of commands) {
+		if (c.behind === true) {
+			behind.push(c);
+			continue;
+		}
+		if (c.pictureId !== void 0) {
+			const group = pictures.get(c.pictureId);
+			if (group) group.push(c);
+			else pictures.set(c.pictureId, [c]);
+			continue;
+		}
+		switch (c.type) {
+			case "fill":
+				fills.push(c);
+				break;
+			case "image":
+				images.push(c);
+				break;
+			case "border":
+				borders.push(c);
+				break;
+			case "shape":
+				shapes.push(c);
+				break;
+			case "line":
+				lines.push(c);
+				break;
+			default: assertNeverPageItem(c);
+		}
 	}
 	return {
+		behind,
 		fills,
 		images,
 		borders,
 		shapes,
-		lines
+		lines,
+		pictures: [...pictures.values()]
 	};
 }
 function assertNeverPageItem(item) {