@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/drawingAnchor.js

@@ -0,0 +1,201 @@
+import { intAttr } from "./serializer/xmlUtils.js";
+import { findChildByNamespaceUri, getAttribute, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
+//#region src/docx/drawingAnchor.ts
+/** WordprocessingDrawing, Transitional and Strict (ECMA-376 Parts 1 and 4). */
+const WORDPROCESSING_DRAWING_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing", "http://purl.oclc.org/ooxml/drawingml/wordprocessingDrawing"]);
+/**
+* Model key → attribute, total over the boolean half of {@link DrawingAnchor}.
+*
+* A flag added to the model fails this map until the rebuild path decides what
+* an anchor that does not state it is.
+*/
+const ANCHOR_FLAGS = {
+	useSimplePosition: {
+		spelling: "simplePos",
+		whenUnstated: false
+	},
+	locked: {
+		spelling: "locked",
+		whenUnstated: false
+	},
+	layoutInCell: {
+		spelling: "layoutInCell",
+		whenUnstated: true
+	},
+	allowOverlap: {
+		spelling: "allowOverlap",
+		whenUnstated: true
+	},
+	hidden: {
+		spelling: "hidden",
+		whenUnstated: "omit"
+	}
+};
+/** Every boolean the anchor models, from the total map above. */
+const DRAWING_ANCHOR_FLAG_KEYS = Object.keys(ANCHOR_FLAGS);
+/**
+* `@relativeHeight` is required and unsigned; this is the value Word writes for
+* the first floating object it anchors, and the only one folio may invent.
+*/
+const DEFAULT_RELATIVE_HEIGHT = 251658240;
+/** The wrap insets, which `CT_Inline` and `CT_Anchor` both carry. */
+const WRAP_DISTANCE_ATTRIBUTES = {
+	distT: "distT",
+	distB: "distB",
+	distL: "distL",
+	distR: "distR"
+};
+const WRAP_DISTANCE_KEYS = Object.keys(WRAP_DISTANCE_ATTRIBUTES);
+/**
+* Read `CT_Anchor`'s own attributes and its `wp:simplePos` offsets.
+*
+* Undefined when the element states none of them: an anchor whose every
+* attribute is the spec default holds nothing the model needs to remember, and
+* recording an empty record would make a rebuild write values the source did
+* not.
+*/
+const parseDrawingAnchor = (anchorEl) => {
+	const anchor = {};
+	let stated = false;
+	for (const key of DRAWING_ANCHOR_FLAG_KEYS) {
+		const value = parseOnOffValue(getAttribute(anchorEl, null, ANCHOR_FLAGS[key].spelling));
+		if (value !== void 0) {
+			anchor[key] = value;
+			stated = true;
+		}
+	}
+	const relativeHeight = parseNumericAttribute(anchorEl, null, "relativeHeight");
+	if (relativeHeight !== void 0) {
+		anchor.relativeHeight = relativeHeight;
+		stated = true;
+	}
+	const simplePosEl = findChildByNamespaceUri(anchorEl, WORDPROCESSING_DRAWING_NAMESPACE_URIS, "simplePos");
+	const x = parseNumericAttribute(simplePosEl, null, "x");
+	const y = parseNumericAttribute(simplePosEl, null, "y");
+	if (x !== void 0 && y !== void 0) {
+		anchor.simplePosition = {
+			x,
+			y
+		};
+		stated = true;
+	}
+	return stated ? anchor : void 0;
+};
+/**
+* The insets to write on each of the two elements that can carry them.
+*
+* A drawing whose slots say where its insets were authored gets each one back
+* on that element, which is the only way the wrap child's own set survives a
+* rebuild. A drawing with no slots, or one an editor command has moved an inset
+* on, states the value in force on the drawing: that is where OOXML reads an
+* inset from when the wrap child states none, so the effective value is right
+* either way, and inventing a wrap-child inset from a moved value would not be.
+*/
+const resolveWrapDistances = (wrap) => {
+	const slots = wrap?.distanceSlots;
+	if (slots !== void 0 && WRAP_DISTANCE_KEYS.every((key) => wrap?.[key] === (slots.wrapChild?.[key] ?? slots.drawing?.[key]))) return {
+		drawing: slots.drawing ?? {},
+		wrapChild: slots.wrapChild ?? {}
+	};
+	const drawing = {};
+	for (const key of WRAP_DISTANCE_KEYS) {
+		const value = wrap?.[key];
+		if (value !== void 0) drawing[key] = value;
+	}
+	return {
+		drawing,
+		wrapChild: {}
+	};
+};
+/** `CT_EffectExtent`'s four sides, in the order the type declares them. */
+const EFFECT_EXTENT_SIDES = [
+	"left",
+	"top",
+	"right",
+	"bottom"
+];
+/**
+* Two reservations are the same document when every side matches.
+*
+* An absent side and a zero one are one value: `CT_EffectExtent` requires all
+* four and the rebuild writes zero for a side the record holds nothing for, so
+* an all-zero record and no record at all say the same thing.
+*/
+const sameEffectExtent = (left, right) => EFFECT_EXTENT_SIDES.every((side) => (left?.[side] ?? 0) === (right?.[side] ?? 0));
+/**
+* The `wp:effectExtent` to write on each of the two elements that carry one.
+*
+* {@link resolveWrapDistances}'s rule, one element over: a drawing whose slots
+* say where the reservations were authored gets each one back on that element,
+* which is the only way the wrap child's own survives a rebuild. Once the
+* drawing's reservation has been resized the two no longer describe the same
+* object, so the rebuild states the value in force on the drawing and lets
+* OOXML's own default apply to the wrap — keeping a wrap reservation computed
+* against the old size would flow text around a shape that is no longer there.
+*
+* `effective` is the reservation the model holds for the drawing itself:
+* `Image.padding`. A shape and a text box have no such field — the rebuild has
+* always written zeros — so they pass the drawing slot back and nothing can
+* have moved a value the model cannot hold.
+*/
+const resolveEffectExtents = (wrap, effective) => {
+	const slots = wrap?.effectExtentSlots;
+	if (slots === void 0 || !sameEffectExtent(effective, slots.drawing)) return {
+		drawing: effective,
+		wrapChild: void 0
+	};
+	return {
+		drawing: slots.drawing,
+		wrapChild: slots.wrapChild
+	};
+};
+/** `wp:effectExtent`, whose four sides `CT_EffectExtent` all requires. */
+const serializeEffectExtent = (extent) => `<wp:effectExtent l="${intAttr(extent?.left ?? 0)}" t="${intAttr(extent?.top ?? 0)}" r="${intAttr(extent?.right ?? 0)}" b="${intAttr(extent?.bottom ?? 0)}"/>`;
+/** The inset attributes an element states, in schema order, or nothing. */
+const serializeWrapDistances = (distances) => {
+	const attrs = WRAP_DISTANCE_KEYS.flatMap((key) => {
+		const value = distances[key];
+		return value === void 0 ? [] : [`${WRAP_DISTANCE_ATTRIBUTES[key]}="${intAttr(value)}"`];
+	});
+	return attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+};
+/**
+* Only the wrap insets `wp:inline` or `wp:anchor` itself carries. OOXML
+* defaults an omitted one to zero, so writing all four would put a value on
+* every drawing that never had one.
+*/
+const serializeWrapDistanceAttributes = (wrap) => serializeWrapDistances(resolveWrapDistances(wrap).drawing);
+/** `wp:inline` carries the wrap insets and nothing else of `CT_Anchor`'s set. */
+const serializeInlineAttributes = (wrap) => serializeWrapDistanceAttributes(wrap);
+/**
+* Every attribute `CT_Anchor` declares of its own, in schema order.
+*
+* The walk is over {@link DRAWING_ANCHOR_FLAG_KEYS} rather than a hand-written list, so
+* a flag added to the model cannot be written by the parser and forgotten here.
+*/
+const serializeAnchorAttributes = ({ anchor, wrap, behindDoc }) => {
+	const attrs = [];
+	for (const key of DRAWING_ANCHOR_FLAG_KEYS) {
+		const { spelling, whenUnstated } = ANCHOR_FLAGS[key];
+		const stated = anchor?.[key] ?? whenUnstated;
+		if (stated !== "omit") attrs.push(`${spelling}="${stated ? "1" : "0"}"`);
+		if (key === "useSimplePosition") {
+			attrs.push(`relativeHeight="${intAttr(anchor?.relativeHeight ?? DEFAULT_RELATIVE_HEIGHT)}"`);
+			attrs.push(`behindDoc="${behindDoc ? "1" : "0"}"`);
+		}
+	}
+	return `${serializeWrapDistanceAttributes(wrap)} ${attrs.join(" ")}`;
+};
+/**
+* `wp:simplePos`, which `CT_Anchor` requires whether or not `@simplePos` says to
+* use it, so an anchor that authored no offsets still writes the origin.
+*/
+const serializeSimplePos = (anchor) => {
+	const { x, y } = anchor?.simplePosition ?? {
+		x: 0,
+		y: 0
+	};
+	return `<wp:simplePos x="${intAttr(x)}" y="${intAttr(y)}"/>`;
+};
+//#endregion
+export { DRAWING_ANCHOR_FLAG_KEYS, WORDPROCESSING_DRAWING_NAMESPACE_URIS, parseDrawingAnchor, resolveEffectExtents, resolveWrapDistances, serializeAnchorAttributes, serializeEffectExtent, serializeInlineAttributes, serializeSimplePos, serializeWrapDistanceAttributes, serializeWrapDistances };

package/dist/docx/drawingUtils.d.ts

@@ -1,28 +1,7 @@
 import { document_d_exports } from "../types/document.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/drawingUtils.d.ts
-/**
- * Map normalized theme color slots back to DrawingML scheme color names.
- * DrawingML uses bg1/bg2/tx1/tx2 where the document model uses descriptive names.
- */
-declare const THEME_COLOR_TO_DRAWING_SCHEME: {
-  readonly dk1: "dk1";
-  readonly lt1: "lt1";
-  readonly dk2: "dk2";
-  readonly lt2: "lt2";
-  readonly accent1: "accent1";
-  readonly accent2: "accent2";
-  readonly accent3: "accent3";
-  readonly accent4: "accent4";
-  readonly accent5: "accent5";
-  readonly accent6: "accent6";
-  readonly hlink: "hlink";
-  readonly folHlink: "folHlink";
-  readonly background1: "bg1";
-  readonly text1: "tx1";
-  readonly background2: "bg2";
-  readonly text2: "tx2";
-};
 /**
  * Parse a color value from a DrawingML element.
  * Handles: a:srgbClr, a:schemeClr, a:sysClr, a:prstClr
@@ -36,10 +15,7 @@ declare function parseFill(spPr: XmlElement | null): document_d_exports.ShapeFil
 /**
  * Parse outline from shape properties (a:ln).
  */
-declare function parseOutline(spPr: XmlElement | null): document_d_exports.ShapeOutline | undefined;
-/**
- * Parse horizontal position from wp:positionH element.
- */
+declare function parseOutline(spPr: XmlElement | null, context?: ParseContext): document_d_exports.ShapeOutline | undefined;
 declare function parsePositionH(posH: XmlElement | null): document_d_exports.ImagePosition["horizontal"] | undefined;
 /**
  * Parse vertical position from wp:positionV element.
@@ -49,21 +25,50 @@ declare function parsePositionV(posV: XmlElement | null): document_d_exports.Ima
  * Parse position for anchored drawings (combines positionH + positionV).
  */
 declare function parseAnchorPosition(anchor: XmlElement): document_d_exports.ImagePosition;
-/** Known wrap element names */
-declare const WRAP_ELEMENT_NAMES: string[];
+/** The `EG_WrapType` child of a `wp:anchor`, resolved by namespace. */
+declare function findWrapElement(anchor: XmlElement): XmlElement | null;
+/**
+ * `wp:effectExtent`'s four sides in EMU, exactly as the element states them.
+ *
+ * `CT_EffectExtent` requires all four, so a missing one is a malformed element
+ * rather than an unstated side, and zero is its own value: an explicit all-zero
+ * reservation on a wrap child says "this wrap reserves nothing", which is not
+ * what an absent element says.
+ */
+declare const parseEffectExtent: (el: XmlElement | null) => document_d_exports.ImagePadding | undefined;
+/**
+ * The drawing's own `wp:effectExtent`, which is also what `Image.padding` holds.
+ *
+ * An all-zero reservation is what Word writes on a drawing with no effect, and
+ * a rebuild writes zeros for a drawing the record holds none for, so the two
+ * are the same document and neither the padding nor the slot keeps it. The wrap
+ * child's is read as authored instead: an absent one there inherits the
+ * drawing's, so an explicit all-zero says something an absent one does not.
+ */
+declare const parseDrawingEffectExtent: (el: XmlElement | null) => document_d_exports.ImagePadding | undefined;
+/** The wrap insets `CT_Inline` carries, read the same way for every graphic. */
+declare function parseInlineWrap(inlineEl: XmlElement): document_d_exports.ImageWrap;
+type WrapElementOptions = {
+  /** The `EG_WrapType` child of the anchor, or null when it declared none. */
+  wrapEl: XmlElement | null;
+  /** `wp:anchor/@behindDoc`, which decides which side of the text a `wrapNone` sits on. */
+  behindDoc: boolean;
+  /** The insets `wp:anchor` itself states. */
+  anchorDistances?: document_d_exports.WrapDistances;
+  /** The `wp:effectExtent` `wp:anchor` itself states. */
+  anchorEffectExtent?: document_d_exports.ImagePadding;
+};
 /**
  * Parse wrap settings from a wrap element.
  *
- * Distance attributes (distT/distB/distL/distR) can appear on both
- * the anchor element and the wrap child. Wrap child values take priority;
- * anchor-level values are used as fallbacks.
+ * Both the insets and the effect extent are declared twice over — on the
+ * drawing and on the wrap child — and each is kept in the slot that stated it.
+ * The insets differ in that the wrap child's take priority as the value in
+ * force; the two effect extents are two values (the object's own reservation
+ * and the one the text flow is computed against), so neither overrides the
+ * other.
  */
-declare function parseWrapElement(wrapEl: XmlElement | null, behindDoc: boolean, anchorDistances?: {
-  distT?: number;
-  distB?: number;
-  distL?: number;
-  distR?: number;
-}): document_d_exports.ImageWrap;
+declare function parseWrapElement({ wrapEl, behindDoc, anchorDistances, anchorEffectExtent }: WrapElementOptions): document_d_exports.ImageWrap;
 /**
  * Parse wrap from an anchor element (finds wrap child internally).
  */
@@ -81,4 +86,4 @@ declare function parseAnchorWrap(anchor: XmlElement): document_d_exports.ImageWr
  */
 declare function resolveColorValueToHex(color: document_d_exports.ColorValue | undefined): string | undefined;
 //#endregion
-export { THEME_COLOR_TO_DRAWING_SCHEME, WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };
+export { WrapElementOptions, findWrapElement, parseAnchorBehindDoc, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseDrawingEffectExtent, parseEffectExtent, parseFill, parseInlineWrap, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };