@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/io/ooxml/parse-object.ts

@@ -0,0 +1,147 @@
+/**
+ * Lane 7c Slice 7c.1 — `<w:object>` parser (OLE preserve-only).
+ *
+ * Extracts OLE embedded objects from a `<w:object>` subtree and returns
+ * a typed `OleEmbedNode`. Non-OLE `<w:object>` elements (legacy VML
+ * drawings wrapped in `<w:object>` without `<o:OLEObject>`) return
+ * `undefined` so the caller can fall through to the generic
+ * opaque-fragment path in `src/preservation/store.ts`.
+ *
+ * Preservation contract (see `docs/wiki/images-and-media.md`):
+ * - `rawXml` is the authoritative round-trip source and is re-emitted
+ *   verbatim by the serializer.
+ * - The binary embedding part (e.g. `/word/embeddings/oleObject1.bin`)
+ *   is preserved automatically via `collectPreservedPackageParts` in
+ *   `src/io/docx-session.ts` — the relationship id stored on the node
+ *   is the handle.
+ * - Placeholder chrome (badge with ProgID + filename) is Lane 6b's
+ *   responsibility post-v2.0; this module emits only data.
+ */
+
+import type { OleEmbedNode } from "../../model/canonical-document.ts";
+import type { OpcRelationship } from "./part-manifest.ts";
+import type { XmlElementNode } from "./xml-element.ts";
+import { resolveOleRelationship } from "./parse-ole-relationship.ts";
+
+/**
+ * Parse a `<w:object>` element into an `OleEmbedNode` if it contains an
+ * `<o:OLEObject>` child with a resolvable relationship. Returns
+ * `undefined` when the element is not an OLE embedding — the caller
+ * should then fall back to opaque-fragment preservation.
+ *
+ * `rawXml` must be the full verbatim source of the `<w:object>` element
+ * (the caller typically slices `sourceXml.slice(node.start, node.end)`).
+ * It is not recomputed from the parsed tree because the grab-bag
+ * reconstruction is not byte-identical and this slice preserves rawXml
+ * bytes as the authoritative round-trip source.
+ *
+ * The canonical id is derived from the relationship id + an optional
+ * occurrence counter so callers that encounter multiple `<w:object>`
+ * elements sharing a relationship id still get stable, unique node
+ * identifiers. When `occurrenceIndex` is omitted the id is simply
+ * `ole-embed-${relationshipId}`.
+ */
+export function parseObject(
+  node: XmlElementNode,
+  rawXml: string,
+  relationships: readonly OpcRelationship[],
+  occurrenceIndex?: number,
+): OleEmbedNode | undefined {
+  const oleChild = findDirectChild(node, "OLEObject");
+  if (!oleChild) return undefined;
+
+  const progId = readOleAttribute(oleChild, "ProgID");
+  const classId = readOleAttribute(oleChild, "ClassID");
+  const shapeId = readOleAttribute(oleChild, "ShapeID");
+  const relationshipIdRaw = readRelationshipIdAttribute(oleChild);
+
+  const resolved = resolveOleRelationship(relationshipIdRaw, relationships);
+  if (!resolved) {
+    // No resolvable internal relationship — treat as non-OLE. The
+    // generic opaque-fragment path preserves the subtree via rawXml;
+    // promoting to OleEmbedNode would lose the handoff semantics the
+    // post-v2.0 chrome slice depends on.
+    return undefined;
+  }
+
+  const metadata: OleEmbedNode["metadata"] = {};
+  if (resolved.originalFilename) {
+    metadata.originalFilename = resolved.originalFilename;
+  }
+  if (classId) {
+    metadata.classId = classId;
+  }
+  if (shapeId) {
+    metadata.shapeId = shapeId;
+  }
+
+  const id =
+    typeof occurrenceIndex === "number"
+      ? `ole-embed-${resolved.relationshipId}-${occurrenceIndex}`
+      : `ole-embed-${resolved.relationshipId}`;
+
+  const result: OleEmbedNode = {
+    type: "ole_embed",
+    id,
+    embedType: "oleObject",
+    relationshipId: resolved.relationshipId,
+    metadata,
+    rawXml,
+  };
+  if (progId) {
+    result.progId = progId;
+  }
+  return result;
+}
+
+function findDirectChild(
+  node: XmlElementNode,
+  localName: string,
+): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    const colon = child.name.indexOf(":");
+    const local = colon < 0 ? child.name : child.name.slice(colon + 1);
+    if (local === localName) return child;
+  }
+  return undefined;
+}
+
+/**
+ * Read a `<o:OLEObject>` attribute by local name. OLE attributes use
+ * the VML / Office-drawing namespaces which may appear bare, prefixed
+ * as `o:`, or with another prefix depending on the source document.
+ */
+function readOleAttribute(
+  node: XmlElementNode,
+  localName: string,
+): string | undefined {
+  for (const [key, value] of Object.entries(node.attributes)) {
+    const colon = key.indexOf(":");
+    const local = colon < 0 ? key : key.slice(colon + 1);
+    if (local === localName) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Read the `r:id` attribute on `<o:OLEObject>` that references the
+ * embedding relationship. The attribute lives in the Office-
+ * relationships namespace and must have an explicit prefix on
+ * `<o:OLEObject>` — a bare `id` is `ObjectID`-style bookkeeping, not a
+ * relationship reference. We accept `r:id` or any other prefix pointing
+ * at the same namespace URI, but reject bare `id` so we don't
+ * misinterpret non-relationship attributes.
+ */
+function readRelationshipIdAttribute(
+  node: XmlElementNode,
+): string | undefined {
+  for (const [key, value] of Object.entries(node.attributes)) {
+    const colon = key.indexOf(":");
+    if (colon < 0) continue; // skip bare `id` / `ObjectID` / `ShapeID`
+    if (key.slice(colon + 1) === "id") {
+      return value;
+    }
+  }
+  return undefined;
+}

package/src/io/ooxml/parse-ole-relationship.ts

@@ -0,0 +1,82 @@
+/**
+ * Lane 7c Slice 7c.1 — OLE embedded-object relationship resolver.
+ *
+ * Resolves an `r:id` referenced from an `<o:OLEObject>` element against
+ * the parent part's relationship list. The binary package part (e.g.
+ * `/word/embeddings/oleObject1.bin`) is preserved automatically by the
+ * OPC reader → `collectPreservedPackageParts` pipeline in
+ * `src/io/docx-session.ts` — this helper only reports where the binary
+ * lives so parse-object can populate metadata on the canonical
+ * `OleEmbedNode`.
+ *
+ * Non-OLE `<w:object>` elements (legacy VML-wrapped objects without
+ * `<o:OLEObject>`) must NOT use this helper; they flow through the
+ * generic opaque-fragment path.
+ */
+
+import type { OpcRelationship } from "./part-manifest.ts";
+
+/**
+ * OLE-embedding relationship target classes defined by OOXML. Used only
+ * for logging / validator wording today; the preservation contract is
+ * insensitive to the exact relationship type as long as the binary part
+ * survives.
+ */
+export const OLE_RELATIONSHIP_TYPES: ReadonlySet<string> = new Set([
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject",
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/package",
+]);
+
+export interface ResolvedOleRelationship {
+  relationshipId: string;
+  /**
+   * Relative target as declared in the relationship XML (e.g.
+   * `"embeddings/oleObject1.bin"` or `"embeddings/Microsoft_Excel_Worksheet.xlsx"`).
+   * The absolute package path is resolved downstream by
+   * `resolveRelationshipTarget` against the source part's folder.
+   */
+  target: string;
+  relationshipType: string;
+  /**
+   * Extracted filename from the target path (without folder prefix). Used
+   * as a human-facing label in preserve-only diagnostics. Undefined when
+   * the target is unparseable.
+   */
+  originalFilename?: string;
+}
+
+/**
+ * Look up the relationship record for an r:id referenced by an
+ * `<o:OLEObject>` element. Returns undefined when the id is absent or
+ * the referenced record does not look like an OLE embedding — callers
+ * treat that as "fall through to generic opaque-fragment preservation".
+ *
+ * This helper is intentionally read-only: it does not mutate
+ * relationship records or allocate preservation store entries. Binary
+ * preservation is a separate pipeline stage.
+ */
+export function resolveOleRelationship(
+  relationshipId: string | undefined,
+  relationships: readonly OpcRelationship[],
+): ResolvedOleRelationship | undefined {
+  if (!relationshipId) return undefined;
+  const record = relationships.find((rel) => rel.id === relationshipId);
+  if (!record) return undefined;
+  if (record.targetMode !== "internal") return undefined;
+
+  return {
+    relationshipId: record.id,
+    target: record.target,
+    relationshipType: record.type,
+    originalFilename: extractFilename(record.target),
+  };
+}
+
+function extractFilename(target: string): string | undefined {
+  if (!target) return undefined;
+  const slashIdx = target.lastIndexOf("/");
+  const backslashIdx = target.lastIndexOf("\\");
+  const idx = Math.max(slashIdx, backslashIdx);
+  const name = idx >= 0 ? target.slice(idx + 1) : target;
+  return name.length > 0 ? name : undefined;
+}

package/src/io/ooxml/parse-paragraph-formatting.ts

@@ -23,6 +23,9 @@ import {
   type PropertyGrabBagDescriptor,
 } from "./property-grab-bag.ts";
 
+const TAB_ALIGN_VOCAB = new Set<TabStop["align"]>(["left", "center", "right", "decimal", "num", "bar", "clear"]);
+const TAB_LEADER_VOCAB = new Set<TabStop["leader"]>(["none", "dot", "hyphen", "underscore", "heavy", "middleDot"]);
+
 /**
  * Modelled direct children of `<w:pPr>` that `readParagraphProperties` below
  * dispatches into typed fields on `CanonicalParagraphFormatting`. Anything
@@ -92,16 +95,10 @@ function readTabStops(node: XmlElementNode): TabStop[] | undefined {
     if (!Number.isFinite(pos)) continue;
     const val = (c.attributes["w:val"] ?? c.attributes.val ?? "left").toLowerCase();
     const leader = (c.attributes["w:leader"] ?? c.attributes.leader ?? "none").toLowerCase();
-    const align: TabStop["align"] =
-      val === "center" || val === "right" || val === "decimal" || val === "bar" || val === "num" || val === "clear"
-        ? (val as TabStop["align"])
-        : "left";
-    const mappedLeader: TabStop["leader"] | undefined =
-      leader === "dot" || leader === "hyphen" || leader === "underscore" || leader === "heavy"
-        ? (leader as TabStop["leader"])
-        : leader === "middledot"
-          ? "middleDot"
-          : undefined;
+    const alignCandidate = val as TabStop["align"];
+    const align: TabStop["align"] = TAB_ALIGN_VOCAB.has(alignCandidate) ? alignCandidate : "left";
+    const leaderNorm = leader === "middledot" ? "middleDot" : (leader as TabStop["leader"]);
+    const mappedLeader: TabStop["leader"] | undefined = TAB_LEADER_VOCAB.has(leaderNorm) ? leaderNorm : undefined;
     tabs.push({
       position: pos,
       align,

package/src/io/ooxml/parse-picture-sdt.ts

@@ -0,0 +1,85 @@
+/**
+ * parse-picture-sdt.ts — CO4.5
+ *
+ * Public adapter for parsing a `<w:sdt>` element that wraps picture or shape
+ * drawing content. Thin wrapper over `parseSdtXml` from parse-main-document.ts,
+ * which threads drawing-frame opts (relationships, mediaParts) through the full
+ * block-parse chain so `<w:drawing>` inside SDT content becomes a
+ * `DrawingFrameNode` inside the paragraph's inline children.
+ *
+ * The typical OOXML structure is:
+ *   <w:sdt> → <w:sdtContent> → <w:p> → <w:r> → <w:drawing>
+ * The SDT's canonical child is a ParagraphNode; the drawing lives inside the
+ * paragraph's inline content as a DrawingFrameNode.
+ */
+
+import type { OpcRelationship } from "./part-manifest.ts";
+import type { InlineMediaPart } from "./parse-inline-media.ts";
+import type { ChartPartLookup } from "./parse-complex-content.ts";
+import { type XmlElementNode, localName } from "./_mini-xml.ts";
+import { parseSdtXml } from "./parse-main-document.ts";
+import type { ParsedBlockNode } from "./parse-main-document.ts";
+
+export type { ParsedBlockNode };
+
+/**
+ * Parse a raw `<w:sdt>` XML string with full drawing support.
+ *
+ * Returns the canonical block node — typically a `ParsedSdtNode` whose
+ * children are `ParsedParagraphNode` items carrying `DrawingFrameNode`
+ * inline content. Falls back to `opaque_block` if the fragment cannot be
+ * parsed (malformed XML, no `<w:sdt>` root, etc.).
+ */
+export function parsePictureSdt(
+  rawXml: string,
+  relationships: readonly OpcRelationship[] = [],
+  mediaParts: ReadonlyMap<string, InlineMediaPart> = new Map(),
+  sourcePartPath?: string,
+  chartPartLookup?: ChartPartLookup,
+): ParsedBlockNode {
+  return parseSdtXml(
+    rawXml,
+    relationships,
+    mediaParts,
+    sourcePartPath ?? "/word/document.xml",
+    chartPartLookup,
+  );
+}
+
+/**
+ * Cheap predicate: returns true when any paragraph inside `<w:sdtContent>`
+ * contains a `<w:drawing>` or `<w:pict>` child (directly or inside a run).
+ *
+ * Accepts either the `<w:sdt>` element directly or the `__root__` wrapper
+ * returned by `parseXml()`.
+ */
+export function sdtContentHasDrawing(node: XmlElementNode): boolean {
+  const sdt =
+    node.name === "__root__"
+      ? node.children.find((c): c is XmlElementNode => c.type === "element")
+      : node;
+  if (!sdt) return false;
+
+  const contentNode = sdt.children.find(
+    (c): c is XmlElementNode =>
+      c.type === "element" && localName(c.name) === "sdtContent",
+  );
+  if (!contentNode) return false;
+  for (const child of contentNode.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "p") continue;
+    for (const pChild of (child as XmlElementNode).children) {
+      if (pChild.type !== "element") continue;
+      const pChildName = localName((pChild as XmlElementNode).name);
+      if (pChildName === "drawing" || pChildName === "pict") return true;
+      if (pChildName === "r") {
+        for (const rChild of (pChild as XmlElementNode).children) {
+          if (rChild.type !== "element") continue;
+          const rChildName = localName((rChild as XmlElementNode).name);
+          if (rChildName === "drawing" || rChildName === "pict") return true;
+        }
+      }
+    }
+  }
+  return false;
+}

package/src/io/ooxml/parse-picture.ts

@@ -1,18 +1,30 @@
 import type { PictureContent } from "../../model/canonical-document.ts";
-
-interface XmlElementNode {
-  type: "element";
-  name: string;
-  attributes: Record<string, string>;
-  children: XmlNode[];
-}
-
-interface XmlTextNode {
-  type: "text";
-  text: string;
-}
-
-type XmlNode = XmlElementNode | XmlTextNode;
+import {
+  type XmlElementNode,
+  findFirstChild,
+  findFirstDescendant,
+} from "./_mini-xml.ts";
+
+const SAFE_HEX_COLOR_RE = /^(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
+const SAFE_SCHEME_COLOR_SLOTS = new Set([
+  "dk1",
+  "lt1",
+  "dk2",
+  "lt2",
+  "accent1",
+  "accent2",
+  "accent3",
+  "accent4",
+  "accent5",
+  "accent6",
+  "hlink",
+  "folhlink",
+  "tx1",
+  "tx2",
+  "bg1",
+  "bg2",
+  "phclr",
+]);
 
 /**
  * Parse a pic:pic element (child of a:graphicData) into PictureContent.
@@ -25,13 +37,18 @@ export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | nu
   const pic = findFirstDescendant(graphicDataEl, "pic");
   if (!pic) return null;
 
-  // blipFill/blip r:embed
+  // blipFill/blip — Phase 4.4 G4: accept r:embed (embedded, primary) OR r:link
+  // (externally-linked image). Previously only r:embed was honored, silently
+  // dropping valid linked images.
   const blipFill = findFirstChild(pic, "blipFill");
   if (!blipFill) return null;
   const blip = findFirstChild(blipFill, "blip");
   if (!blip) return null;
-  const blipRef = blip.attributes["r:embed"] ?? blip.attributes.embed ?? "";
+  const blipEmbed = blip.attributes["r:embed"] ?? blip.attributes.embed;
+  const blipLink = blip.attributes["r:link"] ?? blip.attributes.link;
+  const blipRef = blipEmbed ?? blipLink ?? "";
   if (!blipRef) return null;
+  const isLinked = !blipEmbed && !!blipLink;
 
   // srcRect (percentage crop: 0..100000 = 0..100%)
   const srcRectEl = findFirstChild(blipFill, "srcRect");
@@ -44,10 +61,15 @@ export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | nu
       }
     : undefined;
 
-  // stretch
+  // stretch vs tile — mutually exclusive per OOXML spec. Prefer stretch
+  // when both appear (matches Word's observed serializer behavior).
   const stretchEl = findFirstChild(blipFill, "stretch");
   const stretch = stretchEl ? true : undefined;
 
+  // Phase 4.5 G7 — a:tile (blipFill tile repeat)
+  const tileEl = findFirstChild(blipFill, "tile");
+  const tile = tileEl ? readTileAttrs(tileEl) : undefined;
+
   // spPr/xfrm — rotation and flip
   const spPr = findFirstChild(pic, "spPr");
   const xfrm = spPr ? findFirstChild(spPr, "xfrm") : undefined;
@@ -60,48 +82,107 @@ export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | nu
   const prstGeom = spPr ? findFirstChild(spPr, "prstGeom") : undefined;
   const presetGeom = prstGeom?.attributes.prst;
 
+  // N11.b — effectLst: softEdge, outerShdw, glow
+  const effectLst = spPr ? findFirstChild(spPr, "effectLst") : undefined;
+  const softEdgeEl = effectLst ? findFirstChild(effectLst, "softEdge") : undefined;
+  const softEdgeRadius = softEdgeEl ? readEmuAttr(softEdgeEl, "rad") : undefined;
+  const outerShdwEl = effectLst ? findFirstChild(effectLst, "outerShdw") : undefined;
+  const outerShadow = outerShdwEl
+    ? parseOuterShadow(outerShdwEl)
+    : undefined;
+  const glowEl = effectLst ? findFirstChild(effectLst, "glow") : undefined;
+  const glow = glowEl ? parseGlow(glowEl) : undefined;
+
   const result: PictureContent = { type: "picture", blipRef };
+  if (isLinked) result.isLinked = true;
   if (srcRect) result.srcRect = srcRect;
   if (stretch !== undefined) result.stretch = stretch;
+  if (tile !== undefined) result.tile = tile;
   if (rotation !== undefined) result.rotation = rotation;
   if (flipH !== undefined) result.flipH = flipH;
   if (flipV !== undefined) result.flipV = flipV;
   if (presetGeom) result.presetGeom = presetGeom;
+  if (softEdgeRadius !== undefined) result.softEdgeRadius = softEdgeRadius;
+  if (outerShadow) result.outerShadow = outerShadow;
+  if (glow) result.glow = glow;
   return result;
 }
 
-function readPercentAttr(el: XmlElementNode, name: string): number {
-  const v = el.attributes[name];
-  if (v === undefined) return 0;
-  return parseInt(v, 10) || 0;
-}
-
-function readBoolAttr(el: XmlElementNode, name: string): boolean | undefined {
+function readEmuAttr(el: XmlElementNode, name: string): number | undefined {
   const v = el.attributes[name];
   if (v === undefined) return undefined;
-  return v !== "0" && v !== "false";
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : undefined;
 }
 
-function findFirstChild(node: XmlElementNode, local: string): XmlElementNode | undefined {
-  for (const child of node.children) {
-    if (child.type === "element" && localName(child.name) === local) return child;
+function parseColorFromEl(el: XmlElementNode): { color: string; colorType: "srgbClr" | "schemeClr" } | null {
+  const srgb = findFirstChild(el, "srgbClr");
+  if (srgb) {
+    const color = (srgb.attributes.val ?? "000000").trim();
+    if (!SAFE_HEX_COLOR_RE.test(color)) return null;
+    return { color: color.toUpperCase(), colorType: "srgbClr" };
+  }
+  const scheme = findFirstChild(el, "schemeClr");
+  if (scheme) {
+    const slot = (scheme.attributes.val ?? "dk1").trim().toLowerCase();
+    if (!SAFE_SCHEME_COLOR_SLOTS.has(slot)) return null;
+    return { color: slot, colorType: "schemeClr" };
   }
-  return undefined;
+  return null;
+}
+
+function parseOuterShadow(
+  el: XmlElementNode,
+): PictureContent["outerShadow"] {
+  const blurRad = readEmuAttr(el, "blurRad") ?? 0;
+  const dist = readEmuAttr(el, "dist") ?? 0;
+  const dir = parseInt(el.attributes.dir ?? "0", 10) || 0;
+  const colorInfo = parseColorFromEl(el);
+  if (!colorInfo) return undefined;
+  return { blurRad, dist, dir, color: colorInfo.color, colorType: colorInfo.colorType };
 }
 
-function findFirstDescendant(node: XmlElementNode, local: string): XmlElementNode | undefined {
-  for (const child of node.children) {
-    if (child.type !== "element") continue;
-    if (localName(child.name) === local) return child;
-    const found = findFirstDescendant(child, local);
-    if (found) return found;
+function parseGlow(el: XmlElementNode): PictureContent["glow"] {
+  const radius = readEmuAttr(el, "rad") ?? 0;
+  const colorInfo = parseColorFromEl(el);
+  if (!colorInfo) return undefined;
+  return { radius, color: colorInfo.color, colorType: colorInfo.colorType };
+}
+
+function readTileAttrs(
+  tileEl: XmlElementNode,
+): NonNullable<PictureContent["tile"]> | undefined {
+  const result: NonNullable<PictureContent["tile"]> = {};
+  const intAttrs = ["tx", "ty", "sx", "sy"] as const;
+  for (const key of intAttrs) {
+    const v = tileEl.attributes[key];
+    if (v !== undefined) {
+      const n = parseInt(v, 10);
+      if (Number.isFinite(n)) result[key] = n;
+    }
   }
-  return undefined;
+  const flip = tileEl.attributes.flip;
+  if (flip === "x" || flip === "y" || flip === "xy") result.flip = flip;
+  const algn = tileEl.attributes.algn;
+  if (algn) result.algn = algn;
+  return Object.keys(result).length > 0 ? result : {};
 }
 
-function localName(name: string): string {
-  const i = name.indexOf(":");
-  return i >= 0 ? name.slice(i + 1) : name;
+function readPercentAttr(el: XmlElementNode, name: string): number {
+  const v = el.attributes[name];
+  if (v === undefined) return 0;
+  return parseInt(v, 10) || 0;
+}
+
+function readBoolAttr(el: XmlElementNode, name: string): boolean | undefined {
+  // Phase 1.3 B5 — check unprefixed, wp:-prefixed, and a:-prefixed variants.
+  // Serialized OOXML occasionally keeps DrawingML attrs in the a: namespace
+  // (e.g. `<a:xfrm a:flipH="1"/>`) even though xfrm itself is in the a: NS.
+  // parse-anchor.ts::readBoolAttr uses the same pattern; staying consistent.
+  const v = el.attributes[name] ?? el.attributes[`wp:${name}`] ?? el.attributes[`a:${name}`];
+  if (v === undefined) return undefined;
+  return v !== "0" && v !== "false";
 }
 
+/** @deprecated Phase 6.2 — re-export from _mini-xml.ts; call sites should migrate to XmlElementNode directly. */
 export { type XmlElementNode as PictureXmlElement };