@beyondwork/docx-react-component 1.0.55 → 1.0.57

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

@@ -146,6 +146,117 @@ export function extractBookmarksFromBodyXml(bodyXml: string): ParsedBookmarkNode
   return results;
 }
 
+// ─── FieldGroup stream walker ─────────────────────────────────────────────────
+
+/**
+ * A fully-parsed fldChar triad: begin → instrText* → separate → display → end.
+ * Unlike `ParsedComplexFieldNode`, this captures cross-paragraph triads by
+ * walking the body-level run list flattened across all block elements.
+ *
+ * Fail-closed: an incomplete triad (begin with no end) is silently discarded.
+ */
+export interface FieldGroup {
+  /** Joined instrText content (trimmed). */
+  instruction: string;
+  /** Raw XML of all runs between the separate and end fldChar runs. */
+  displayContent: string;
+  /** Byte offset in sourceXml where the begin run starts. */
+  start: number;
+  /** Byte offset (exclusive) where the end run ends. */
+  end: number;
+}
+
+/**
+ * Stream-walk all block elements in a body XML string and emit one
+ * `FieldGroup` per complete fldChar triad.  Handles cross-paragraph
+ * triads (e.g., TOC fields that span multiple <w:p> siblings).
+ *
+ * Fail-closed: a begin with no matching end is silently dropped.
+ */
+export function streamWalkFieldGroups(bodyXml: string): FieldGroup[] {
+  const root = parseXml(bodyXml);
+  const bodyEl =
+    findFirstChild(root, "body") ??
+    findFirstChild(root, "document") ??
+    root;
+
+  const allRuns: XmlElementNode[] = [];
+  collectRunsDeep(bodyEl, allRuns);
+
+  return extractFieldGroupsFromRuns(allRuns, bodyXml);
+}
+
+function collectRunsDeep(node: XmlElementNode, out: XmlElementNode[]): void {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) === "r") {
+      out.push(child);
+    } else {
+      collectRunsDeep(child, out);
+    }
+  }
+}
+
+function extractFieldGroupsFromRuns(
+  runs: XmlElementNode[],
+  sourceXml: string,
+): FieldGroup[] {
+  type State = "idle" | "in-instr" | "in-content";
+  let state: State = "idle";
+  let instrParts: string[] = [];
+  let fieldStart = -1;
+  let contentStart = -1;
+  const results: FieldGroup[] = [];
+
+  for (const run of runs) {
+    const fldChar = findFirstChildEl(run, "fldChar");
+    const instrText = findFirstChildEl(run, "instrText");
+
+    if (fldChar) {
+      const charType = (
+        fldChar.attributes["w:fldCharType"] ??
+        fldChar.attributes.fldCharType ??
+        ""
+      ).toLowerCase();
+
+      if (charType === "begin") {
+        state = "in-instr";
+        instrParts = [];
+        fieldStart = run.start;
+        contentStart = -1;
+      } else if (charType === "separate" && state === "in-instr") {
+        state = "in-content";
+        contentStart = run.end;
+      } else if (charType === "end") {
+        if (state === "in-content" || state === "in-instr") {
+          const displayContent =
+            contentStart >= 0 && contentStart <= run.start
+              ? sourceXml.slice(contentStart, run.start)
+              : "";
+          results.push({
+            instruction: instrParts.join("").trim(),
+            displayContent,
+            start: fieldStart,
+            end: run.end,
+          });
+        }
+        state = "idle";
+        instrParts = [];
+        fieldStart = -1;
+        contentStart = -1;
+      }
+    } else if (instrText && state === "in-instr") {
+      const text = instrText.children
+        .filter((c): c is XmlTextNode => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+      instrParts.push(text);
+    }
+  }
+
+  return results;
+}
+
 // ─── Element-level parsers (exported for unit testing) ────────────────────────
 
 export function parseFldSimple(
@@ -309,7 +420,7 @@ export function buildFieldRegistry(
     paragraphIndex = pIdx;
     if (node.type === "field") {
       const classification = node.fieldFamily
-        ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget }
+        ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget, switches: node.switches }
         : classifyFieldInstruction(node.instruction);
       const displayText = flattenFieldText(node.children);
       const entry: FieldRegistryEntry = {
@@ -321,6 +432,7 @@ export function buildFieldRegistry(
         displayText,
         paragraphIndex,
         refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+        ...(classification.switches ? { switches: classification.switches } : {}),
       };
       if (classification.supported) {
         supported.push(entry);
@@ -338,7 +450,7 @@ export function buildFieldRegistry(
       paragraphIndex = pIdx;
       if (node.type === "field") {
         const classification = node.fieldFamily
-          ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget }
+          ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget, switches: node.switches }
           : classifyFieldInstruction(node.instruction);
         const displayText = flattenFieldText(node.children);
         const entry: FieldRegistryEntry = {
@@ -350,6 +462,7 @@ export function buildFieldRegistry(
           displayText,
           paragraphIndex,
           refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+          ...(classification.switches ? { switches: classification.switches } : {}),
         };
         if (classification.supported) {
           supported.push(entry);

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

@@ -0,0 +1,215 @@
+/**
+ * parse-fill.ts
+ *
+ * Shared fill-parsing primitives for DrawingML cascade reads. Covers
+ * `a:solidFill`, `a:noFill`, `a:gradFill`, and `a:pattFill`.
+ *
+ * Exposed for:
+ * - `parse-shapes.ts::parseShapeContent` (wps:wsp → ShapeContent.fill) — CO4
+ * - `src/io/ooxml/chart/**` (chart-style + series fill cascade) — Lane 5 Stage 2+
+ *
+ * The `colorType` discriminant on solid-fill keeps `schemeClr` tokens raw so
+ * CO1's ThemeColorResolver can resolve them to effective rgb later. Gradient
+ * and pattern colors use the same `ColorToken` shape for consistency.
+ *
+ * Legacy export: `parseSolidFill` is retained for back-compat with existing
+ * call sites; new code should prefer `parseFill` which dispatches across all
+ * four fill families.
+ */
+
+export interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+export interface ColorToken {
+  color: string;
+  colorType: "srgbClr" | "schemeClr";
+}
+
+export type SolidFillResult =
+  | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
+  | { kind: "none" };
+
+export interface GradientStop {
+  /** Position along the gradient axis in 0..100000 (= 0..100%). */
+  pos: number;
+  color: string;
+  colorType: "srgbClr" | "schemeClr";
+}
+
+export type GradientDirection =
+  | { kind: "linear"; angle: number; scaled?: boolean } // angle in 60000ths of degree
+  | { kind: "path"; path: "circle" | "rect" | "shape" };
+
+export interface GradientFillResult {
+  kind: "gradient";
+  stops: GradientStop[];
+  direction: GradientDirection;
+  /** Rotate with shape (a:gradFill rotWithShape). Defaults true per OOXML. */
+  rotWithShape?: boolean;
+}
+
+export interface PatternFillResult {
+  kind: "pattern";
+  /** Preset pattern token (e.g. "wdDkVert", "pct50"). Raw OOXML value. */
+  preset: string;
+  fg?: ColorToken;
+  bg?: ColorToken;
+}
+
+export type FillResult = SolidFillResult | GradientFillResult | PatternFillResult;
+
+/**
+ * Parse any OOXML fill child of a shape-property element.
+ *
+ * Returns the first recognised fill variant found among:
+ * - `a:noFill`
+ * - `a:solidFill`
+ * - `a:gradFill`
+ * - `a:pattFill`
+ *
+ * Returns `undefined` when none of the above are direct children.
+ */
+export function parseFill(parent: XmlElementNode): FillResult | undefined {
+  if (findFirstChild(parent, "noFill")) return { kind: "none" };
+  const solid = findFirstChild(parent, "solidFill");
+  if (solid) return parseSolidFillInner(solid);
+  const grad = findFirstChild(parent, "gradFill");
+  if (grad) return parseGradientFill(grad);
+  const pat = findFirstChild(parent, "pattFill");
+  if (pat) return parsePatternFill(pat);
+  return undefined;
+}
+
+/**
+ * Legacy `parseSolidFill` entry point (still used by `parse-shapes.ts::readFill`).
+ * Returns only `SolidFillResult` — callers that want gradient/pattern should
+ * migrate to `parseFill`.
+ */
+export function parseSolidFill(parent: XmlElementNode): SolidFillResult | undefined {
+  const noFill = findFirstChild(parent, "noFill");
+  if (noFill) return { kind: "none" };
+  const solid = findFirstChild(parent, "solidFill");
+  if (!solid) return undefined;
+  return parseSolidFillInner(solid);
+}
+
+function parseSolidFillInner(solid: XmlElementNode): SolidFillResult | undefined {
+  const srgb = findFirstChild(solid, "srgbClr");
+  if (srgb?.attributes.val) {
+    return {
+      kind: "solid",
+      color: srgb.attributes.val.toUpperCase(),
+      colorType: "srgbClr",
+    };
+  }
+  const scheme = findFirstChild(solid, "schemeClr");
+  if (scheme?.attributes.val) {
+    return {
+      kind: "solid",
+      color: scheme.attributes.val,
+      colorType: "schemeClr",
+    };
+  }
+  return undefined;
+}
+
+function parseGradientFill(grad: XmlElementNode): GradientFillResult | undefined {
+  const gsLst = findFirstChild(grad, "gsLst");
+  if (!gsLst) return undefined;
+  const stops: GradientStop[] = [];
+  for (const child of gsLst.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "gs") continue;
+    const posRaw = child.attributes.pos;
+    const pos = posRaw !== undefined ? parseInt(posRaw, 10) : 0;
+    const token = extractColorToken(child);
+    if (!token) continue;
+    stops.push({ pos: Number.isFinite(pos) ? pos : 0, ...token });
+  }
+  if (stops.length === 0) return undefined;
+
+  const direction = readGradientDirection(grad);
+  const rotWithShapeRaw = grad.attributes.rotWithShape;
+  const rotWithShape =
+    rotWithShapeRaw === undefined ? undefined : rotWithShapeRaw !== "0" && rotWithShapeRaw !== "false";
+
+  const result: GradientFillResult = { kind: "gradient", stops, direction };
+  if (rotWithShape !== undefined) result.rotWithShape = rotWithShape;
+  return result;
+}
+
+function readGradientDirection(grad: XmlElementNode): GradientDirection {
+  const lin = findFirstChild(grad, "lin");
+  if (lin) {
+    const ang = parseInt(lin.attributes.ang ?? "0", 10) || 0;
+    const scaledRaw = lin.attributes.scaled;
+    const scaled = scaledRaw !== undefined ? scaledRaw !== "0" && scaledRaw !== "false" : undefined;
+    const d: GradientDirection = { kind: "linear", angle: ang };
+    if (scaled !== undefined) d.scaled = scaled;
+    return d;
+  }
+  const path = findFirstChild(grad, "path");
+  if (path) {
+    const pathKind = path.attributes.path;
+    if (pathKind === "circle" || pathKind === "rect" || pathKind === "shape") {
+      return { kind: "path", path: pathKind };
+    }
+  }
+  // Default: OOXML implicit linear at 0°
+  return { kind: "linear", angle: 0 };
+}
+
+function parsePatternFill(pat: XmlElementNode): PatternFillResult | undefined {
+  const preset = pat.attributes.prst;
+  if (!preset) return undefined;
+  const fgEl = findFirstChild(pat, "fgClr");
+  const bgEl = findFirstChild(pat, "bgClr");
+  const result: PatternFillResult = { kind: "pattern", preset };
+  if (fgEl) {
+    const t = extractColorToken(fgEl);
+    if (t) result.fg = t;
+  }
+  if (bgEl) {
+    const t = extractColorToken(bgEl);
+    if (t) result.bg = t;
+  }
+  return result;
+}
+
+function extractColorToken(parent: XmlElementNode): ColorToken | undefined {
+  const srgb = findFirstChild(parent, "srgbClr");
+  if (srgb?.attributes.val) {
+    return { color: srgb.attributes.val.toUpperCase(), colorType: "srgbClr" };
+  }
+  const scheme = findFirstChild(parent, "schemeClr");
+  if (scheme?.attributes.val) {
+    return { color: scheme.attributes.val, colorType: "schemeClr" };
+  }
+  return 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;
+  }
+  return undefined;
+}
+
+function localName(name: string): string {
+  const i = name.indexOf(":");
+  return i >= 0 ? name.slice(i + 1) : name;
+}

package/src/io/ooxml/parse-font-table.ts

@@ -0,0 +1,190 @@
+/**
+ * Parse fontTable.xml into a CanonicalFontTable.
+ *
+ * Reads every <w:font> child of the root <w:fonts> element and materializes
+ * name/family/pitch/charset/altName. panose and sig metadata is not needed
+ * by consumers and is skipped.
+ *
+ * Key insight from LO FontTable.cxx: w:family is qualitative ("roman",
+ * "swiss", "modern", "script", "decorative") — do not treat as numeric.
+ * w:charset="02" marks Symbol fonts; consumers must handle glyph remapping.
+ */
+
+import type {
+  CanonicalFontEntry,
+  CanonicalFontTable,
+} 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;
+
+const KNOWN_FAMILIES = new Set(["roman", "swiss", "modern", "script", "decorative"]);
+
+export function parseFontTable(xml: string): CanonicalFontTable {
+  const root = parseXml(xml);
+  const fontsElement = findChildElementOptional(root, "fonts") ?? root;
+  const fonts: Record<string, CanonicalFontEntry> = {};
+
+  for (const child of fontsElement.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "font") continue;
+
+    const name = child.attributes["w:name"] ?? child.attributes["name"];
+    if (!name) continue;
+
+    const entry: CanonicalFontEntry = { name };
+
+    for (const sub of child.children) {
+      if (sub.type !== "element") continue;
+      switch (localName(sub.name)) {
+        case "family": {
+          const raw = sub.attributes["w:val"] ?? sub.attributes["val"];
+          if (raw && KNOWN_FAMILIES.has(raw)) {
+            entry.family = raw as CanonicalFontEntry["family"];
+          }
+          break;
+        }
+        case "pitch": {
+          const raw = sub.attributes["w:val"] ?? sub.attributes["val"];
+          if (raw === "fixed" || raw === "variable" || raw === "default") {
+            entry.pitch = raw;
+          }
+          break;
+        }
+        case "charset": {
+          const raw = sub.attributes["w:val"] ?? sub.attributes["val"];
+          if (raw !== undefined) {
+            const parsed = Number.parseInt(raw, 16);
+            if (Number.isFinite(parsed)) entry.charset = parsed;
+          }
+          break;
+        }
+        case "altName": {
+          const raw = sub.attributes["w:val"] ?? sub.attributes["val"];
+          if (raw) entry.altName = raw;
+          break;
+        }
+      }
+    }
+
+    fonts[name] = entry;
+  }
+
+  return { fonts };
+}
+
+// ---------------------------------------------------------------------------
+// XML helpers — same shape as parse-numbering.ts internals
+// ---------------------------------------------------------------------------
+
+function localName(name: string): string {
+  const separator = name.indexOf(":");
+  return separator >= 0 ? name.slice(separator + 1) : name;
+}
+
+function findChildElementOptional(
+  node: XmlElementNode,
+  childLocalName: string,
+): XmlElementNode | undefined {
+  return node.children.find(
+    (entry): entry is XmlElementNode =>
+      entry.type === "element" && localName(entry.name) === childLocalName,
+  );
+}
+
+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[cursor] !== "<") {
+      const nextTag = xml.indexOf("<", cursor);
+      cursor = nextTag >= 0 ? nextTag : xml.length;
+      continue;
+    }
+    if (xml[cursor + 1] === "/") {
+      const end = xml.indexOf(">", cursor);
+      if (end < 0) throw new Error("Malformed XML: missing closing >.");
+      stack.pop();
+      cursor = end + 1;
+      continue;
+    }
+
+    const tagEnd = findTagEnd(xml, cursor);
+    const tagBody = xml.slice(cursor + 1, tagEnd);
+    const selfClosing = /\/\s*$/.test(tagBody);
+    const { name, attributes } = parseTag(tagBody.replace(/\/\s*$/, "").trim());
+
+    const element: XmlElementNode = {
+      type: "element",
+      name,
+      attributes,
+      children: [],
+    };
+    stack[stack.length - 1]?.children.push(element);
+    if (!selfClosing) stack.push(element);
+    cursor = tagEnd + 1;
+  }
+
+  return root;
+}
+
+function findTagEnd(xml: string, start: number): number {
+  let cursor = start + 1;
+  let inQuote: '"' | "'" | null = null;
+  while (cursor < xml.length) {
+    const ch = xml[cursor];
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+    } else {
+      if (ch === '"' || ch === "'") inQuote = ch;
+      else if (ch === ">") return cursor;
+    }
+    cursor++;
+  }
+  throw new Error("Malformed XML: missing closing >.");
+}
+
+function parseTag(body: string): { name: string; attributes: Record<string, string> } {
+  const attributes: Record<string, string> = {};
+  let cursor = 0;
+  while (cursor < body.length && !/\s/.test(body[cursor]!)) cursor++;
+  const name = body.slice(0, cursor);
+
+  const attrRegex = /([\w:\-.]+)\s*=\s*"([^"]*)"|([\w:\-.]+)\s*=\s*'([^']*)'/g;
+  let match: RegExpExecArray | null;
+  while ((match = attrRegex.exec(body)) !== null) {
+    const key = match[1] ?? match[3]!;
+    const value = match[2] ?? match[4] ?? "";
+    attributes[key] = value;
+  }
+
+  return { name, attributes };
+}

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

@@ -2,6 +2,7 @@ import type {
   BlockNode,
   FootnoteCollection,
   FootnoteDefinition,
+  FootnoteSeparators,
   InlineNode,
   ParagraphIndentation,
   ParagraphNode,
@@ -114,7 +115,12 @@ export function parseFootnotesXml(xml: string): FootnoteCollection {
     }
   }
 
-  return { footnotes, endnotes };
+  const footnoteSeparators = parseFootnoteSeparators(xml);
+  return {
+    footnotes,
+    endnotes,
+    ...(Object.keys(footnoteSeparators).length > 0 ? { footnoteSeparators } : {}),
+  };
 }
 
 /**
@@ -152,6 +158,51 @@ export function parseEndnotesXml(
   };
 }
 
+/**
+ * Extract separator and continuation-separator run XML from footnotes.xml
+ * or endnotes.xml. The special notes with `w:type="separator"` and
+ * `w:type="continuationSeparator"` contain horizontal-rule content used
+ * by the page-chrome renderer at the footnote divider line.
+ */
+export function parseFootnoteSeparators(xml: string): FootnoteSeparators {
+  const root = parseXml(xml);
+  const footnotesEl = findChildElementOptional(root, "footnotes");
+  const endnotesEl = findChildElementOptional(root, "endnotes");
+  const containerEl = footnotesEl ?? endnotesEl;
+  if (!containerEl) return {};
+
+  let separatorContent: string | undefined;
+  let continuationSeparatorContent: string | undefined;
+
+  for (const child of containerEl.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+    if (name !== "footnote" && name !== "endnote") continue;
+
+    const rawType = child.attributes["w:type"] ?? child.attributes.type ?? "";
+    if (rawType !== "separator" && rawType !== "continuationSeparator") continue;
+
+    const paraEl = findChildElementOptional(child, "p");
+    if (!paraEl) continue;
+
+    const runXml = paraEl.children
+      .filter((c): c is XmlElementNode => c.type === "element" && localName(c.name) === "r")
+      .map((r) => serializeElementToXml(r))
+      .join("");
+
+    if (rawType === "separator") {
+      separatorContent = runXml;
+    } else {
+      continuationSeparatorContent = runXml;
+    }
+  }
+
+  return {
+    ...(separatorContent !== undefined ? { separatorContent } : {}),
+    ...(continuationSeparatorContent !== undefined ? { continuationSeparatorContent } : {}),
+  };
+}
+
 // ---- Internal helpers ----
 
 function parseNoteElement(