@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,438 @@
+/**
+ * parse-fields.ts
+ *
+ * Standalone parsers for OOXML field codes (w:fldSimple, complex fldChar sequences)
+ * and bookmarks (w:bookmarkStart / w:bookmarkEnd).
+ *
+ * These types mirror the canonical FieldNode / BookmarkStartNode / BookmarkEndNode
+ * shapes from canonical-document.ts, but carry raw XML for preservation and are
+ * pre-normalization (no fragmentId / warningId yet).
+ *
+ * Usage: call parseFieldsFromParagraphXml() or parseBookmarksFromXml() for
+ * independent field/bookmark extraction.  The functions are designed to be
+ * imported by parse-main-document.ts when full pipeline integration is ready.
+ */
+
+// ─── Parsed types ────────────────────────────────────────────────────────────
+
+export interface ParsedSimpleFieldNode {
+  type: "field";
+  fieldType: "simple";
+  instruction: string;
+  /** Raw XML of the content runs inside <w:fldSimple>. */
+  contentXml: string;
+  rawXml: string;
+}
+
+export interface ParsedComplexFieldNode {
+  type: "field";
+  fieldType: "complex";
+  instruction: string;
+  /** Raw XML of the content runs between the "separate" and "end" fldChar. */
+  contentXml: string;
+  /** Start index in the source document XML. */
+  start: number;
+  /** End index (exclusive) in the source document XML. */
+  end: number;
+}
+
+export type ParsedFieldNode = ParsedSimpleFieldNode | ParsedComplexFieldNode;
+
+export interface ParsedBookmarkStartNode {
+  type: "bookmark_start";
+  bookmarkId: string;
+  name: string;
+  rawXml: string;
+}
+
+export interface ParsedBookmarkEndNode {
+  type: "bookmark_end";
+  bookmarkId: string;
+  rawXml: string;
+}
+
+export type ParsedBookmarkNode = ParsedBookmarkStartNode | ParsedBookmarkEndNode;
+
+// ─── Internal XML types ───────────────────────────────────────────────────────
+
+interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+  start: number;
+  end: number;
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+  start: number;
+  end: number;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Parse all simple fields and bookmarks from the XML of a single paragraph
+ * element.  Complex fields that span paragraphs are not fully resolved here;
+ * use extractComplexFieldsFromBodyXml for body-level extraction.
+ *
+ * @param paragraphXml  Raw XML string of a <w:p> element.
+ */
+export function parseFieldsFromParagraphXml(paragraphXml: string): {
+  simpleFields: ParsedSimpleFieldNode[];
+  bookmarks: ParsedBookmarkNode[];
+} {
+  const root = parseXml(paragraphXml);
+  const pEl = findFirstChild(root, "p");
+  const target = pEl ?? root;
+
+  const simpleFields: ParsedSimpleFieldNode[] = [];
+  const bookmarks: ParsedBookmarkNode[] = [];
+
+  for (const child of target.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "fldSimple") {
+      const field = parseFldSimple(child, paragraphXml);
+      if (field) simpleFields.push(field);
+    } else if (name === "bookmarkStart") {
+      const bk = parseBookmarkStart(child, paragraphXml);
+      if (bk) bookmarks.push(bk);
+    } else if (name === "bookmarkEnd") {
+      const bk = parseBookmarkEnd(child, paragraphXml);
+      if (bk) bookmarks.push(bk);
+    }
+  }
+
+  return { simpleFields, bookmarks };
+}
+
+/**
+ * Extract complex field sequences from a body element XML string.
+ * A complex field is a begin / instrText* / separate / content / end sequence
+ * spread across multiple <w:r> siblings.
+ *
+ * @param bodyXml  Raw XML string of a <w:body> element (or full document).
+ */
+export function extractComplexFieldsFromBodyXml(bodyXml: string): ParsedComplexFieldNode[] {
+  const root = parseXml(bodyXml);
+  const results: ParsedComplexFieldNode[] = [];
+
+  // Walk all <w:p> children of the body
+  const bodyEl = findFirstChild(root, "body") ?? findFirstChild(root, "document");
+  const scanTarget = bodyEl ?? root;
+
+  for (const block of scanTarget.children) {
+    if (block.type !== "element") continue;
+    if (localName(block.name) !== "p") continue;
+    extractComplexFieldsFromParagraph(block, bodyXml, results);
+  }
+
+  return results;
+}
+
+/**
+ * Parse all bookmark start/end nodes from a full document or body XML.
+ */
+export function extractBookmarksFromBodyXml(bodyXml: string): ParsedBookmarkNode[] {
+  const root = parseXml(bodyXml);
+  const results: ParsedBookmarkNode[] = [];
+  collectBookmarks(root, bodyXml, results);
+  return results;
+}
+
+// ─── Element-level parsers (exported for unit testing) ────────────────────────
+
+export function parseFldSimple(
+  element: { attributes: Record<string, string>; children: XmlNode[]; start: number; end: number },
+  sourceXml: string,
+): ParsedSimpleFieldNode | undefined {
+  const instruction = (element.attributes["w:instr"] ?? element.attributes.instr ?? "").trim();
+  const contentXml = element.children
+    .filter((c): c is XmlElementNode => c.type === "element")
+    .map((c) => sourceXml.slice(c.start, c.end))
+    .join("");
+  return {
+    type: "field",
+    fieldType: "simple",
+    instruction,
+    contentXml,
+    rawXml: sourceXml.slice(element.start, element.end),
+  };
+}
+
+export function parseBookmarkStart(
+  element: { attributes: Record<string, string>; start: number; end: number },
+  sourceXml: string,
+): ParsedBookmarkStartNode | undefined {
+  const bookmarkId = element.attributes["w:id"] ?? element.attributes.id ?? "";
+  const name = element.attributes["w:name"] ?? element.attributes.name ?? "";
+  if (!bookmarkId) return undefined;
+  return {
+    type: "bookmark_start",
+    bookmarkId,
+    name,
+    rawXml: sourceXml.slice(element.start, element.end),
+  };
+}
+
+export function parseBookmarkEnd(
+  element: { attributes: Record<string, string>; start: number; end: number },
+  sourceXml: string,
+): ParsedBookmarkEndNode | undefined {
+  const bookmarkId = element.attributes["w:id"] ?? element.attributes.id ?? "";
+  if (!bookmarkId) return undefined;
+  return {
+    type: "bookmark_end",
+    bookmarkId,
+    rawXml: sourceXml.slice(element.start, element.end),
+  };
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function extractComplexFieldsFromParagraph(
+  paragraph: XmlElementNode,
+  sourceXml: string,
+  results: ParsedComplexFieldNode[],
+): void {
+  type FieldState = "idle" | "in-instr" | "in-content";
+  let state: FieldState = "idle";
+  let instrParts: string[] = [];
+  let contentStart = -1;
+  let contentEnd = -1;
+  let fieldStart = -1;
+
+  for (const child of paragraph.children) {
+    if (child.type !== "element" || localName(child.name) !== "r") continue;
+
+    const fldChar = findFirstChildEl(child, "fldChar");
+    const instrText = findFirstChildEl(child, "instrText");
+
+    if (fldChar) {
+      const charType = (
+        fldChar.attributes["w:fldCharType"] ??
+        fldChar.attributes.fldCharType ??
+        ""
+      ).toLowerCase();
+
+      if (charType === "begin") {
+        state = "in-instr";
+        instrParts = [];
+        fieldStart = child.start;
+        contentStart = -1;
+        contentEnd = -1;
+      } else if (charType === "separate" && state === "in-instr") {
+        state = "in-content";
+        contentStart = child.end;
+      } else if (charType === "end") {
+        if (state === "in-content" || state === "in-instr") {
+          if (state === "in-content") {
+            contentEnd = child.start;
+          }
+          const instruction = instrParts.join("").trim();
+          const contentXml =
+            contentStart >= 0 && contentEnd >= contentStart
+              ? sourceXml.slice(contentStart, contentEnd)
+              : "";
+          results.push({
+            type: "field",
+            fieldType: "complex",
+            instruction,
+            contentXml,
+            start: fieldStart,
+            end: child.end,
+          });
+        }
+        state = "idle";
+        instrParts = [];
+      }
+    } 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);
+    }
+  }
+}
+
+function collectBookmarks(
+  node: XmlElementNode,
+  sourceXml: string,
+  results: ParsedBookmarkNode[],
+): void {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+    if (name === "bookmarkStart") {
+      const bk = parseBookmarkStart(child, sourceXml);
+      if (bk) results.push(bk);
+    } else if (name === "bookmarkEnd") {
+      const bk = parseBookmarkEnd(child, sourceXml);
+      if (bk) results.push(bk);
+    } else {
+      collectBookmarks(child, sourceXml, results);
+    }
+  }
+}
+
+function findFirstChild(node: XmlElementNode, childLocalName: string): XmlElementNode | undefined {
+  return node.children.find(
+    (c): c is XmlElementNode => c.type === "element" && localName(c.name) === childLocalName,
+  );
+}
+
+function findFirstChildEl(node: XmlElementNode, childLocalName: string): XmlElementNode | undefined {
+  return node.children.find(
+    (c): c is XmlElementNode => c.type === "element" && localName(c.name) === childLocalName,
+  );
+}
+
+function localName(name: string): string {
+  const sep = name.indexOf(":");
+  return sep >= 0 ? name.slice(sep + 1) : name;
+}
+
+// ─── Minimal XML parser (same pattern as parse-tables.ts) ────────────────────
+
+function parseXml(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 >.");
+      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 = 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: [],
+      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 parseTag(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 findTagEnd(xml: string, start: number): number {
+  let cursor = start + 1;
+  let quote: string | null = null;
+  while (cursor < xml.length) {
+    const c = xml[cursor];
+    if (quote) { if (c === quote) quote = null; cursor += 1; continue; }
+    if (c === `"` || c === `'`) { quote = c; cursor += 1; continue; }
+    if (c === ">") return cursor;
+    cursor += 1;
+  }
+  throw new Error("Malformed XML: missing >.");
+}
+
+function decodeXmlEntities(value: string): string {
+  return value.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (match, entity) => {
+    switch (entity) {
+      case "amp": return "&";
+      case "lt": return "<";
+      case "gt": return ">";
+      case "quot": return `"`;
+      case "apos": return `'`;
+      default:
+        if (entity.startsWith("#x")) return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+        if (entity.startsWith("#")) return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+        return match;
+    }
+  });
+}