@beyondwork/docx-react-component 1.0.1 → 1.0.3

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

@@ -0,0 +1,403 @@
+import type {
+  BlockNode,
+  FootnoteCollection,
+  FootnoteDefinition,
+  InlineNode,
+  ParagraphNode,
+  TextMark,
+} 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;
+
+// ---- Special footnote/endnote IDs to skip ----
+
+const SPECIAL_NOTE_IDS = new Set(["-1", "0"]);
+const SPECIAL_NOTE_TYPES = new Set(["separator", "continuationSeparator"]);
+
+// ---- Public API ----
+
+/**
+ * Parse footnotes.xml (<w:footnotes> root) into a FootnoteCollection.
+ * Also accepts endnotes.xml (<w:endnotes> root).
+ */
+export function parseFootnotesXml(xml: string): FootnoteCollection {
+  const root = parseXml(xml);
+
+  const footnotesElement = findChildElementOptional(root, "footnotes");
+  const endnotesElement = findChildElementOptional(root, "endnotes");
+
+  const footnotes: Record<string, FootnoteDefinition> = {};
+  const endnotes: Record<string, FootnoteDefinition> = {};
+
+  if (footnotesElement) {
+    for (const child of footnotesElement.children) {
+      if (child.type !== "element") {
+        continue;
+      }
+      if (localName(child.name) !== "footnote") {
+        continue;
+      }
+      const definition = parseNoteElement(child, "footnote");
+      if (definition) {
+        footnotes[definition.noteId] = definition;
+      }
+    }
+  }
+
+  if (endnotesElement) {
+    for (const child of endnotesElement.children) {
+      if (child.type !== "element") {
+        continue;
+      }
+      if (localName(child.name) !== "endnote") {
+        continue;
+      }
+      const definition = parseNoteElement(child, "endnote");
+      if (definition) {
+        endnotes[definition.noteId] = definition;
+      }
+    }
+  }
+
+  return { footnotes, endnotes };
+}
+
+/**
+ * Parse a standalone endnotes.xml (<w:endnotes> root).
+ * Merges into the provided collection or creates a new one.
+ */
+export function parseEndnotesXml(
+  xml: string,
+  existing?: FootnoteCollection,
+): FootnoteCollection {
+  const root = parseXml(xml);
+  const endnotesElement = findChildElementOptional(root, "endnotes");
+  const endnotes: Record<string, FootnoteDefinition> = {
+    ...(existing?.endnotes ?? {}),
+  };
+
+  if (endnotesElement) {
+    for (const child of endnotesElement.children) {
+      if (child.type !== "element") {
+        continue;
+      }
+      if (localName(child.name) !== "endnote") {
+        continue;
+      }
+      const definition = parseNoteElement(child, "endnote");
+      if (definition) {
+        endnotes[definition.noteId] = definition;
+      }
+    }
+  }
+
+  return {
+    footnotes: existing?.footnotes ?? {},
+    endnotes,
+  };
+}
+
+// ---- Internal helpers ----
+
+function parseNoteElement(
+  element: XmlElementNode,
+  kind: "footnote" | "endnote",
+): FootnoteDefinition | undefined {
+  const rawId =
+    element.attributes["w:id"] ?? element.attributes.id ?? "";
+  const rawType =
+    element.attributes["w:type"] ?? element.attributes.type ?? "";
+
+  if (!rawId || SPECIAL_NOTE_IDS.has(rawId) || SPECIAL_NOTE_TYPES.has(rawType)) {
+    return undefined;
+  }
+
+  const noteId = rawId;
+  const blocks: BlockNode[] = [];
+
+  for (const child of element.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+    const name = localName(child.name);
+    if (name === "p") {
+      blocks.push(parseParagraphElement(child));
+    } else if (name === "tbl") {
+      blocks.push({
+        type: "opaque_block",
+        fragmentId: `fragment:note-tbl-${noteId}`,
+        warningId: `warning:note-opaque-table`,
+      });
+    } else {
+      blocks.push({
+        type: "opaque_block",
+        fragmentId: `fragment:note-opaque-${noteId}`,
+        warningId: `warning:note-opaque-block`,
+      });
+    }
+  }
+
+  return { noteId, kind, blocks };
+}
+
+function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
+  let styleId: string | undefined;
+  const children: InlineNode[] = [];
+
+  for (const child of pElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (name === "pPr") {
+      const pStyle = findChildElementOptional(child, "pStyle");
+      styleId = pStyle?.attributes["w:val"] ?? pStyle?.attributes.val;
+    } else if (name === "r") {
+      children.push(...parseRunElement(child));
+    } else if (name === "hyperlink") {
+      for (const hChild of child.children) {
+        if (hChild.type === "element" && localName(hChild.name) === "r") {
+          children.push(...parseRunElement(hChild));
+        }
+      }
+    }
+  }
+
+  return {
+    type: "paragraph",
+    ...(styleId ? { styleId } : {}),
+    children,
+  };
+}
+
+function parseRunElement(rElement: XmlElementNode): InlineNode[] {
+  const nodes: InlineNode[] = [];
+  const marks: TextMark[] = parseRunProperties(rElement);
+
+  for (const child of rElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (name === "t") {
+      const text = extractTextContent(child);
+      if (text.length > 0) {
+        nodes.push({
+          type: "text",
+          text,
+          ...(marks.length > 0 ? { marks } : {}),
+        });
+      }
+    } else if (name === "br") {
+      nodes.push({ type: "hard_break" });
+    } else if (name === "tab") {
+      nodes.push({ type: "tab" });
+    } else if (name === "footnoteRef" || name === "endnoteRef") {
+      // The in-note reference marker (superscript) - skip, rendered by the host
+    } else if (name === "footnoteReference") {
+      const noteId =
+        child.attributes["w:id"] ?? child.attributes.id ?? "";
+      if (noteId) {
+        nodes.push({ type: "footnote_ref", noteId, noteKind: "footnote" });
+      }
+    } else if (name === "endnoteReference") {
+      const noteId =
+        child.attributes["w:id"] ?? child.attributes.id ?? "";
+      if (noteId) {
+        nodes.push({ type: "footnote_ref", noteId, noteKind: "endnote" });
+      }
+    }
+  }
+
+  return nodes;
+}
+
+function parseRunProperties(rElement: XmlElementNode): TextMark[] {
+  const rPr = findChildElementOptional(rElement, "rPr");
+  if (!rPr) {
+    return [];
+  }
+
+  const marks: TextMark[] = [];
+
+  for (const child of rPr.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+    const val = child.attributes["w:val"] ?? child.attributes.val ?? "true";
+
+    switch (name) {
+      case "b":
+        if (val !== "0" && val !== "false") marks.push({ type: "bold" });
+        break;
+      case "i":
+        if (val !== "0" && val !== "false") marks.push({ type: "italic" });
+        break;
+      case "u":
+        if (val !== "none" && val !== "0") marks.push({ type: "underline" });
+        break;
+      case "strike":
+        if (val !== "0" && val !== "false") marks.push({ type: "strikethrough" });
+        break;
+    }
+  }
+
+  return marks;
+}
+
+function extractTextContent(tElement: XmlElementNode): string {
+  let text = "";
+  for (const child of tElement.children) {
+    if (child.type === "text") {
+      text += child.text;
+    }
+  }
+  return text;
+}
+
+function findChildElementOptional(
+  node: XmlElementNode,
+  childLocalName: string,
+): XmlElementNode | undefined {
+  return node.children.find(
+    (entry): entry is XmlElementNode =>
+      entry.type === "element" && localName(entry.name) === childLocalName,
+  );
+}
+
+function localName(name: string): string {
+  const idx = name.indexOf(":");
+  return idx >= 0 ? name.slice(idx + 1) : name;
+}
+
+// ---- Minimal XML parser (same pattern as parse-numbering.ts) ----
+
+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)),
+    );
+}