reamkit 1.22.0 → 1.24.0

package/dist/esm/core/drawingml/diagram/run.d.ts

@@ -0,0 +1,37 @@
+import { PoNode } from '../../po-helpers.js';
+/** The parts a diagram is run from, as the reader resolved them. */
+export interface DiagramParts {
+    readonly data: Uint8Array;
+    readonly layout?: Uint8Array | undefined;
+    readonly colors?: Uint8Array | undefined;
+}
+/**
+ * The picture a drawing part caches, when it caches one at all.
+ *
+ * A generator may write the drawing part and put nothing in it — the group
+ * properties and no `dsp:sp` at all. That is a placeholder the generator never
+ * got round to filling, not a diagram drawn as empty, and taking it at its word
+ * paints a blank frame over a diagram whose data, layout and colours are all
+ * present. So an empty tree reads as no tree, and the caller runs the layout
+ * exactly as it does for a file that ships no drawing part in the first place.
+ *
+ * @param drawing The drawing part's bytes.
+ * @param parse   The reader's XML parser.
+ * @returns The cached `dsp:spTree`, or undefined when there is none to use.
+ */
+export declare function cachedDiagramTree(drawing: Uint8Array, parse: (bytes: Uint8Array) => Array<PoNode>): PoNode | undefined;
+/**
+ * The `dsp:spTree` a diagram's own parts describe, for a file that ships no
+ * cached drawing.
+ *
+ * @param parts The diagram's data, layout and colours parts.
+ * @param frame The extent the drawing gives the diagram, in EMU.
+ * @param parse The reader's XML parser (the same tree shape either way).
+ * @returns The shape tree, or undefined when there is no layout part or the
+ *          layout uses an algorithm this engine does not run — the caller then
+ *          reports the diagram as a loss exactly as before.
+ */
+export declare function laidOutDiagramTree(parts: DiagramParts, frame: {
+    readonly cx: number;
+    readonly cy: number;
+}, parse: (bytes: Uint8Array) => Array<PoNode>): PoNode | undefined;

package/dist/esm/core/drawingml/diagram/run.js

@@ -0,0 +1,50 @@
+import { poChildren, poFindDescendant, poIs } from "../../po-helpers.js";
+import { DiagramColors } from "./colors.js";
+import { DiagramData } from "./data-model.js";
+import { layoutDiagram } from "./layout-engine.js";
+import { diagramDrawingXml } from "./to-drawing.js";
+//#region src/core/drawingml/diagram/run.ts
+/**
+* The picture a drawing part caches, when it caches one at all.
+*
+* A generator may write the drawing part and put nothing in it — the group
+* properties and no `dsp:sp` at all. That is a placeholder the generator never
+* got round to filling, not a diagram drawn as empty, and taking it at its word
+* paints a blank frame over a diagram whose data, layout and colours are all
+* present. So an empty tree reads as no tree, and the caller runs the layout
+* exactly as it does for a file that ships no drawing part in the first place.
+*
+* @param drawing The drawing part's bytes.
+* @param parse   The reader's XML parser.
+* @returns The cached `dsp:spTree`, or undefined when there is none to use.
+*/
+function cachedDiagramTree(drawing, parse) {
+	for (const root of parse(drawing)) {
+		const found = poFindDescendant(root, "dsp:spTree");
+		if (found && poChildren(found).some((c) => poIs(c, "dsp:sp"))) return found;
+	}
+}
+/**
+* The `dsp:spTree` a diagram's own parts describe, for a file that ships no
+* cached drawing.
+*
+* @param parts The diagram's data, layout and colours parts.
+* @param frame The extent the drawing gives the diagram, in EMU.
+* @param parse The reader's XML parser (the same tree shape either way).
+* @returns The shape tree, or undefined when there is no layout part or the
+*          layout uses an algorithm this engine does not run — the caller then
+*          reports the diagram as a loss exactly as before.
+*/
+function laidOutDiagramTree(parts, frame, parse) {
+	if (!parts.layout) return void 0;
+	const data = new DiagramData(parse(parts.data));
+	const nodes = layoutDiagram(parse(parts.layout), data, frame.cx, frame.cy);
+	if (nodes.length === 0) return void 0;
+	const xml = diagramDrawingXml(nodes, frame, parts.colors ? new DiagramColors(parse(parts.colors)) : void 0, data.background);
+	for (const root of parse(new TextEncoder().encode(xml))) {
+		const found = poFindDescendant(root, "dsp:spTree");
+		if (found) return found;
+	}
+}
+//#endregion
+export { cachedDiagramTree, laidOutDiagramTree };

package/dist/esm/core/drawingml/diagram/to-drawing.d.ts

@@ -0,0 +1,16 @@
+import { DiagramColors } from './colors.js';
+import { LaidNode } from './layout-engine.js';
+import { PoNode } from '../../po-helpers.js';
+/**
+ * A `dsp:drawing` for boxes the engine laid out.
+ *
+ * @param nodes  The laid-out boxes, in the diagram's own EMU frame.
+ * @param frame  The frame the slide gives the diagram.
+ * @param colors The colours part, when the file carries one.
+ * @param bg     §21.4.2.4 `dgm:bg` — the fill behind the whole diagram.
+ * @returns The XML text of the drawing part.
+ */
+export declare function diagramDrawingXml(nodes: ReadonlyArray<LaidNode>, frame: {
+    readonly cx: number;
+    readonly cy: number;
+}, colors?: DiagramColors, bg?: PoNode): string;

package/dist/esm/core/drawingml/diagram/to-drawing.js

@@ -0,0 +1,86 @@
+import { poAttr, poChildren, poIs, poText } from "../../po-helpers.js";
+import { pointPaint } from "./colors.js";
+//#region src/core/drawingml/diagram/to-drawing.ts
+var NS = "xmlns:dsp=\"http://schemas.microsoft.com/office/drawing/2008/diagram\" xmlns:a=\"http://schemas.openxmlformats.org/drawingml/2006/main\"";
+/**
+* A `dsp:drawing` for boxes the engine laid out.
+*
+* @param nodes  The laid-out boxes, in the diagram's own EMU frame.
+* @param frame  The frame the slide gives the diagram.
+* @param colors The colours part, when the file carries one.
+* @param bg     §21.4.2.4 `dgm:bg` — the fill behind the whole diagram.
+* @returns The XML text of the drawing part.
+*/
+function diagramDrawingXml(nodes, frame, colors, bg) {
+	const back = pointPaint(bg).fill;
+	const panel = back === void 0 ? "" : `<dsp:sp><dsp:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${r(frame.cx)}" cy="${r(frame.cy)}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom>${back}<a:ln><a:noFill/></a:ln></dsp:spPr><dsp:txBody><a:bodyPr/><a:lstStyle/><a:p/></dsp:txBody></dsp:sp>`;
+	const shapes = nodes.map((n) => {
+		const off = `<a:off x="${r(n.x)}" y="${r(n.y)}"/><a:ext cx="${r(n.cx)}" cy="${r(n.cy)}"/>`;
+		const own = pointPaint(n.point.spPr);
+		const paint = n.hideGeom === true ? "<a:noFill/><a:ln><a:noFill/></a:ln>" : (own.fill ?? colors?.fill(n.styleLbl, n.index) ?? (colors?.knows(n.styleLbl) === true ? "<a:noFill/>" : "<a:solidFill><a:schemeClr val=\"accent1\"/></a:solidFill>")) + (own.line ?? colors?.line(n.styleLbl, n.index) ?? "");
+		const text = colors?.textFill(n.styleLbl, n.index);
+		return `<dsp:sp><dsp:spPr><a:xfrm${n.rotation60k !== void 0 ? ` rot="${r(n.rotation60k)}"` : ""}>${off}</a:xfrm><a:prstGeom prst="${esc(n.shapeType)}"><a:avLst/></a:prstGeom>${paint}</dsp:spPr><dsp:style><a:fontRef idx="minor"><a:schemeClr val="lt1"/></a:fontRef></dsp:style><dsp:txBody>${bodyXml(n, text)}</dsp:txBody></dsp:sp>`;
+	}).join("");
+	return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<dsp:drawing ${NS}><dsp:spTree>${`<dsp:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${r(frame.cx)}" cy="${r(frame.cy)}"/><a:chOff x="0" y="0"/><a:chExt cx="${r(frame.cx)}" cy="${r(frame.cy)}"/></a:xfrm></dsp:grpSpPr>`}${panel}${shapes}</dsp:spTree></dsp:drawing>`;
+}
+function bodyXml(node, textFill) {
+	const paragraphs = [];
+	for (const p of node.point.text ? poChildren(node.point.text) : []) {
+		if (!poIs(p, "a:p")) continue;
+		let runs = "";
+		for (const r of poChildren(p)) {
+			if (poIs(r, "a:br")) {
+				runs += "<a:br/>";
+				continue;
+			}
+			if (!poIs(r, "a:r")) continue;
+			const text = poText(poChildren(r).find((c) => poIs(c, "a:t")));
+			if (text !== "") {
+				const src = poChildren(r).find((c) => poIs(c, "a:rPr"));
+				const stated = poAttr(src, "sz");
+				const sz = stated !== void 0 ? ` sz="${esc(stated)}"` : node.fontSizePt === void 0 ? "" : ` sz="${Math.round(node.fontSizePt * 100)}"`;
+				const emph = [
+					"b",
+					"i",
+					"u"
+				].map((a) => {
+					const v = poAttr(src, a);
+					return v === void 0 ? "" : ` ${a}="${esc(v)}"`;
+				}).join("");
+				const rPr = textFill === void 0 ? `<a:rPr lang="en-US"${sz}${emph}/>` : `<a:rPr lang="en-US"${sz}${emph}>${textFill}</a:rPr>`;
+				runs += `<a:r>${rPr}<a:t>${esc(text)}</a:t></a:r>`;
+			}
+		}
+		if (runs !== "") paragraphs.push(`<a:p>${paraPr(node, p)}${runs}</a:p>`);
+	}
+	const body = `<a:bodyPr anchor="${node.anchor === void 0 ? "ctr" : esc(node.anchor)}"${node.bulleted === true ? " anchorCtr=\"0\"" : ""}><a:normAutofit/></a:bodyPr><a:lstStyle/>`;
+	return paragraphs.length > 0 ? body + paragraphs.join("") : `${body}<a:p/>`;
+}
+/**
+* One paragraph's properties. `bulletEnabled` on a layout node says only that
+* bullets are ALLOWED here; which bullet a paragraph actually takes — or that it
+* takes none — is the data part's to state, and smartart-missing-bullet is a
+* file of exactly two paragraphs, one `a:buNone` and one `a:buChar`, that came
+* out with the same marker on both. So a paragraph that states its own bullet or
+* its own alignment keeps them, and only one that states neither falls back to
+* the layout's answer: ranged left behind a bullet where the layout allows one,
+* centred where it does not.
+*/
+function paraPr(node, para) {
+	const src = poChildren(para).find((c) => poIs(c, "a:pPr"));
+	const bullet = poChildren(src).find((c) => poIs(c, "a:buNone") || poIs(c, "a:buChar") || poIs(c, "a:buAutoNum"));
+	const listed = bullet === void 0 ? node.bulleted === true : !poIs(bullet, "a:buNone");
+	const algn = poAttr(src, "algn") ?? node.align ?? (listed ? "l" : "ctr");
+	if (!listed) return `<a:pPr algn="${esc(algn)}"/>`;
+	const marL = poAttr(src, "marL") ?? "171450";
+	const indent = poAttr(src, "indent") ?? "-171450";
+	const char = bullet !== void 0 && poIs(bullet, "a:buChar") ? poAttr(bullet, "char") : void 0;
+	return `<a:pPr algn="${esc(algn)}" marL="${esc(marL)}" indent="${esc(indent)}"><a:buChar char="${esc(char ?? "•")}"/></a:pPr>`;
+}
+var r = (v) => Math.round(v);
+function esc(s) {
+	return s.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/"/gu, "&quot;");
+}
+//#endregion
+export { diagramDrawingXml };

package/dist/esm/core/drawingml/preset-geometry.js

@@ -75,6 +75,94 @@ function presetPaths(preset, w, h, adjust) {
 			])];
 		}
 		case "pentagon": return [regularPolygon(w, h, 5)];
+		case "heptagon": return [regularPolygon(w, h, 7)];
+		case "octagon": return [regularPolygon(w, h, 8, Math.PI / 8)];
+		case "decagon": return [regularPolygon(w, h, 10, Math.PI / 10)];
+		case "dodecagon": return [regularPolygon(w, h, 12, Math.PI / 12)];
+		case "donut": {
+			const t = clamp(frac(adjust, "adj", 25e3), 0, .5) * Math.min(w, h);
+			const b = new PathBuilder().append(ellipseSegments(w, h));
+			const [ix, iy] = [w / 2 - t, h / 2 - t];
+			if (ix > 0 && iy > 0) {
+				b.moveTo(w / 2 + ix, h / 2).append(arcToBeziers(w / 2, h / 2, ix, iy, 0, 2 * Math.PI));
+				b.close();
+			}
+			return [b.build("evenodd")];
+		}
+		case "frame": {
+			const t = clamp(frac(adjust, "adj", 12500), 0, .5) * Math.min(w, h);
+			return [new PathBuilder().moveTo(0, 0).lineTo(w, 0).lineTo(w, h).lineTo(0, h).close().moveTo(t, t).lineTo(w - t, t).lineTo(w - t, h - t).lineTo(t, h - t).close().build("evenodd")];
+		}
+		case "diagStripe": {
+			const a = clamp(frac(adjust, "adj", 5e4), 0, 1);
+			return [polygon([
+				[0, h - h * a],
+				[w * a, h],
+				[w, h],
+				[0, 0]
+			])];
+		}
+		case "teardrop": {
+			const a = clamp(frac(adjust, "adj", 1e5), 0, 2);
+			const [rx, ry] = [w / 2, h / 2];
+			return [new PathBuilder().moveTo(rx, h).append(arcToBeziers(rx, ry, rx, ry, Math.PI / 2, 3 * Math.PI / 2)).lineTo(w * (.5 + a / 2), h * (.5 + a / 2)).close().build()];
+		}
+		case "can": return cylinder(w, h, clamp(frac(adjust, "adj", 25e3), 0, .5) * h / 2);
+		case "halfFrame": {
+			const ss = Math.min(w, h);
+			const x1 = clamp(frac(adjust, "adj2", 33333), 0, 1) * ss;
+			const y1 = clamp(frac(adjust, "adj1", 33333), 0, 1) * ss;
+			const x2 = w - (h === 0 ? 0 : y1 * w / h);
+			const y2 = h - (w === 0 ? 0 : x1 * h / w);
+			return [polygon([
+				[0, 0],
+				[0, h],
+				[w, h],
+				[x2, h - y1],
+				[x1, h - y1],
+				[x1, h - y2]
+			])];
+		}
+		case "bevel": {
+			const t = clamp(frac(adjust, "adj", 12500), 0, .5) * Math.min(w, h);
+			const face = (pts) => polygon(pts);
+			return [
+				face([
+					[0, h],
+					[w, h],
+					[w - t, h - t],
+					[t, h - t]
+				]),
+				face([
+					[0, h],
+					[t, h - t],
+					[t, t],
+					[0, 0]
+				]),
+				face([
+					[w, 0],
+					[0, 0],
+					[t, t],
+					[w - t, t]
+				]),
+				face([
+					[w, 0],
+					[w - t, t],
+					[w - t, h - t],
+					[w, h]
+				]),
+				polygon([
+					[t, t],
+					[w - t, t],
+					[w - t, h - t],
+					[t, h - t]
+				])
+			];
+		}
+		case "plaque": {
+			const t = clamp(frac(adjust, "adj", 16667), 0, .5) * Math.min(w, h);
+			return [new PathBuilder().moveTo(t, 0).lineTo(w - t, 0).append(arcToBeziers(w, 0, t, t, Math.PI, -Math.PI / 2)).lineTo(w, h - t).append(arcToBeziers(w, h, t, t, 3 * Math.PI / 2, -Math.PI / 2)).lineTo(t, h).append(arcToBeziers(0, h, t, t, 0, -Math.PI / 2)).lineTo(0, t).append(arcToBeziers(0, 0, t, t, Math.PI / 2, -Math.PI / 2)).close().build()];
+		}
 		case "hexagon": {
 			const inset = clamp(frac(adjust, "adj", 25e3) * w, 0, w / 2);
 			return [polygon([
@@ -227,6 +315,7 @@ function presetPaths(preset, w, h, adjust) {
 				[0, h]
 			])];
 		}
+		case "pieWedge": return [new PathBuilder().moveTo(0, 0).append(arcToBeziers(w, 0, w, h, Math.PI, -Math.PI / 2)).lineTo(w, 0).close().build()];
 		case "pie":
 		case "blockArc": {
 			const [rx, ry] = [w / 2, h / 2];
@@ -306,10 +395,8 @@ function presetPaths(preset, w, h, adjust) {
 			[w / 2, h]
 		])];
 		case "flowChartDelay": return [new PathBuilder().moveTo(0, 0).lineTo(w / 2, 0).append(arcToBeziers(w / 2, h / 2, w / 2, h / 2, -Math.PI / 2, Math.PI)).lineTo(0, h).close().build()];
-		case "flowChartMagneticDisk": {
-			const ry = h / 6;
-			return [new PathBuilder().moveTo(0, h - ry).append(arcToBeziers(w / 2, h - ry, w / 2, ry, Math.PI, -2 * Math.PI)).moveTo(0, h - ry).lineTo(0, ry).append(arcToBeziers(w / 2, ry, w / 2, ry, Math.PI, -Math.PI)).lineTo(w, h - ry).build()];
-		}
+		case "flowChartMagneticDisk": return cylinder(w, h, h / 6);
+		case "flowChartMagneticDrum": return drum(w, h, w / 6);
 		case "flowChartMagneticTape": {
 			const foot = h / 8;
 			return [{ segments: ellipseSegments(w, h) }, polygon([
@@ -626,14 +713,37 @@ function star(w, h, preset, adjust) {
 	}
 	return polygon(pts);
 }
-function regularPolygon(w, h, n) {
+/**
+* A cylinder standing on its base: the body under its lid, and the lid drawn
+* again on top so its near edge shows.
+*
+* Both paths are wound the SAME way round. Wound against each other a nonzero
+* fill cancels the two and the top comes out hollow, which is how the flowchart
+* disk of tdf114848's fifth page had been drawn all along; and the base bulges
+* DOWN, which the same shape had going up.
+*/
+function cylinder(w, h, ry) {
+	const [rx, cx] = [w / 2, w / 2];
+	return [new PathBuilder().moveTo(0, ry).lineTo(0, h - ry).append(arcToBeziers(cx, h - ry, rx, ry, Math.PI, -Math.PI)).lineTo(w, ry).append(arcToBeziers(cx, ry, rx, ry, 0, -Math.PI)).close().build(), new PathBuilder().moveTo(w, h - ry).append(arcToBeziers(cx, h - ry, rx, ry, 0, -2 * Math.PI)).close().build()];
+}
+/**
+* A cylinder lying on its side: the body with a rounded end at each side, and
+* the near cap drawn again over the right one. Wound like {@link cylinder}, and
+* for the same reason — the two paths must turn the same way or a nonzero fill
+* cancels them.
+*/
+function drum(w, h, rx) {
+	const [ry, cy] = [h / 2, h / 2];
+	return [new PathBuilder().moveTo(w - rx, h).lineTo(rx, h).append(arcToBeziers(rx, cy, rx, ry, Math.PI / 2, Math.PI)).lineTo(w - rx, 0).append(arcToBeziers(w - rx, cy, rx, ry, -Math.PI / 2, Math.PI)).close().build(), new PathBuilder().moveTo(w, cy).append(arcToBeziers(w - rx, cy, rx, ry, 0, 2 * Math.PI)).close().build()];
+}
+function regularPolygon(w, h, n, turn = 0) {
 	const cx = w / 2;
 	const cy = h / 2;
 	const rx = w / 2;
 	const ry = h / 2;
 	const pts = [];
 	for (let i = 0; i < n; i++) {
-		const a = Math.PI / 2 + i * 2 * Math.PI / n;
+		const a = Math.PI / 2 + turn + i * 2 * Math.PI / n;
 		pts.push([cx + rx * Math.cos(a), cy + ry * Math.sin(a)]);
 	}
 	return polygon(pts);

package/dist/esm/core/drawingml/text-warp.d.ts

@@ -0,0 +1,58 @@
+/** The two edges of a warp at one horizontal position, `0`…`1` down the box. */
+export interface WarpEdges {
+    readonly top: number;
+    readonly bottom: number;
+}
+/**
+ * Whether a preset bends text at all. `textNoShape` is the "no warp" member of
+ * the enumeration and by far its most common value — two thirds of the decks
+ * that mention a warp state only this one — and a body carrying it is an
+ * ordinary text box, NOT WordArt stretched to its shape.
+ *
+ * @param preset The `a:prstTxWarp @prst` value.
+ * @returns Whether {@link textWarpEdges} can bend text through this preset.
+ */
+export declare function isTextWarp(preset: string): boolean;
+/**
+ * Where a warped body's two frames sit on the page: the shape's box, which the
+ * warped text is stretched onto, and the box the UN-warped block occupies.
+ * Both are in the page's top-left frame, y growing down.
+ */
+export interface WarpFrame {
+    readonly preset: string;
+    readonly adjust?: number;
+    readonly boxX: number;
+    readonly boxY: number;
+    readonly boxWidth: number;
+    readonly boxHeight: number;
+    readonly srcX: number;
+    readonly srcWidth: number;
+    readonly srcTop: number;
+    readonly srcHeight: number;
+}
+/**
+ * The matrix that places one glyph of a warped body.
+ *
+ * Maps the glyph's own text space — x along its advance, y UP from its
+ * baseline — into the page's top-left frame, as `[a, b, c, d, e, f]` with
+ * `px = a·x + c·y + e` and `py = b·x + d·y + f`. Upright text therefore has a
+ * negative `d`: the glyph's y runs against the page's.
+ *
+ * @param frame     The two frames, from the laid-out line.
+ * @param glyphX    The glyph's left edge in the un-warped block.
+ * @param advance   How wide the glyph is there.
+ * @param baselineY The line's baseline in the un-warped block.
+ * @returns The six numbers, or `undefined` where the warp leaves no room to
+ *          draw — the pinched end of a fade, or a preset this file cannot bend.
+ */
+export declare function warpGlyphMatrix(frame: WarpFrame, glyphX: number, advance: number, baselineY: number): readonly [number, number, number, number, number, number] | undefined;
+/**
+ * The two edges of a warp at one position across its box.
+ *
+ * @param preset The `a:prstTxWarp @prst` value.
+ * @param u      Position across the box, `0` at its left edge and `1` at its right.
+ * @param adj    The `a:avLst` `adj` guide in hundred-thousandths, when the file states one.
+ * @returns The top and bottom edges, `0`…`1` down the box, or `undefined` for a
+ *          preset this file does not bend (an unknown name, or `textNoShape`).
+ */
+export declare function textWarpEdges(preset: string, u: number, adj?: number): WarpEdges | undefined;