@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/io/ooxml/xml-parser.ts

@@ -16,6 +16,7 @@
  * and any future OOXML import path can share the same implementation.
  */
 import type { XmlElementNode } from "./xml-element.ts";
+import { localName } from "./xml-attr-helpers.ts";
 
 const ROOT_TAG = "__root__";
 
@@ -112,6 +113,188 @@ export function parseXml(xml: string): XmlElementNode {
   return root;
 }
 
+/**
+ * Like `parseXml` but records byte-offset positions (`start`, `end`) on every
+ * produced element and text node. Required by parsers that need to re-slice the
+ * source string to extract raw XML fragments (e.g. `rawXml` preservation,
+ * `sourceXml.slice(node.start, node.end)` patterns).
+ *
+ * The canonical `parseXml` above is lighter and preferred when position
+ * information is not needed.
+ */
+export function parseXmlWithOffsets(xml: string): XmlElementNode {
+  const root: XmlElementNode = {
+    type: "element",
+    name: "__root__",
+    attributes: {},
+    children: [],
+    start: 0,
+    end: xml.length,
+  };
+  const stack: XmlElementNode[] = [root];
+  let cursor = 0;
+
+  while (cursor < xml.length) {
+    if (xml.startsWith("<!--", cursor)) {
+      const end = xml.indexOf("-->", cursor);
+      cursor = end >= 0 ? end + 3 : xml.length;
+      continue;
+    }
+
+    if (xml.startsWith("<?", cursor)) {
+      const end = xml.indexOf("?>", cursor);
+      cursor = end >= 0 ? end + 2 : xml.length;
+      continue;
+    }
+
+    if (xml.startsWith("<![CDATA[", cursor)) {
+      const end = xml.indexOf("]]>", cursor);
+      const textEnd = end >= 0 ? end : xml.length;
+      stack[stack.length - 1]?.children.push({
+        type: "text",
+        text: xml.slice(cursor + 9, textEnd),
+        start: cursor,
+        end: end >= 0 ? end + 3 : xml.length,
+      });
+      cursor = end >= 0 ? end + 3 : xml.length;
+      continue;
+    }
+
+    if (xml[cursor] !== "<") {
+      const nextTag = xml.indexOf("<", cursor);
+      const end = nextTag >= 0 ? nextTag : xml.length;
+      const text = decodeXmlEntities(xml.slice(cursor, end));
+      if (text.length > 0) {
+        stack[stack.length - 1]?.children.push({ type: "text", text, start: cursor, end });
+      }
+      cursor = end;
+      continue;
+    }
+
+    if (xml[cursor + 1] === "/") {
+      const end = xml.indexOf(">", cursor);
+      if (end < 0) {
+        throw new Error("Malformed XML: missing closing >.");
+      }
+      const name = xml.slice(cursor + 2, end).trim();
+      const current = stack.pop();
+      if (!current || localName(current.name) !== localName(name)) {
+        throw new Error(`Malformed XML: unexpected closing tag </${name}>.`);
+      }
+      current.end = end + 1;
+      cursor = end + 1;
+      continue;
+    }
+
+    const tagEnd = findTagEndWithOffsets(xml, cursor);
+    const tagBody = xml.slice(cursor + 1, tagEnd);
+    const selfClosing = /\/\s*$/.test(tagBody);
+    const { name, attributes: tagAttributes } = parseTagWithOffsets(
+      tagBody.replace(/\/\s*$/, "").trim(),
+    );
+    const element: XmlElementNode = {
+      type: "element",
+      name,
+      attributes: tagAttributes,
+      children: [],
+      start: cursor,
+      end: tagEnd + 1,
+    };
+    stack[stack.length - 1]?.children.push(element);
+
+    if (!selfClosing) {
+      stack.push(element);
+    }
+
+    cursor = tagEnd + 1;
+  }
+
+  if (stack.length !== 1) {
+    throw new Error("Malformed XML: unclosed element.");
+  }
+
+  return root;
+}
+
+
+function parseTagWithOffsets(
+  tagBody: string,
+): { name: string; attributes: Record<string, string> } {
+  let cursor = 0;
+  while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
+    cursor += 1;
+  }
+  const nameStart = cursor;
+  while (cursor < tagBody.length && !/\s/.test(tagBody[cursor] ?? "")) {
+    cursor += 1;
+  }
+  const name = tagBody.slice(nameStart, cursor);
+  const attributes: Record<string, string> = {};
+
+  while (cursor < tagBody.length) {
+    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
+      cursor += 1;
+    }
+    if (cursor >= tagBody.length) break;
+    const keyStart = cursor;
+    while (cursor < tagBody.length && !/[\s=]/.test(tagBody[cursor] ?? "")) {
+      cursor += 1;
+    }
+    const key = tagBody.slice(keyStart, cursor);
+    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
+      cursor += 1;
+    }
+    if (tagBody[cursor] !== "=") {
+      attributes[key] = "";
+      continue;
+    }
+    cursor += 1;
+    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
+      cursor += 1;
+    }
+    const quote = tagBody[cursor];
+    if (quote !== `"` && quote !== `'`) {
+      throw new Error(`Malformed XML attribute ${key}.`);
+    }
+    cursor += 1;
+    const valueStart = cursor;
+    while (cursor < tagBody.length && tagBody[cursor] !== quote) {
+      cursor += 1;
+    }
+    attributes[key] = decodeXmlEntities(tagBody.slice(valueStart, cursor));
+    cursor += 1;
+  }
+
+  return { name, attributes };
+}
+
+function findTagEndWithOffsets(xml: string, start: number): number {
+  let cursor = start + 1;
+  let quote: string | null = null;
+
+  while (cursor < xml.length) {
+    const current = xml[cursor];
+    if (quote) {
+      if (current === quote) {
+        quote = null;
+      }
+      cursor += 1;
+      continue;
+    }
+    if (current === `"` || current === `'`) {
+      quote = current;
+      cursor += 1;
+      continue;
+    }
+    if (current === ">") {
+      return cursor;
+    }
+    cursor += 1;
+  }
+
+  throw new Error("Malformed XML: missing >.");
+}
+
 /** Decode the standard XML entity references plus numeric character references. */
 export function decodeXmlEntities(text: string): string {
   return text

package/src/legal/bookmarks.ts

@@ -7,7 +7,7 @@ import type {
   FieldRegistry,
   FieldRegistryEntry,
 } from "../model/canonical-document.ts";
-import { resolveWalkableRoot } from "./_document-root.ts";
+import { resolveWalkableRoot } from "./document-root.ts";
 
 export interface LegalBookmark {
   bookmarkId: string;

package/src/legal/cross-references.ts

@@ -12,7 +12,7 @@ import type {
   ParagraphNode,
   TocEntry,
 } from "../model/canonical-document.ts";
-import { resolveWalkableRoot } from "./_document-root.ts";
+import { resolveWalkableRoot } from "./document-root.ts";
 
 export interface CrossReferencePattern {
   kind: "section" | "clause" | "article" | "schedule" | "exhibit" | "appendix";

package/src/legal/defined-terms.ts

@@ -4,7 +4,7 @@ import type {
   DocumentNode,
   ParagraphNode,
 } from "../model/canonical-document.ts";
-import { resolveWalkableRoot } from "./_document-root.ts";
+import { resolveWalkableRoot } from "./document-root.ts";
 
 export interface DefinedTermOccurrence {
   paragraphIndex: number;

package/src/legal/{_document-root.ts → document-root.ts}

@@ -4,6 +4,14 @@ import type {
   DocumentRootNode,
 } from "../model/canonical-document.ts";
 
+// Compile-time guard: CanonicalDocument must never gain a `type` field,
+// because resolveWalkableRoot uses `!("type" in document)` to distinguish
+// a CanonicalDocument envelope from a DocumentNode union member.
+type _CanonicalDocumentHasNoTypeField = "type" extends keyof CanonicalDocument
+  ? never
+  : true;
+const _: _CanonicalDocumentHasNoTypeField = true;
+
 /**
  * Accept either a full `CanonicalDocument` (or a Pick of it carrying `content`)
  * or a raw `DocumentNode`, and return the node to walk.

package/src/legal/signature-blocks.ts

@@ -4,7 +4,7 @@ import type {
   DocumentNode,
   ParagraphNode,
 } from "../model/canonical-document.ts";
-import { resolveWalkableRoot } from "./_document-root.ts";
+import { resolveWalkableRoot } from "./document-root.ts";
 
 export interface SignatureBlockCandidate {
   startIndex: number;

package/src/model/canonical-document.ts

@@ -16,10 +16,10 @@ import type {
   ScopeMarkerStartNode,
   ScopeMarkerEndNode,
 } from "./scope-markers.ts";
-import type { ChartModel } from "../io/ooxml/chart/types.ts";
+import type { ChartModel } from "./chart-types.ts";
 
 export type { ScopeMarkerStartNode, ScopeMarkerEndNode } from "./scope-markers.ts";
-export type { ChartModel } from "../io/ooxml/chart/types.ts";
+export type { ChartModel } from "./chart-types.ts";
 
 const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
   "schemaVersion",
@@ -284,6 +284,7 @@ export interface NumberingLevelOverrideDefinition {
   paragraphGeometry?: NumberingLevelParagraphGeometry;
   runProperties?: CanonicalRunFormatting;
   restartAfterLevel?: number;
+  picBulletId?: string;
 }
 
 export interface NumberingInstance {
@@ -555,7 +556,8 @@ export type DocumentNode =
   | ShapeNode
   | WordArtNode
   | VmlShapeNode
-  | DrawingFrameNode;
+  | DrawingFrameNode
+  | OleEmbedNode;
 
 export interface DocumentRootNode {
   type: "doc";
@@ -833,6 +835,19 @@ export interface CellShading {
   fill?: string;
   color?: string;
   val?: string;
+  /**
+   * SOW gap G3 — theme-shading references (§17.3.5). When `themeFill` is set
+   * and `fill` is absent or "auto", the runtime resolves the shading via
+   * `ThemeColorResolver.resolveWordThemeColor(themeFill, themeFillTint,
+   * themeFillShade)`. Fields are kept verbatim so export can round-trip the
+   * original `w:shd` element without re-encoding the resolved hex.
+   */
+  themeFill?: string;
+  themeFillTint?: string;
+  themeFillShade?: string;
+  themeColor?: string;
+  themeColorTint?: string;
+  themeColorShade?: string;
 }
 
 export interface TableCellMargins {
@@ -1062,6 +1077,41 @@ export interface FieldNode {
     includeNumbering?: boolean;
     includeLevel?: boolean;
   };
+  /** Legacy form-field metadata from w:ffData (textInput, checkBox, ddList). Round-trip only; no UI for MVP. */
+  legacyFormField?: LegacyFormFieldNode;
+}
+
+export type LegacyFormFieldKind = "textInput" | "checkBox" | "ddList";
+
+export interface LegacyFormFieldNode {
+  kind: LegacyFormFieldKind;
+  name?: string;
+  enabled?: boolean;
+  calcOnExit?: boolean;
+  textInput?: {
+    default?: string;
+    maxLength?: number;
+    format?: string;
+  };
+  checkBox?: {
+    size?: number;
+    default?: boolean;
+    checked?: boolean;
+  };
+  ddList?: {
+    default?: number;
+    listEntry?: string[];
+  };
+  /** Verbatim <w:ffData>…</w:ffData> XML for lossless round-trip. */
+  rawXml: string;
+  /**
+   * Phase V.a: set to `true` when typed fields have been mutated via
+   * `setLegacyFormFieldValue` since parse. On serialize, the `rawXml` is
+   * regenerated from the typed fields via `regenerateFFDataRawXml`.
+   * Un-mutated nodes emit the preserved `rawXml` verbatim for lossless
+   * round-trip.
+   */
+  mutated?: boolean;
 }
 
 // ─── Field registry ─────────────────────────────────────────────────────────
@@ -1198,7 +1248,10 @@ export interface SectionProperties {
  */
 export interface FootnoteProperties {
   pos?: "pageBottom" | "beneathText" | "sectEnd" | "docEnd";
-  numFmt?: "decimal" | "upperRoman" | "lowerRoman" | "upperLetter" | "lowerLetter" | "chicago" | "none";
+  numFmt?: "decimal" | "upperRoman" | "lowerRoman" | "upperLetter" | "lowerLetter"
+    | "ordinal" | "cardinalText" | "ordinalText" | "hex" | "chicago" | "bullet"
+    | "ideographDigital" | "japaneseCounting" | "arabicAbjad" | "arabicAlpha"
+    | "none";
   numStart?: number;
   numRestart?: "continuous" | "eachSect" | "eachPage";
 }
@@ -1289,7 +1342,8 @@ export type InlineNode =
   | ShapeNode
   | WordArtNode
   | VmlShapeNode
-  | DrawingFrameNode;
+  | DrawingFrameNode
+  | OleEmbedNode;
 
 export interface TextNode {
   type: "text";
@@ -1450,10 +1504,50 @@ export interface VmlShapeNode {
   rawXml: string;
 }
 
+/**
+ * Preserve-only OLE embedded object (Lane 7c Slice 7c.1).
+ *
+ * Captures `<w:object>` subtrees whose child is `<o:OLEObject>` — Excel
+ * ranges, PowerPoint slides, and other OLE-packaged payloads embedded in
+ * the document via an OPC relationship. The original object XML is
+ * retained in `rawXml` and re-emitted verbatim on export; the binary
+ * package part is preserved through the opaque-fragment / package-part
+ * store reached via `relationshipId`.
+ *
+ * Native render is out of scope: this node models the preservation
+ * contract only. Placeholder badge chrome (Lane 6b post-v2.0) will hang
+ * off `{progId, relationshipId}` when the chrome slice activates.
+ *
+ * Non-OLE `<w:object>` elements (legacy VML-wrapped objects without
+ * `<o:OLEObject>`) continue to flow through the generic opaque-fragment
+ * path and do NOT materialize as `OleEmbedNode` — parsers must fall
+ * through when `<o:OLEObject>` is absent.
+ */
+export interface OleEmbedNode {
+  type: "ole_embed";
+  id: string;
+  progId?: string;
+  embedType: "oleObject";
+  relationshipId: string;
+  metadata: {
+    originalFilename?: string;
+    classId?: string;
+    shapeId?: string;
+  };
+  rawXml: string;
+}
+
 export interface AnchorGeometry {
   display: "inline" | "floating";
   extent: { widthEmu: number; heightEmu: number };
   wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
+  /**
+   * Polygon coords (in OOXML's 21600ths-of-image units) when wrapMode is
+   * "tight" or "through" and `wp:wrapPolygon` is present. First point from
+   * `wp:start`; subsequent points from sequential `wp:lineTo`. Consumed by
+   * Lane 6 P7 float-wrap for proper polygon text flow.
+   */
+  wrapPolygon?: Array<{ x: number; y: number }>;
   positionH?: { relativeFrom: string; align?: string; offset?: number };
   positionV?: { relativeFrom: string; align?: string; offset?: number };
   distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
@@ -1462,22 +1556,66 @@ export interface AnchorGeometry {
   layoutInCell?: boolean;
   allowOverlap?: boolean;
   simplePos?: boolean;
-  docPr?: { id: string; name?: string; descr?: string };
+  docPr?: {
+    id: string;
+    name?: string;
+    descr?: string;
+    /** `wp:docPr hidden="1"` — Word UI hides the frame from the user. */
+    hidden?: boolean;
+  };
+  /**
+   * `wp:cNvGraphicFramePr/a:graphicFrameLocks` — object-manipulation locks
+   * consumed by Lane 6 object chrome (disable resize handles / move, etc.).
+   */
+  frameLocks?: {
+    noChangeAspect?: boolean;
+    noResize?: boolean;
+    noMove?: boolean;
+    noRot?: boolean;
+    noSelect?: boolean;
+    noGrp?: boolean;
+  };
 }
 
 export interface PictureContent {
   type: "picture";
   blipRef: string;
+  /**
+   * Phase 4.4 G4 — true when the image references an external URL via
+   * `a:blip r:link` (bytes not in the .docx package) rather than embedded
+   * via `r:embed`. External-linked images can't resolve to mediaId;
+   * `state: "missing"` in surface projection.
+   */
+  isLinked?: boolean;
   /** Resolved media catalog ID (e.g. "media:word/media/image1.png"), populated by parse-drawing. */
   mediaId?: string;
   /** Absolute package path for media catalog lookup. */
   packagePartName?: string;
   srcRect?: { top: number; bottom: number; left: number; right: number };
   stretch?: boolean;
+  /**
+   * Phase 4.5 G7 — `pic:blipFill/a:tile` (tiled image repeat). Mutually
+   * exclusive with `stretch`. tx/ty = offset (EMUs), sx/sy = scale ×1000,
+   * flip = "x"|"y"|"xy", algn = alignment token.
+   */
+  tile?: {
+    tx?: number;
+    ty?: number;
+    sx?: number;
+    sy?: number;
+    flip?: "x" | "y" | "xy";
+    algn?: string;
+  };
   rotation?: number;
   flipH?: boolean;
   flipV?: boolean;
   presetGeom?: string;
+  /** N11.b — DrawingML a:softEdge feather radius in EMU. */
+  softEdgeRadius?: number;
+  /** N11.b — DrawingML a:outerShdw attributes. `dir` is in 60000ths of a degree; `blurRad`/`dist` in EMU. */
+  outerShadow?: { blurRad: number; dist: number; dir: number; color: string; colorType: "srgbClr" | "schemeClr" };
+  /** N11.b — DrawingML a:glow radius in EMU + color. */
+  glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
   /** Original w:drawing XML slice, preserved for lossless round-trip serialization. */
   rawXml?: string;
 }
@@ -2264,6 +2402,27 @@ function validateDocumentNode(
       }
       return;
     }
+    case "ole_embed":
+      expectString(record.id, `${path}.id`, issues);
+      expectString(record.relationshipId, `${path}.relationshipId`, issues);
+      expectString(record.rawXml, `${path}.rawXml`, issues);
+      if (record.embedType !== "oleObject") {
+        issues.push({
+          path: `${path}.embedType`,
+          message: "embedType must be 'oleObject'.",
+        });
+      }
+      if (record.progId !== undefined) {
+        expectString(record.progId, `${path}.progId`, issues);
+      }
+      if (record.metadata === undefined || record.metadata === null ||
+          typeof record.metadata !== "object") {
+        issues.push({
+          path: `${path}.metadata`,
+          message: "metadata must be an object.",
+        });
+      }
+      return;
     default:
       issues.push({
         path: `${path}.type`,