@beyondwork/docx-react-component 1.0.47 → 1.0.48

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

@@ -4,22 +4,8 @@ import type {
   ThemeFontScheme,
   ResolvedTheme,
 } from "../../model/canonical-document.ts";
-
-// ---- XML node types (inline, no external dep) ----
-
-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 } from "./xml-element.ts";
+import { parseXml } from "./xml-parser.ts";
 
 // ---- Well-known DrawingML color slot names ----
 
@@ -233,114 +219,3 @@ function localName(name: string): string {
   return idx >= 0 ? name.slice(idx + 1) : name;
 }
 
-// ---- Minimal XML parser ----
-
-function parseXml(xml: string): XmlElementNode {
-  const root: XmlElementNode = {
-    type: "element",
-    name: "__root__",
-    attributes: {},
-    children: [],
-  };
-  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),
-      });
-      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.trim().length > 0 || (text.length > 0 && stack.length > 1)) {
-        stack[stack.length - 1]?.children.push({ type: "text", text });
-      }
-      cursor = end;
-      continue;
-    }
-
-    if (xml[cursor + 1] === "/") {
-      const end = xml.indexOf(">", cursor);
-      if (end < 0) break;
-      stack.pop();
-      cursor = end + 1;
-      continue;
-    }
-
-    const tagEnd = xml.indexOf(">", cursor);
-    if (tagEnd < 0) break;
-
-    const tagContent = xml.slice(cursor + 1, tagEnd);
-    const selfClosing = tagContent.endsWith("/");
-    const normalized = selfClosing ? tagContent.slice(0, -1).trimEnd() : tagContent;
-
-    const spaceIndex = normalized.search(/\s/);
-    const tagName = spaceIndex >= 0 ? normalized.slice(0, spaceIndex) : normalized;
-    const attrString = spaceIndex >= 0 ? normalized.slice(spaceIndex + 1) : "";
-    const attributes = parseAttributes(attrString);
-
-    const element: XmlElementNode = {
-      type: "element",
-      name: tagName,
-      attributes,
-      children: [],
-    };
-
-    stack[stack.length - 1]?.children.push(element);
-
-    if (!selfClosing) {
-      stack.push(element);
-    }
-
-    cursor = tagEnd + 1;
-  }
-
-  return root;
-}
-
-function parseAttributes(attrString: string): Record<string, string> {
-  const attrs: Record<string, string> = {};
-  const pattern = /([A-Za-z_:][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
-  for (const match of attrString.matchAll(pattern)) {
-    const name = match[1];
-    const value = match[3] ?? match[4] ?? "";
-    if (name) {
-      attrs[name] = decodeXmlEntities(value);
-    }
-  }
-  return attrs;
-}
-
-function decodeXmlEntities(text: string): string {
-  return text
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10)))
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) =>
-      String.fromCodePoint(Number.parseInt(hex, 16)),
-    );
-}

package/src/io/ooxml/xml-attr-helpers.ts

@@ -10,7 +10,7 @@
  * parse-styles.ts, parse-numbering.ts.
  */
 
-import type { XmlElementNode } from "./xml-element.ts";
+import type { XmlElementNode, XmlNode } from "./xml-element.ts";
 
 export function localName(name: string): string {
   const sep = name.indexOf(":");
@@ -26,6 +26,27 @@ export function findChildOptional(
   );
 }
 
+/**
+ * Depth-first search for the first descendant element with the given local name
+ * (namespace prefix ignored). Returns undefined if no descendant matches.
+ *
+ * Useful when the exact parent chain isn't known — e.g. descending into
+ * `<w:drawing>` to find a `<c:chart>` regardless of which DrawingML wrapper
+ * stands between them.
+ */
+export 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 nested = findFirstDescendant(child, local);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
 /** ST_OnOff: missing child → undefined; present bare or w:val="1|true|on" → true; w:val="0|false|off" → false. */
 export function readOnOff(node: XmlElementNode | undefined): boolean | undefined {
   if (!node) return undefined;
@@ -46,6 +67,43 @@ export function readIntVal(node: XmlElementNode | undefined): number | undefined
   return Number.isFinite(v) ? v : undefined;
 }
 
+/** Read the child's `val` attribute as a float. Returns undefined if missing or not a finite number. */
+export function readFloatVal(node: XmlElementNode | undefined): number | undefined {
+  if (!node) return undefined;
+  const raw = node.attributes["w:val"] ?? node.attributes.val;
+  if (raw === undefined) return undefined;
+  const v = Number.parseFloat(raw);
+  return Number.isFinite(v) ? v : undefined;
+}
+
+/**
+ * Return the concatenated text content of the first child element with the
+ * given local name. Returns undefined if the child is missing. Returns an
+ * empty string if the child exists but has no text.
+ */
+export function readStringChild(
+  node: XmlElementNode | undefined,
+  local: string,
+): string | undefined {
+  if (!node) return undefined;
+  const child = findChildOptional(node, local);
+  if (!child) return undefined;
+  return textContent(child);
+}
+
+/** Concatenate all descendant text nodes of an element into a single string. */
+export function textContent(node: XmlElementNode): string {
+  let out = "";
+  const walk = (children: XmlNode[]): void => {
+    for (const c of children) {
+      if (c.type === "text") out += c.text;
+      else walk(c.children);
+    }
+  };
+  walk(node.children);
+  return out;
+}
+
 /** Read an arbitrary attribute from a node as an int, with namespace fallback. */
 export function readIntAttr(node: XmlElementNode, attr: string): number | undefined {
   const raw = node.attributes[attr] ?? node.attributes[attr.replace(/^w:/, "")];

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

@@ -0,0 +1,142 @@
+/**
+ * Minimal XML parser shared across OOXML parsers.
+ *
+ * Handles the subset of XML that Office documents actually emit:
+ * elements, attributes, text, comments (stripped), processing instructions
+ * (stripped), and CDATA sections. Namespace prefixes are preserved verbatim
+ * on element and attribute names — strip with `localName()` from
+ * `xml-attr-helpers.ts` when lookups must be prefix-agnostic.
+ *
+ * Not a full XML conformance parser: does not validate element nesting,
+ * does not track source offsets on produced nodes, does not report errors on
+ * malformed input beyond best-effort early termination. Sufficient for every
+ * OOXML part we import.
+ *
+ * Originally inlined in `parse-theme.ts`; extracted here so the chart parsers
+ * and any future OOXML import path can share the same implementation.
+ */
+import type { XmlElementNode } from "./xml-element.ts";
+
+const ROOT_TAG = "__root__";
+
+/**
+ * Parse an XML string into a virtual root element. The root is a synthetic
+ * wrapper element whose `children` contain the top-level nodes from the
+ * source. Callers typically do `parseXml(xml).children.find(...)` or look up
+ * a specific top-level element via `findChildOptional`.
+ */
+export function parseXml(xml: string): XmlElementNode {
+  const root: XmlElementNode = {
+    type: "element",
+    name: ROOT_TAG,
+    attributes: {},
+    children: [],
+  };
+  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),
+      });
+      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.trim().length > 0 || (text.length > 0 && stack.length > 1)) {
+        stack[stack.length - 1]?.children.push({ type: "text", text });
+      }
+      cursor = end;
+      continue;
+    }
+
+    if (xml[cursor + 1] === "/") {
+      const end = xml.indexOf(">", cursor);
+      if (end < 0) break;
+      stack.pop();
+      cursor = end + 1;
+      continue;
+    }
+
+    const tagEnd = xml.indexOf(">", cursor);
+    if (tagEnd < 0) break;
+
+    const tagContent = xml.slice(cursor + 1, tagEnd);
+    const selfClosing = tagContent.endsWith("/");
+    const normalized = selfClosing
+      ? tagContent.slice(0, -1).trimEnd()
+      : tagContent;
+
+    const spaceIndex = normalized.search(/\s/);
+    const tagName =
+      spaceIndex >= 0 ? normalized.slice(0, spaceIndex) : normalized;
+    const attrString = spaceIndex >= 0 ? normalized.slice(spaceIndex + 1) : "";
+    const attributes = parseAttributes(attrString);
+
+    const element: XmlElementNode = {
+      type: "element",
+      name: tagName,
+      attributes,
+      children: [],
+    };
+
+    stack[stack.length - 1]?.children.push(element);
+
+    if (!selfClosing) {
+      stack.push(element);
+    }
+
+    cursor = tagEnd + 1;
+  }
+
+  return root;
+}
+
+/** Decode the standard XML entity references plus numeric character references. */
+export function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, dec) =>
+      String.fromCodePoint(Number.parseInt(dec, 10)),
+    )
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) =>
+      String.fromCodePoint(Number.parseInt(hex, 16)),
+    );
+}
+
+function parseAttributes(attrString: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const pattern = /([A-Za-z_:][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  for (const match of attrString.matchAll(pattern)) {
+    const name = match[1];
+    const value = match[3] ?? match[4] ?? "";
+    if (name) {
+      attrs[name] = decodeXmlEntities(value);
+    }
+  }
+  return attrs;
+}

package/src/model/canonical-document.ts

@@ -12,6 +12,14 @@ import {
   expectUuid,
   stableStringify,
 } from "./cds-1.0.0.ts";
+import type {
+  ScopeMarkerStartNode,
+  ScopeMarkerEndNode,
+} from "./scope-markers.ts";
+import type { ChartModel } from "../io/ooxml/chart/types.ts";
+
+export type { ScopeMarkerStartNode, ScopeMarkerEndNode } from "./scope-markers.ts";
+export type { ChartModel } from "../io/ooxml/chart/types.ts";
 
 const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
   "schemaVersion",
@@ -97,6 +105,14 @@ export interface ParagraphStyleDefinition {
   isDefault: boolean;
   paragraphProperties?: CanonicalParagraphFormatting;
   runProperties?: CanonicalRunFormatting;
+  /**
+   * Style ID of the linked character style (from `<w:link w:val="..."/>`).
+   * Populated during parse; the second-pass resolver in `parse-styles.ts`
+   * synthesizes the reciprocal link on the partner when the source only
+   * declares the relationship on one side. Mirrors LibreOffice's
+   * `StyleSheetTable.cxx:535` second pass.
+   */
+  linkedStyleId?: string;
 }
 
 export interface ParagraphStyleNumberingReference {
@@ -111,6 +127,12 @@ export interface CharacterStyleDefinition {
   kind: "character";
   isDefault: boolean;
   runProperties?: CanonicalRunFormatting;
+  /**
+   * Style ID of the linked paragraph style (from `<w:link w:val="..."/>`).
+   * See `ParagraphStyleDefinition.linkedStyleId` for the second-pass
+   * reciprocal-resolution contract.
+   */
+  linkedStyleId?: string;
 }
 
 export interface TableStyleDefinition {
@@ -257,9 +279,63 @@ export interface ThemeDefinition {
   fontScheme?: ThemeFontScheme;
 }
 
+/**
+ * One <w:compatSetting> entry under <w:compat>. Word emits multiple of these
+ * with the same `name` across different `uri` namespaces, so the canonical
+ * shape is an ordered tuple list rather than a name→value map.
+ *
+ * `value` is preserved as the raw `w:val` string (e.g. "15", "1", "0") so the
+ * future serializer can re-emit byte-stable diffs.
+ */
+export interface CompatSetting {
+  name: string;
+  uri: string;
+  value: string;
+}
+
 export interface DocumentSettings {
   evenAndOddHeaders?: boolean;
   zoomLevel?: "pageWidth" | "onePage" | number;
+  /**
+   * Ordered list of <w:compatSetting> entries inside <w:compat>. Insertion
+   * order is preserved for serializer diff stability.
+   */
+  compatSettings?: CompatSetting[];
+  /**
+   * Boolean flag children of <w:compat> that are NOT <w:compatSetting>
+   * (e.g. <w:spaceForUL/>, <w:doNotExpandShiftReturn/>). Keyed by local
+   * element name. The value reflects ST_OnOff semantics: missing `w:val` is
+   * true; explicit `w:val="0"`/`"false"` is false.
+   */
+  compatFlags?: Record<string, boolean>;
+  /**
+   * Settings-level (NOT inside <w:compat>) compat-adjacent boolean flags
+   * such as <w:doNotEmbedSmartTags/>. Kept in a separate field from
+   * compatFlags because the OOXML location differs and the future
+   * serializer must re-emit them at root, not inside <w:compat>.
+   */
+  rootCompatFlags?: Record<string, boolean>;
+  /**
+   * <w:themeFontLang> attribute bag, captured verbatim so the future
+   * serializer can re-emit unknown attributes Word may add.
+   *
+   * Distinguishes three states:
+   *   - undefined: the element was absent.
+   *   - {}: the element existed with no attributes.
+   *   - { "w:val": "en-US", … }: attributes preserved with their qualified
+   *     names so the serializer round-trips namespace prefixes intact.
+   */
+  themeFontLang?: Record<string, string>;
+  /**
+   * Local names of every direct child of <w:settings> that this parser does
+   * not model individually. Insertion order preserved; duplicates retained.
+   *
+   * Diagnostic only — round-trip is served by whole-part preservation while
+   * settings.xml stays out of `ownedOutputPaths`. The future serializer will
+   * use this list as a validator assertion that every preserved child still
+   * appears in the re-emitted output.
+   */
+  unmodelledSettingsChildren?: string[];
 }
 
 export interface SubPartsCatalog {
@@ -305,6 +381,8 @@ export type DocumentNode =
   | FieldNode
   | BookmarkStartNode
   | BookmarkEndNode
+  | ScopeMarkerStartNode
+  | ScopeMarkerEndNode
   | SectionBreakNode
   | OpaqueInlineNode
   | OpaqueBlockNode
@@ -890,6 +968,8 @@ export type InlineNode =
   | FieldNode
   | BookmarkStartNode
   | BookmarkEndNode
+  | ScopeMarkerStartNode
+  | ScopeMarkerEndNode
   | OpaqueInlineNode
   | FootnoteRefNode
   | ChartPreviewNode
@@ -992,6 +1072,16 @@ export interface OpaqueInlineNode {
 export interface ChartPreviewNode {
   type: "chart_preview";
   previewMediaId?: string;
+  /**
+   * Typed chart data model parsed from the `c:chartSpace` part, when
+   * available. Populated at import time by the Stage 1 chart parser
+   * (`src/io/ooxml/chart/parse-chart-space.ts`). Undefined when the chart
+   * part cannot be located, fails to parse, or has no chart-family match
+   * — consumers fall back to the fallback bitmap (`previewMediaId`) or the
+   * typed badge in that case. `rawXml` is the authoritative round-trip
+   * source regardless of whether `parsedData` is populated.
+   */
+  parsedData?: ChartModel;
   rawXml: string;
 }
 
@@ -1658,6 +1748,10 @@ function validateDocumentNode(
     case "bookmark_end":
       expectString(record.bookmarkId, `${path}.bookmarkId`, issues);
       return;
+    case "scope_marker_start":
+    case "scope_marker_end":
+      expectString(record.scopeId, `${path}.scopeId`, issues);
+      return;
     case "section_break":
       return;
     case "text":

package/src/model/scope-markers.ts

@@ -0,0 +1,144 @@
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  DocumentRootNode,
+} from "./canonical-document.ts";
+
+/**
+ * Inline zero-width marker that opens a workflow scope. Modeled on
+ * `BookmarkStartNode` — the marker lives IN the document so PM handles
+ * position bookkeeping for free. `scopeId` is the key; metadata persistence
+ * is orthogonal and owned by `WorkflowOverlay` + customXml payloads.
+ */
+export interface ScopeMarkerStartNode {
+  type: "scope_marker_start";
+  scopeId: string;
+}
+
+/**
+ * Inline zero-width marker that closes a workflow scope opened by a matching
+ * `ScopeMarkerStartNode` with the same `scopeId`.
+ */
+export interface ScopeMarkerEndNode {
+  type: "scope_marker_end";
+  scopeId: string;
+}
+
+export type ScopeMarkerNode = ScopeMarkerStartNode | ScopeMarkerEndNode;
+
+export function isScopeMarkerNode(node: unknown): node is ScopeMarkerNode {
+  if (typeof node !== "object" || node === null) return false;
+  const t = (node as { type?: unknown }).type;
+  return t === "scope_marker_start" || t === "scope_marker_end";
+}
+
+export interface ScopeMarkerWalkEntry {
+  scopeId: string;
+  source: "canonical";
+  status: "paired" | "start-only" | "end-only";
+  startIndex?: number;
+  endIndex?: number;
+}
+
+interface OpenScopeMarker {
+  scopeId: string;
+  startIndex: number;
+}
+
+/**
+ * Walk the canonical document in pre-order and return one entry per scope
+ * detected. A paired entry carries both `startIndex` + `endIndex`; an
+ * unpaired entry has only the surviving side filled.
+ */
+export function collectScopeMarkers(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): ScopeMarkerWalkEntry[] {
+  const root = ("content" in document
+    ? document.content
+    : document) as DocumentNode | DocumentRootNode;
+  const sequence: ScopeMarkerNode[] = [];
+
+  walkDocument(root, (node) => {
+    if (isScopeMarkerNode(node)) {
+      sequence.push(node);
+    }
+  });
+
+  const open = new Map<string, OpenScopeMarker[]>();
+  const results: ScopeMarkerWalkEntry[] = [];
+
+  for (let index = 0; index < sequence.length; index += 1) {
+    const marker = sequence[index]!;
+    if (marker.type === "scope_marker_start") {
+      const stack = open.get(marker.scopeId) ?? [];
+      stack.push({ scopeId: marker.scopeId, startIndex: index });
+      open.set(marker.scopeId, stack);
+      continue;
+    }
+
+    const stack = open.get(marker.scopeId);
+    const opener = stack?.pop();
+    if (stack && stack.length === 0) {
+      open.delete(marker.scopeId);
+    }
+
+    if (opener) {
+      results.push({
+        scopeId: marker.scopeId,
+        source: "canonical",
+        status: "paired",
+        startIndex: opener.startIndex,
+        endIndex: index,
+      });
+      continue;
+    }
+
+    results.push({
+      scopeId: marker.scopeId,
+      source: "canonical",
+      status: "end-only",
+      endIndex: index,
+    });
+  }
+
+  for (const stack of open.values()) {
+    for (const opener of stack) {
+      results.push({
+        scopeId: opener.scopeId,
+        source: "canonical",
+        status: "start-only",
+        startIndex: opener.startIndex,
+      });
+    }
+  }
+
+  return results.sort(
+    (left, right) =>
+      (left.startIndex ?? left.endIndex ?? Number.MAX_SAFE_INTEGER) -
+        (right.startIndex ?? right.endIndex ?? Number.MAX_SAFE_INTEGER) ||
+      left.scopeId.localeCompare(right.scopeId),
+  );
+}
+
+function walkDocument(
+  node: DocumentNode | DocumentRootNode,
+  visit: (node: DocumentNode) => void,
+): void {
+  visit(node as DocumentNode);
+
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      walkDocument(child as DocumentNode, visit);
+    }
+  }
+
+  if (node.type === "table") {
+    for (const row of node.rows) {
+      walkDocument(row, visit);
+    }
+  } else if (node.type === "table_row") {
+    for (const cell of node.cells) {
+      walkDocument(cell, visit);
+    }
+  }
+}