@beyondwork/docx-react-component 1.0.18 → 1.0.20

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

@@ -0,0 +1,463 @@
+/**
+ * Parse styles.xml into the canonical StylesCatalog.
+ *
+ * Reads paragraph, character, and table style definitions plus latent-style
+ * metadata from the package styles part. This makes styles.xml the canonical
+ * source of style truth instead of synthesizing display names from referenced
+ * styleId values.
+ */
+
+import type {
+  CharacterStyleDefinition,
+  LatentStyleDefinition,
+  ParagraphStyleDefinition,
+  StylesCatalog,
+  TableStyleDefinition,
+} from "../../model/canonical-document.ts";
+
+// ---------------------------------------------------------------------------
+// Inline XML node types (same pattern as parse-numbering.ts)
+// ---------------------------------------------------------------------------
+
+interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface ParseStylesResult {
+  catalog: StylesCatalog;
+  /** True when the catalog was parsed from actual styles.xml content. */
+  fromPackage: boolean;
+  /** Diagnostic notes for logging/proof. */
+  diagnostics: string[];
+}
+
+/**
+ * Parse a styles.xml string into a canonical StylesCatalog.
+ *
+ * Returns `fromPackage: false` when the input is empty or structurally empty,
+ * in which case the catalog fields will be empty records.
+ */
+export function parseStylesXml(xml: string): ParseStylesResult {
+  const diagnostics: string[] = [];
+
+  if (!xml || xml.trim().length === 0) {
+    diagnostics.push("styles.xml is empty; synthetic fallback will be used");
+    return {
+      catalog: { paragraphs: {}, characters: {}, tables: {} },
+      fromPackage: false,
+      diagnostics,
+    };
+  }
+
+  let root: XmlElementNode;
+  try {
+    root = parseXml(xml);
+  } catch {
+    diagnostics.push("styles.xml could not be parsed; synthetic fallback will be used");
+    return {
+      catalog: { paragraphs: {}, characters: {}, tables: {} },
+      fromPackage: false,
+      diagnostics,
+    };
+  }
+
+  const stylesElement = findChildElementOptional(root, "styles");
+  if (!stylesElement) {
+    diagnostics.push("styles.xml has no <w:styles> root; synthetic fallback will be used");
+    return {
+      catalog: { paragraphs: {}, characters: {}, tables: {} },
+      fromPackage: false,
+      diagnostics,
+    };
+  }
+
+  const paragraphs: Record<string, ParagraphStyleDefinition> = {};
+  const characters: Record<string, CharacterStyleDefinition> = {};
+  const tables: Record<string, TableStyleDefinition> = {};
+  const latentStyles: Record<string, LatentStyleDefinition> = {};
+
+  for (const child of stylesElement.children) {
+    if (child.type !== "element") continue;
+    const local = localName(child.name);
+
+    if (local === "style") {
+      const styleType = child.attributes["w:type"] ?? child.attributes.type;
+      const styleId = child.attributes["w:styleId"] ?? child.attributes.styleId;
+      if (!styleId) continue;
+
+      const displayName = readStyleDisplayName(child) ?? styleId;
+      const basedOn = readLinkedStyleId(child, "basedOn");
+      const isDefault = (child.attributes["w:default"] ?? child.attributes.default) === "1";
+
+      switch (styleType) {
+        case "paragraph": {
+          const nextStyle = readLinkedStyleId(child, "next");
+          const outlineLevel = readParagraphStyleOutlineLevel(child);
+          paragraphs[styleId] = {
+            styleId,
+            displayName,
+            kind: "paragraph",
+            isDefault,
+            ...(basedOn ? { basedOn } : {}),
+            ...(nextStyle ? { nextStyle } : {}),
+            ...(outlineLevel !== undefined ? { outlineLevel } : {}),
+          };
+          break;
+        }
+        case "character": {
+          characters[styleId] = {
+            styleId,
+            displayName,
+            kind: "character",
+            isDefault,
+            ...(basedOn ? { basedOn } : {}),
+          };
+          break;
+        }
+        case "table": {
+          tables[styleId] = {
+            styleId,
+            displayName,
+            kind: "table",
+            isDefault,
+            ...(basedOn ? { basedOn } : {}),
+          };
+          break;
+        }
+        default:
+          // numbering/list styles are not part of the canonical catalog
+          break;
+      }
+    } else if (local === "latentStyles") {
+      readLatentStyles(child, latentStyles);
+    }
+  }
+
+  const hasLatent = Object.keys(latentStyles).length > 0;
+  diagnostics.push(
+    `parsed ${Object.keys(paragraphs).length} paragraph, ` +
+      `${Object.keys(characters).length} character, ` +
+      `${Object.keys(tables).length} table styles` +
+      (hasLatent ? `, ${Object.keys(latentStyles).length} latent styles` : ""),
+  );
+
+  return {
+    catalog: {
+      paragraphs,
+      characters,
+      tables,
+      ...(hasLatent ? { latentStyles } : {}),
+    },
+    fromPackage: true,
+    diagnostics,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readStyleDisplayName(styleNode: XmlElementNode): string | undefined {
+  const nameEl = findChildElementOptional(styleNode, "name");
+  if (!nameEl) return undefined;
+  return nameEl.attributes["w:val"] ?? nameEl.attributes.val ?? undefined;
+}
+
+function readLinkedStyleId(
+  styleNode: XmlElementNode,
+  elementLocalName: string,
+): string | undefined {
+  const el = findChildElementOptional(styleNode, elementLocalName);
+  if (!el) return undefined;
+  return el.attributes["w:val"] ?? el.attributes.val ?? undefined;
+}
+
+function readParagraphStyleOutlineLevel(
+  styleNode: XmlElementNode,
+): number | undefined {
+  const paragraphProperties = findChildElementOptional(styleNode, "pPr");
+  if (!paragraphProperties) {
+    return undefined;
+  }
+
+  const outlineLevel = findChildElementOptional(paragraphProperties, "outlineLvl");
+  if (!outlineLevel) {
+    return undefined;
+  }
+
+  const rawValue = outlineLevel.attributes["w:val"] ?? outlineLevel.attributes.val;
+  const parsed = rawValue !== undefined ? Number.parseInt(rawValue, 10) : Number.NaN;
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function readLatentStyles(
+  latentNode: XmlElementNode,
+  out: Record<string, LatentStyleDefinition>,
+): void {
+  for (const child of latentNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "lsdException") continue;
+
+    const name = child.attributes["w:name"] ?? child.attributes.name;
+    if (!name) continue;
+
+    const locked = readBoolAttr(child, "locked");
+    const semiHidden = readBoolAttr(child, "semiHidden");
+    const unhideWhenUsed = readBoolAttr(child, "unhideWhenUsed");
+    const qFormat = readBoolAttr(child, "qFormat");
+    const rawPriority = child.attributes["w:uiPriority"] ?? child.attributes.uiPriority;
+    const uiPriority = rawPriority !== undefined ? Number.parseInt(rawPriority, 10) : undefined;
+
+    out[name] = {
+      name,
+      ...(locked !== undefined ? { locked } : {}),
+      ...(semiHidden !== undefined ? { semiHidden } : {}),
+      ...(unhideWhenUsed !== undefined ? { unhideWhenUsed } : {}),
+      ...(qFormat !== undefined ? { qFormat } : {}),
+      ...(uiPriority !== undefined && !Number.isNaN(uiPriority) ? { uiPriority } : {}),
+    };
+  }
+}
+
+function readBoolAttr(node: XmlElementNode, attrLocalName: string): boolean | undefined {
+  const val = node.attributes[`w:${attrLocalName}`] ?? node.attributes[attrLocalName];
+  if (val === undefined) return undefined;
+  return val === "1" || val === "true";
+}
+
+// ---------------------------------------------------------------------------
+// Inline XML parser (same implementation as parse-numbering.ts)
+// ---------------------------------------------------------------------------
+
+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 separatorIndex = name.indexOf(":");
+  return separatorIndex >= 0 ? name.slice(separatorIndex + 1) : name;
+}
+
+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.length > 0) {
+        stack[stack.length - 1]?.children.push({
+          type: "text",
+          text,
+        });
+      }
+      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}>.`);
+      }
+
+      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;
+  }
+
+  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;
+    }
+    const rawValue = tagBody.slice(valueStart, cursor);
+    attributes[key] = decodeXmlEntities(rawValue);
+    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 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 >.");
+}
+
+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;
+    }
+  });
+}

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

@@ -2,6 +2,7 @@ import type {
   ThemeColorScheme,
   ThemeDefinition,
   ThemeFontScheme,
+  ResolvedTheme,
 } from "../../model/canonical-document.ts";
 
 // ---- XML node types (inline, no external dep) ----
@@ -85,6 +86,37 @@ export function parseThemeXml(xml: string): ThemeDefinition {
   return result;
 }
 
+/**
+ * Resolve a ThemeDefinition into flattened runtime theme inputs.
+ * Maps OOXML theme slot names to CSS-usable color values and font families.
+ */
+export function resolveTheme(theme: ThemeDefinition): ResolvedTheme {
+  const colors: Record<string, string> = {};
+
+  if (theme.colorScheme?.colors) {
+    for (const [slot, value] of Object.entries(theme.colorScheme.colors)) {
+      colors[slot] = value;
+    }
+  }
+
+  return {
+    colors,
+    majorFont: theme.fontScheme?.majorFont,
+    minorFont: theme.fontScheme?.minorFont,
+  };
+}
+
+/**
+ * Resolve a theme color reference (e.g. "accent1", "dk1") to a CSS color string.
+ * Returns undefined if the theme does not contain the requested slot.
+ */
+export function resolveThemeColor(
+  theme: ResolvedTheme | undefined,
+  colorSlot: string,
+): string | undefined {
+  return theme?.colors[colorSlot];
+}
+
 // ---- Internal helpers ----
 
 function parseColorScheme(

package/src/legal/bookmarks.ts

@@ -4,6 +4,8 @@ import type {
   BookmarkStartNode,
   CanonicalDocument,
   DocumentNode,
+  FieldRegistry,
+  FieldRegistryEntry,
 } from "../model/canonical-document.ts";
 
 export interface LegalBookmark {
@@ -210,6 +212,48 @@ function compareBookmarks(left: LegalBookmark, right: LegalBookmark): number {
   );
 }
 
+/**
+ * Build a lookup map from bookmark name to bookmarkId for the document.
+ * Used by the field refresh runtime to resolve REF/PAGEREF/NOTEREF targets.
+ */
+export function buildBookmarkNameMap(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): Map<string, { bookmarkId: string; paragraphIndex: number }> {
+  const root = "content" in document ? document.content : document;
+  const map = new Map<string, { bookmarkId: string; paragraphIndex: number }>();
+  let paragraphIndex = -1;
+
+  walkDocument(root, (node) => {
+    if (node.type === "paragraph") {
+      paragraphIndex += 1;
+    }
+    if (node.type === "bookmark_start" && node.name) {
+      map.set(node.name, { bookmarkId: node.bookmarkId, paragraphIndex });
+    }
+  });
+
+  return map;
+}
+
+/**
+ * Resolve field-to-bookmark dependencies from a field registry.
+ * Returns a map of bookmark names to the field entries that reference them.
+ * This enables the runtime to determine which fields need refresh when
+ * a bookmark's content changes.
+ */
+export function resolveBookmarkFieldDependencies(
+  registry: FieldRegistry,
+): Map<string, FieldRegistryEntry[]> {
+  const deps = new Map<string, FieldRegistryEntry[]>();
+  for (const entry of registry.supported) {
+    if (!entry.fieldTarget) continue;
+    const existing = deps.get(entry.fieldTarget) ?? [];
+    existing.push(entry);
+    deps.set(entry.fieldTarget, existing);
+  }
+  return deps;
+}
+
 function walkDocument(node: DocumentNode, visit: (node: DocumentNode) => void): void {
   visit(node);
 

package/src/legal/cross-references.ts

@@ -7,8 +7,10 @@ import type {
   CanonicalDocument,
   DocumentNode,
   FieldNode,
+  FieldRegistry,
   HyperlinkNode,
   ParagraphNode,
+  TocEntry,
 } from "../model/canonical-document.ts";
 
 export interface CrossReferencePattern {
@@ -33,6 +35,40 @@ interface FieldReference {
   instruction: string;
 }
 
+/**
+ * Collect field references from a canonical document, leveraging the
+ * field family classification when available.
+ */
+export function collectFieldReferencesFromCanonicalDocument(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): Array<{ family: string; target: string; instruction: string; paragraphIndex: number; displayText: string }> {
+  const root = "content" in document ? document.content : document;
+  const results: Array<{ family: string; target: string; instruction: string; paragraphIndex: number; displayText: string }> = [];
+  let paragraphIndex = -1;
+
+  walkDocument(root, (node) => {
+    if (node.type === "paragraph") {
+      paragraphIndex += 1;
+      for (const child of node.children) {
+        if (child.type === "field" && child.fieldFamily && child.fieldTarget) {
+          const family = child.fieldFamily;
+          if (family === "REF" || family === "PAGEREF" || family === "NOTEREF") {
+            results.push({
+              family,
+              target: child.fieldTarget,
+              instruction: child.instruction,
+              paragraphIndex,
+              displayText: flattenInlineText(child.children).trim(),
+            });
+          }
+        }
+      }
+    }
+  });
+
+  return results;
+}
+
 const CROSS_REFERENCE_PATTERN =
   /\b(Section|Clause|Article|Schedule|Exhibit|Appendix)\s+(\d+(?:\.\d+)*|[A-Z]-\d+|[A-Z])(?=[^A-Za-z0-9]|$)/g;
 const W_REF_PATTERN = /<w:ref\b([^>]*)\/?>/g;
@@ -281,7 +317,7 @@ function flattenParagraphText(paragraph: ParagraphNode): string {
         case "hyperlink":
           return flattenInlineText(child.children);
         case "field":
-          return flattenInlineText(child.children);
+          return child.children ? flattenInlineText(child.children) : "";
         case "tab":
           return "\t";
         case "hard_break":
@@ -335,6 +371,28 @@ function dedupeCrossReferences(references: CrossReference[]): CrossReference[] {
   return deduped;
 }
 
+/**
+ * Collect TOC entries from a field registry's tocStructure.
+ * Returns the entries in document order with their heading text and levels.
+ * Returns an empty array if no TOC structure is available.
+ */
+export function collectTocEntriesFromRegistry(
+  registry: FieldRegistry | undefined,
+): TocEntry[] {
+  return registry?.tocStructure?.entries ?? [];
+}
+
+/**
+ * Assess whether the TOC structure in a field registry is current
+ * with respect to the document's heading structure.
+ */
+export function assessTocFreshness(
+  registry: FieldRegistry | undefined,
+): "current" | "stale" | "absent" {
+  if (!registry?.tocStructure) return "absent";
+  return registry.tocStructure.status;
+}
+
 function walkDocument(node: DocumentNode, visit: (node: DocumentNode) => void): void {
   visit(node);