@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/watermarkParser.js

@@ -0,0 +1,348 @@
+import { cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findChild, findChildren, findDeep, getAttribute, getLocalName, getTextContent } from "./xmlParser.js";
+//#region src/docx/watermarkParser.ts
+const VML_TEXT_WATERMARK_SHAPETYPE = "#_x0000_t136";
+/**
+* Word's own UI emits picture watermarks with a shape id beginning
+* `WordPictureWatermark`. A logo image dropped into a header from the
+* ribbon gets a plain auto-id like `_x0000_s1025`, so this prefix is
+* the cleanest signal to separate real picture watermarks from
+* ordinary header imagery.
+*/
+const VML_PICTURE_WATERMARK_ID_PREFIX = "WordPictureWatermark";
+/**
+* Whether a VML `<v:shape>` is a watermark rather than ordinary inline
+* imagery. Text watermarks use the WordArt shapetype; picture watermarks
+* carry a `WordPictureWatermark…` id. The VML image parser uses this to
+* leave watermark shapes to this module, so a header watermark is not also
+* rendered as an inline picture.
+*/
+function isWatermarkShape(shape) {
+	if ((getAttribute(shape, null, "type") ?? "") === VML_TEXT_WATERMARK_SHAPETYPE) return true;
+	return (getAttribute(shape, null, "id") ?? "").startsWith(VML_PICTURE_WATERMARK_ID_PREFIX);
+}
+/**
+* Walk a parsed `<w:hdr>` element and return the watermark it carries,
+* or `undefined` when none is present. Scans every candidate shape /
+* anchor in the header so a non-watermark shape (e.g. a logo image)
+* earlier in document order does not shadow the real watermark.
+*
+* Returns the modeled `Watermark`, the verbatim XML of the hosting
+* paragraph (so the serializer can replay it byte-exact), and a
+* reference to that paragraph so the regular body parser can skip it.
+*/
+function parseWatermark(header) {
+	const headerXmlns = collectXmlnsDeclarations(header);
+	for (const shape of collectVmlShapesWithContent(header)) {
+		const watermark = readVmlWatermark(shape);
+		if (watermark) {
+			const hosting = findEnclosingParagraph(header, shape);
+			if (hosting) return {
+				watermark,
+				rawParagraphXml: elementToXml(cloneWithXmlnsDeclarations(hosting, headerXmlns)),
+				hostingParagraph: hosting,
+				blockIndex: blockIndexOf(header, hosting)
+			};
+		}
+	}
+	for (const anchor of collectDrawingMlBehindContentAnchors(header)) {
+		const watermark = readDrawingMlTextWatermark(anchor);
+		if (watermark) {
+			const hosting = findEnclosingParagraph(header, anchor);
+			if (hosting) return {
+				watermark,
+				rawParagraphXml: elementToXml(cloneWithXmlnsDeclarations(hosting, headerXmlns)),
+				hostingParagraph: hosting,
+				blockIndex: blockIndexOf(header, hosting)
+			};
+		}
+	}
+}
+/**
+* Index of `target` among block-level children of `header` (only
+* `w:p` and `w:tbl` count as blocks). Since the hosting paragraph
+* is filtered out of `content` after parse, this is the index the
+* serializer needs to splice the watermark XML back into so the
+* header rounds-trips with the same flow as the source.
+*/
+function blockIndexOf(header, target) {
+	let blockIdx = 0;
+	for (const child of header.elements ?? []) {
+		if (child === target) return blockIdx;
+		if (child.type !== "element") continue;
+		const local = getLocalName(child.name ?? "");
+		if (local === "p" || local === "tbl") blockIdx++;
+	}
+	return 0;
+}
+/**
+* Walk back from a watermark shape / anchor to its enclosing `<w:p>`
+* inside the header. Word always wraps a watermark in its own
+* paragraph; capturing the paragraph (not the shape) means the
+* replayed XML is a self-contained body block the header serializer
+* can splice in without further wrapping.
+*
+* If the paragraph mixes the watermark with other meaningful content
+* (text runs, additional shapes), we refuse to detach — surgically
+* extracting the watermark shape from such a paragraph is out of
+* scope here, and silently dropping the rest on `setDocumentWatermark`
+* would lose data. The caller treats the watermark as unrecoverable
+* in that case; the original paragraph stays in `content` and
+* round-trips through the regular block parser.
+*/
+function findEnclosingParagraph(header, target) {
+	for (const child of header.elements ?? []) {
+		if (child.type !== "element" || !child.name) continue;
+		if (getLocalName(child.name) !== "p") continue;
+		if (containsElement(child, target) && isWatermarkOnlyParagraph(child)) return child;
+	}
+	return null;
+}
+/**
+* A "watermark-only" paragraph carries one shape plus only
+* WordprocessingML wrappers/formatting around it. Field runs,
+* bookmarks, tabs, breaks, text, and sibling shapes are authored
+* content; those paragraphs stay in the regular header content path
+* so clearing a watermark cannot drop unrelated header data.
+*/
+function isWatermarkOnlyParagraph(paragraph) {
+	const counts = countParagraphShapeAndBodyContent(paragraph);
+	if (counts.bodyContentCount > 0) return false;
+	return counts.shapeCount <= 1;
+}
+/**
+* Count non-shape WordprocessingML content inside a paragraph while
+* ignoring pure formatting wrappers. The shape containers themselves
+* (`w:pict` / `w:drawing`) are counted as shapes, but their descendants
+* are skipped so the watermark's own text (`a:t`, etc.) is not treated
+* as body content.
+*/
+function countParagraphShapeAndBodyContent(paragraph) {
+	let shapeCount = 0;
+	let bodyContentCount = 0;
+	const walkParagraph = (root, insidePropertyContainer) => {
+		for (const child of root.elements ?? []) {
+			if (child.type !== "element") continue;
+			const local = getLocalName(child.name ?? "");
+			if (local === "pict" || local === "drawing") {
+				shapeCount++;
+				continue;
+			}
+			const childInsidePropertyContainer = insidePropertyContainer || isWordprocessingPropertyContainer(local);
+			if (!childInsidePropertyContainer && !isWatermarkParagraphWrapper(local)) bodyContentCount++;
+			walkParagraph(child, childInsidePropertyContainer);
+		}
+	};
+	walkParagraph(paragraph, false);
+	return {
+		shapeCount,
+		bodyContentCount
+	};
+}
+function isWordprocessingPropertyContainer(localName) {
+	return localName.endsWith("Pr");
+}
+function isWatermarkParagraphWrapper(localName) {
+	return localName === "r";
+}
+function containsElement(root, target) {
+	if (root === target) return true;
+	for (const child of root.elements ?? []) {
+		if (child.type !== "element") continue;
+		if (containsElement(child, target)) return true;
+	}
+	return false;
+}
+function collectVmlShapesWithContent(header) {
+	const out = [];
+	for (const pict of collectByLocalName(header, "pict")) for (const shape of findChildren(pict, "v", "shape")) if (findChild(shape, "v", "textpath") || findChild(shape, "v", "imagedata")) out.push(shape);
+	return out;
+}
+function readVmlWatermark(shape) {
+	const textpath = findChild(shape, "v", "textpath");
+	if (textpath) return readVmlTextWatermark(shape, textpath);
+	const imagedata = findChild(shape, "v", "imagedata");
+	if (imagedata) return readVmlPictureWatermark(shape, imagedata);
+	return null;
+}
+function readVmlTextWatermark(shape, textpath) {
+	const text = getAttribute(textpath, null, "string") ?? "";
+	if (text.length === 0) return null;
+	const shapeStyle = getAttribute(shape, null, "style") ?? "";
+	if ((getAttribute(shape, null, "type") ?? "") !== VML_TEXT_WATERMARK_SHAPETYPE) return null;
+	const font = parseInlineStyle(getAttribute(textpath, null, "style") ?? "", "font-family");
+	const color = readVmlFillColor(shape);
+	const rotation = parseInlineStyleNumber(shapeStyle, "rotation");
+	const opacity = readVmlFillOpacity(shape);
+	const watermark = {
+		kind: "text",
+		text
+	};
+	if (font !== void 0) watermark.font = stripQuotes(font);
+	if (color !== void 0) watermark.color = color;
+	if (opacity !== void 0) watermark.opacity = opacity;
+	if (rotation !== void 0) watermark.diagonal = rotation === 315 || rotation === -45;
+	return watermark;
+}
+function readVmlPictureWatermark(shape, imagedata) {
+	if (!(getAttribute(shape, null, "id") ?? "").startsWith(VML_PICTURE_WATERMARK_ID_PREFIX)) return null;
+	const imageRId = getAttribute(imagedata, "r", "id") ?? getAttribute(imagedata, null, "id");
+	if (!imageRId) return null;
+	const watermark = {
+		kind: "picture",
+		imageRId
+	};
+	const scale = readVmlPictureWatermarkScale(shape);
+	if (scale !== void 0) watermark.scale = scale;
+	const { widthPt, heightPt } = readVmlPictureWatermarkDimensions(shape);
+	if (widthPt !== void 0) watermark.widthPt = widthPt;
+	if (heightPt !== void 0) watermark.heightPt = heightPt;
+	if (!readVmlPictureWatermarkHasWashout(imagedata)) watermark.washout = false;
+	return watermark;
+}
+const PICTURE_WATERMARK_DEFAULT_WIDTH_PT = 415;
+const PICTURE_WATERMARK_DEFAULT_HEIGHT_PT = 207;
+const PICTURE_WATERMARK_SCALE_EPSILON = .01;
+const PICTURE_WATERMARK_WASHOUT_GAIN = "19661f";
+const PICTURE_WATERMARK_WASHOUT_BLACKLEVEL = "22938f";
+function readVmlPictureWatermarkScale(shape) {
+	const shapeStyle = getAttribute(shape, null, "style") ?? "";
+	const widthPt = parseInlineStyleLengthPt(shapeStyle, "width");
+	const heightPt = parseInlineStyleLengthPt(shapeStyle, "height");
+	if (widthPt === void 0 && heightPt === void 0) return;
+	const widthScale = widthPt !== void 0 ? widthPt / PICTURE_WATERMARK_DEFAULT_WIDTH_PT : void 0;
+	const heightScale = heightPt !== void 0 ? heightPt / PICTURE_WATERMARK_DEFAULT_HEIGHT_PT : void 0;
+	if (widthScale !== void 0 && heightScale !== void 0) {
+		if (Math.abs(widthScale - heightScale) > PICTURE_WATERMARK_SCALE_EPSILON) return;
+		return widthScale;
+	}
+	return widthScale ?? heightScale;
+}
+function readVmlPictureWatermarkDimensions(shape) {
+	const shapeStyle = getAttribute(shape, null, "style") ?? "";
+	return {
+		widthPt: parseInlineStyleLengthPt(shapeStyle, "width"),
+		heightPt: parseInlineStyleLengthPt(shapeStyle, "height")
+	};
+}
+function readVmlPictureWatermarkHasWashout(imagedata) {
+	return getAttribute(imagedata, null, "gain") === PICTURE_WATERMARK_WASHOUT_GAIN && getAttribute(imagedata, null, "blacklevel") === PICTURE_WATERMARK_WASHOUT_BLACKLEVEL;
+}
+/**
+* Read the watermark's opacity from the shape's `<v:fill>` child. Word
+* accepts two boolean encodings: the decimal form (`opacity=".5"`) and
+* the fixed-point form (`opacity="32768f"`, where 65536 = fully
+* opaque). Returns `undefined` for any malformed value so the caller
+* falls back to the renderer's silver default.
+*/
+function readVmlFillOpacity(shape) {
+	const fill = findChild(shape, "v", "fill");
+	if (!fill) return;
+	const raw = getAttribute(fill, null, "opacity");
+	if (!raw) return;
+	if (raw.endsWith("f")) {
+		const fixed = Number.parseFloat(raw.slice(0, -1));
+		if (!Number.isFinite(fixed)) return;
+		return Math.max(0, Math.min(1, fixed / 65536));
+	}
+	const decimal = Number.parseFloat(raw);
+	if (!Number.isFinite(decimal)) return;
+	return Math.max(0, Math.min(1, decimal));
+}
+function readVmlFillColor(shape) {
+	const raw = getAttribute(shape, null, "fillcolor");
+	if (!raw) return;
+	const stripped = raw.startsWith("#") ? raw.slice(1) : raw;
+	return stripped.toLowerCase() === "auto" ? "auto" : stripped.toUpperCase();
+}
+function collectDrawingMlBehindContentAnchors(header) {
+	const out = [];
+	for (const drawing of collectByLocalName(header, "drawing")) {
+		const anchor = findDeep(drawing, "wp", "anchor");
+		if (!anchor) continue;
+		const behindDoc = getAttribute(anchor, null, "behindDoc");
+		if (behindDoc === "1" || behindDoc === "true") out.push(anchor);
+	}
+	return out;
+}
+function readDrawingMlTextWatermark(anchor) {
+	const text = readDrawingMlTextBody(anchor);
+	if (!text) return;
+	const font = readDrawingMlFontFamily(anchor);
+	const watermark = {
+		kind: "text",
+		text
+	};
+	if (font !== void 0) watermark.font = font;
+	return watermark;
+}
+function readDrawingMlTextBody(anchor) {
+	const txBody = findDeep(anchor, "a", "txBody");
+	if (!txBody) return null;
+	const parts = [];
+	for (const p of findChildren(txBody, "a", "p")) for (const r of findChildren(p, "a", "r")) {
+		const t = findChild(r, "a", "t");
+		if (t) parts.push(getTextContent(t));
+	}
+	const joined = parts.join("");
+	return joined.length > 0 ? joined : null;
+}
+function readDrawingMlFontFamily(anchor) {
+	const latin = findDeep(anchor, "a", "latin");
+	if (!latin) return;
+	return getAttribute(latin, null, "typeface") ?? void 0;
+}
+function collectByLocalName(root, localName) {
+	const out = [];
+	walk(root, (el) => {
+		if (getLocalName(el.name ?? "") === localName) out.push(el);
+	});
+	return out;
+}
+function walk(root, visit) {
+	for (const child of root.elements ?? []) {
+		if (child.type !== "element") continue;
+		visit(child);
+		walk(child, visit);
+	}
+}
+function parseInlineStyle(style, key) {
+	const lowerKey = key.toLowerCase();
+	for (const part of style.split(";")) {
+		const colonIdx = part.indexOf(":");
+		if (colonIdx === -1) continue;
+		if (part.slice(0, colonIdx).trim().toLowerCase() === lowerKey) return part.slice(colonIdx + 1).trim();
+	}
+}
+function parseInlineStyleNumber(style, key) {
+	const raw = parseInlineStyle(style, key);
+	if (raw === void 0) return;
+	const num = Number.parseFloat(raw);
+	return Number.isFinite(num) ? num : void 0;
+}
+const CSS_LENGTH_RE = /^(?<amount>[+-]?(?:\d+|\d*\.\d+))(?<unit>pt|in|cm|mm|px)?$/iu;
+function parseInlineStyleLengthPt(style, key) {
+	const raw = parseInlineStyle(style, key);
+	if (raw === void 0) return;
+	const match = CSS_LENGTH_RE.exec(raw.trim());
+	const amountText = match?.groups?.["amount"];
+	if (amountText === void 0) return;
+	const amount = Number.parseFloat(amountText);
+	if (!Number.isFinite(amount) || amount <= 0) return;
+	const unit = match?.groups?.["unit"]?.toLowerCase() ?? "pt";
+	if (unit === "pt") return amount;
+	if (unit === "in") return amount * 72;
+	if (unit === "cm") return amount * 72 / 2.54;
+	if (unit === "mm") return amount * 72 / 25.4;
+	if (unit === "px") return amount * .75;
+}
+function stripQuotes(value) {
+	let primary = value;
+	const commaIdx = primary.indexOf(",");
+	if (commaIdx !== -1) primary = primary.slice(0, commaIdx).trim();
+	const matchedDouble = primary.startsWith("\"") && primary.endsWith("\"");
+	const matchedSingle = primary.startsWith("'") && primary.endsWith("'");
+	if (primary.length >= 2 && (matchedDouble || matchedSingle)) return primary.slice(1, -1);
+	return primary;
+}
+//#endregion
+export { isWatermarkShape, parseWatermark };

package/dist/docx/wrapTypes.d.ts

@@ -0,0 +1,29 @@
+//#region src/docx/wrapTypes.d.ts
+/**
+ * Wrap-type predicates shared across the layout pipeline.
+ *
+ * Mirrors eigenpal docx-editor `wrapTypes` so that the new textBoxFlow
+ * predicates (eigenpal #474) and the existing image classifiers agree on
+ * which OOXML wrap variants are floating, which paint over body text, and
+ * which wrap around it.
+ */
+/**
+ * `true` for any wrap type that takes the object out of inline flow.
+ * Includes `topAndBottom` and the wrapNone variants (`behind`/`inFront`):
+ * those are anchored at absolute coordinates even though they don't shrink
+ * line widths.
+ */
+declare function isFloatingWrapType(wrapType: string | undefined): boolean;
+/**
+ * `true` for `behind` and `inFront` — wrapNone variants that don't shrink
+ * line widths; text paints over or under the object.
+ */
+declare function isWrapNone(wrapType: string | undefined): boolean;
+/**
+ * `true` for wrap types that actually divert lines around the object
+ * (`square` / `tight` / `through`). Excludes `topAndBottom` (block flow)
+ * and the wrapNone variants.
+ */
+declare function wrapsAroundText(wrapType: string | undefined): boolean;
+//#endregion
+export { isFloatingWrapType, isWrapNone, wrapsAroundText };

package/dist/docx/wrapTypes.js

@@ -0,0 +1,48 @@
+//#region src/docx/wrapTypes.ts
+/**
+* Wrap-type predicates shared across the layout pipeline.
+*
+* Mirrors eigenpal docx-editor `wrapTypes` so that the new textBoxFlow
+* predicates (eigenpal #474) and the existing image classifiers agree on
+* which OOXML wrap variants are floating, which paint over body text, and
+* which wrap around it.
+*/
+const FLOATING_WRAP_TYPES = /* @__PURE__ */ new Set([
+	"square",
+	"tight",
+	"through",
+	"topAndBottom",
+	"behind",
+	"inFront"
+]);
+const TEXT_WRAPPING_TYPES = /* @__PURE__ */ new Set([
+	"square",
+	"tight",
+	"through"
+]);
+/**
+* `true` for any wrap type that takes the object out of inline flow.
+* Includes `topAndBottom` and the wrapNone variants (`behind`/`inFront`):
+* those are anchored at absolute coordinates even though they don't shrink
+* line widths.
+*/
+function isFloatingWrapType(wrapType) {
+	return wrapType !== void 0 && FLOATING_WRAP_TYPES.has(wrapType);
+}
+/**
+* `true` for `behind` and `inFront` — wrapNone variants that don't shrink
+* line widths; text paints over or under the object.
+*/
+function isWrapNone(wrapType) {
+	return wrapType === "behind" || wrapType === "inFront";
+}
+/**
+* `true` for wrap types that actually divert lines around the object
+* (`square` / `tight` / `through`). Excludes `topAndBottom` (block flow)
+* and the wrapNone variants.
+*/
+function wrapsAroundText(wrapType) {
+	return wrapType !== void 0 && TEXT_WRAPPING_TYPES.has(wrapType);
+}
+//#endregion
+export { isFloatingWrapType, isWrapNone, wrapsAroundText };