@beyondwork/docx-react-component 1.0.18 → 1.0.20

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

@@ -65,6 +65,8 @@ export interface CommentImportDiagnostic {
     | "preserve_only_revision_overlap";
   message: string;
   featureClass: "preserve-only";
+  detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
+  actionabilityNote?: string;
 }
 
 export interface ParsedCommentsResult {
@@ -143,8 +145,10 @@ export function parseCommentsFromOoxml(
       diagnostics.push({
         commentId: rootCommentId,
         code: "missing_anchor_reference",
-        message: "Comment anchor markers are incomplete and remain preserve-only.",
+        message: "Comment anchor markers are incomplete (missing start, end, or reference). Thread is visible but detached and not actionable.",
         featureClass: "preserve-only",
+        detachedReason: "incomplete-markers",
+        actionabilityNote: "Re-anchoring requires the host to supply a valid range. The comment body and thread are preserved for display.",
       });
       threads.push(
         createImportedCommentThread({
@@ -171,8 +175,10 @@ export function parseCommentsFromOoxml(
         commentId: rootCommentId,
         code: "multi_paragraph_anchor_preserve_only",
         message:
-          "Comment anchor spans multiple paragraphs and remains preserve-only for Wave 5.",
+          "Comment anchor spans multiple paragraphs. Thread is visible but detached; cross-paragraph anchoring is not yet supported for live editing.",
         featureClass: "preserve-only",
+        detachedReason: "multi-paragraph",
+        actionabilityNote: "The comment thread and body are preserved. Operators see the thread in the sidebar but cannot navigate to an inline highlight.",
       });
       threads.push(
         createImportedCommentThread({
@@ -470,32 +476,92 @@ function parseCommentAnchors(documentXml: string): Map<string, CommentAnchorBoun
   const documentElement = findChildElement(root, "document");
   const bodyElement = findChildElement(documentElement, "body");
   const anchors = new Map<string, CommentAnchorBounds>();
-  let cursor = 0;
-  let paragraphIndex = -1;
-  let previousWasParagraph = false;
+  walkCommentAnchorBlocks(bodyElement.children, anchors, 0, -1, true);
 
-  for (const child of bodyElement.children) {
-    if (child.type !== "element") {
+  return anchors;
+}
+
+function walkCommentAnchorBlocks(
+  nodes: readonly XmlNode[],
+  anchors: Map<string, CommentAnchorBounds>,
+  cursor: number,
+  paragraphIndex: number,
+  useSurfaceParagraphSeparators: boolean,
+): {
+  cursor: number;
+  paragraphIndex: number;
+} {
+  let nextCursor = cursor;
+  let nextParagraphIndex = paragraphIndex;
+  let elementIndex = -1;
+
+  for (const node of nodes) {
+    if (node.type !== "element") {
       continue;
     }
+    elementIndex += 1;
 
-    if (localName(child.name) !== "p") {
-      cursor += 1;
-      previousWasParagraph = false;
+    const name = localName(node.name);
+    if (name === "p") {
+      if (useSurfaceParagraphSeparators && elementIndex > 0) {
+        nextCursor += 1;
+      }
+      nextParagraphIndex += 1;
+      walkParagraph(node, nextParagraphIndex, anchors, () => nextCursor, (next) => {
+        nextCursor = next;
+      });
       continue;
     }
 
-    if (previousWasParagraph) {
-      cursor += 1;
+    if (name === "tbl") {
+      for (const child of node.children) {
+        if (child.type !== "element" || localName(child.name) !== "tr") {
+          continue;
+        }
+        for (const rowChild of child.children) {
+          if (rowChild.type !== "element" || localName(rowChild.name) !== "tc") {
+            continue;
+          }
+          const result = walkCommentAnchorBlocks(
+            rowChild.children,
+            anchors,
+            nextCursor,
+            nextParagraphIndex,
+            false,
+          );
+          nextCursor = result.cursor;
+          nextParagraphIndex = result.paragraphIndex;
+        }
+      }
+      continue;
     }
-    paragraphIndex += 1;
-    walkParagraph(child, paragraphIndex, anchors, () => cursor, (next) => {
-      cursor = next;
-    });
-    previousWasParagraph = true;
+
+    if (name === "sdt") {
+      const sdtContent = findChildElement(node, "sdtContent");
+      const result = walkCommentAnchorBlocks(
+        sdtContent.children,
+        anchors,
+        nextCursor,
+        nextParagraphIndex,
+        false,
+      );
+      nextCursor = result.cursor;
+      nextParagraphIndex = result.paragraphIndex;
+      continue;
+    }
+
+    if (name === "customXml") {
+      nextCursor += 1;
+      continue;
+    }
+
+    nextCursor += 0;
   }
 
-  return anchors;
+  return {
+    cursor: nextCursor,
+    paragraphIndex: nextParagraphIndex,
+  };
 }
 
 function walkParagraph(
@@ -554,7 +620,7 @@ function walkInlineNode(
         .filter((child): child is XmlTextNode => child.type === "text")
         .map((child) => child.text)
         .join("");
-      setCursor(getCursor() + text.length);
+      setCursor(getCursor() + Array.from(text).length);
       return;
     }
     case "tab":

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

@@ -194,6 +194,402 @@ export function parseBookmarkEnd(
   };
 }
 
+// ─── Field family classification ─────────────────────────────────────────────
+
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  FieldFamily,
+  FieldNode,
+  FieldRegistry,
+  FieldRegistryEntry,
+  FieldRefreshStatus,
+  InlineNode,
+  ParagraphNode,
+  SubPartsCatalog,
+  SupportedFieldFamily,
+  TocEntry,
+  TocStructure,
+} from "../../model/canonical-document.ts";
+
+const FIELD_FAMILY_PATTERN =
+  /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|MERGEFIELD|IF|SEQ|INDEX|TC|STYLEREF)\b/i;
+
+const SUPPORTED_FAMILIES = new Set<string>(["REF", "PAGEREF", "NOTEREF", "TOC"]);
+
+/**
+ * Classify a field instruction into its field family.
+ * Returns the family enum value and whether it is in the supported slice.
+ */
+export function classifyFieldInstruction(instruction: string): {
+  family: FieldFamily;
+  supported: boolean;
+  target?: string;
+} {
+  const trimmed = instruction.trim();
+  const match = FIELD_FAMILY_PATTERN.exec(trimmed);
+  if (!match) {
+    return { family: "UNKNOWN", supported: false };
+  }
+
+  const family = match[1].toUpperCase() as FieldFamily;
+  const supported = SUPPORTED_FAMILIES.has(family);
+
+  let target: string | undefined;
+  if (family === "REF" || family === "PAGEREF" || family === "NOTEREF") {
+    const targetMatch = /^\s*(?:REF|PAGEREF|NOTEREF)\s+(?:"([^"]+)"|(\S+))/i.exec(trimmed);
+    target = (targetMatch?.[1] ?? targetMatch?.[2])?.trim();
+  }
+
+  return { family, supported, target };
+}
+
+/**
+ * Returns true if the given field family is in the supported refresh slice.
+ */
+export function isSupportedFieldFamily(family: FieldFamily): family is SupportedFieldFamily {
+  return SUPPORTED_FAMILIES.has(family);
+}
+
+// ─── Field registry builder ─────────────────────────────────────────────────
+
+/**
+ * Build a field registry from a canonical document, cataloging every field
+ * instance with its classification, dependency metadata, and refresh status.
+ *
+ * The registry partitions fields into `supported` (REF, PAGEREF, NOTEREF, TOC)
+ * and `preserveOnly` (all others) slices.
+ */
+export function buildFieldRegistry(
+  document: Pick<CanonicalDocument, "content" | "styles"> & {
+    subParts?: SubPartsCatalog;
+  },
+): FieldRegistry {
+  const root = document.content;
+  const supported: FieldRegistryEntry[] = [];
+  const preserveOnly: FieldRegistryEntry[] = [];
+  let fieldIndex = 0;
+  let paragraphIndex = -1;
+  let tocInstruction: string | undefined;
+
+  walkFieldDocument(root, (node, pIdx) => {
+    paragraphIndex = pIdx;
+    if (node.type === "field") {
+      const classification = node.fieldFamily
+        ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget }
+        : classifyFieldInstruction(node.instruction);
+      const displayText = flattenFieldText(node.children);
+      const entry: FieldRegistryEntry = {
+        fieldIndex,
+        fieldFamily: classification.family,
+        supported: classification.supported,
+        instruction: node.instruction,
+        ...(classification.target ? { fieldTarget: classification.target } : {}),
+        displayText,
+        paragraphIndex,
+        refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+      };
+      if (classification.supported) {
+        supported.push(entry);
+        if (classification.family === "TOC" && !tocInstruction) {
+          tocInstruction = node.instruction;
+        }
+      } else {
+        preserveOnly.push(entry);
+      }
+      fieldIndex += 1;
+    }
+  });
+  if (document.subParts) {
+    walkSubPartFields(document.subParts, (node, pIdx) => {
+      paragraphIndex = pIdx;
+      if (node.type === "field") {
+        const classification = node.fieldFamily
+          ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget }
+          : classifyFieldInstruction(node.instruction);
+        const displayText = flattenFieldText(node.children);
+        const entry: FieldRegistryEntry = {
+          fieldIndex,
+          fieldFamily: classification.family,
+          supported: classification.supported,
+          instruction: node.instruction,
+          ...(classification.target ? { fieldTarget: classification.target } : {}),
+          displayText,
+          paragraphIndex,
+          refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+        };
+        if (classification.supported) {
+          supported.push(entry);
+        } else {
+          preserveOnly.push(entry);
+        }
+        fieldIndex += 1;
+      }
+    });
+  }
+
+  const tocStructure = tocInstruction
+    ? buildTocStructure(document, tocInstruction)
+    : undefined;
+
+  return {
+    supported,
+    preserveOnly,
+    ...(tocStructure ? { tocStructure } : {}),
+  };
+}
+
+/**
+ * Parse the heading level range from a TOC field instruction.
+ * The \\o switch specifies the outline level range (e.g. \\o "1-3").
+ * Defaults to 1-9 if no \\o switch is present.
+ */
+export function parseTocLevelRange(instruction: string): { from: number; to: number } {
+  const match = /\\o\s+"(\d+)-(\d+)"/.exec(instruction);
+  if (match) {
+    return { from: Number.parseInt(match[1], 10), to: Number.parseInt(match[2], 10) };
+  }
+  return { from: 1, to: 9 };
+}
+
+/**
+ * Build a TocStructure from the document's heading paragraphs and the
+ * TOC field instruction.  This produces a deterministic, package-backed
+ * TOC model that the runtime can use for refresh without DOM recomputation.
+ */
+export function buildTocStructure(
+  document: Pick<CanonicalDocument, "content" | "styles">,
+  instruction: string,
+): TocStructure {
+  const levelRange = parseTocLevelRange(instruction);
+  const entries: TocEntry[] = [];
+  let paragraphIndex = -1;
+
+  walkFieldDocument(document.content, (node, pIdx) => {
+    paragraphIndex = pIdx;
+    if (node.type !== "paragraph") return;
+    const paragraph = node as ParagraphNode;
+
+    // Determine heading level from outlineLevel or style
+    let level: number | undefined = paragraph.outlineLevel;
+    if (level === undefined && paragraph.styleId) {
+      const style = document.styles.paragraphs[paragraph.styleId];
+      if (style?.outlineLevel !== undefined) {
+        level = style.outlineLevel;
+      }
+    }
+
+    if (level === undefined) return;
+    // TOC outline levels are 0-based internally, 1-based in TOC notation
+    const tocLevel = level + 1;
+    if (tocLevel < levelRange.from || tocLevel > levelRange.to) return;
+
+    const text = flattenParagraphInlineText(paragraph.children);
+    if (text.trim().length === 0) return;
+
+    // Find bookmark anchoring this heading
+    let bookmarkName: string | undefined;
+    for (const child of paragraph.children) {
+      if (child.type === "bookmark_start" && child.name) {
+        bookmarkName = child.name;
+        break;
+      }
+    }
+
+    entries.push({
+      text: text.trim(),
+      level: tocLevel,
+      paragraphIndex,
+      ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
+      ...(bookmarkName ? { bookmarkName } : {}),
+    });
+  });
+
+  return {
+    instruction,
+    levelRange,
+    entries,
+    status: "stale",
+  };
+}
+
+/**
+ * Deterministic refresh helper for REF fields.
+ * Given a bookmark name map and the document content, resolves the display
+ * text for a REF field by extracting text from the bookmarked paragraph.
+ *
+ * Returns the resolved text, or undefined if the bookmark is not found.
+ */
+export function resolveRefFieldText(
+  document: Pick<CanonicalDocument, "content">,
+  bookmarkNameMap: Map<string, { bookmarkId: string; paragraphIndex: number }>,
+  fieldTarget: string,
+): { text: string; refreshStatus: "current" | "unresolvable" } | undefined {
+  const bookmark = bookmarkNameMap.get(fieldTarget);
+  if (!bookmark) {
+    return { text: "", refreshStatus: "unresolvable" };
+  }
+
+  // Find the paragraph at bookmarkIndex and extract its text content
+  let paragraphIndex = -1;
+  let resolvedText: string | undefined;
+
+  walkFieldDocument(document.content, (node, pIdx) => {
+    if (node.type !== "paragraph") return;
+    paragraphIndex = pIdx;
+    if (paragraphIndex === bookmark.paragraphIndex) {
+      resolvedText = flattenBookmarkContent(node as ParagraphNode, bookmark.bookmarkId);
+    }
+  });
+
+  if (resolvedText !== undefined) {
+    return { text: resolvedText, refreshStatus: "current" };
+  }
+  return { text: "", refreshStatus: "unresolvable" };
+}
+
+/**
+ * Deterministic refresh helper that updates all supported field entries
+ * in a registry with their current resolved status.
+ *
+ * This does NOT mutate the document nodes — it returns a new registry
+ * with updated refresh statuses.  A3 owns the runtime wiring that
+ * applies these to the live document.
+ */
+export function refreshFieldRegistry(
+  registry: FieldRegistry,
+  bookmarkNameMap: Map<string, { bookmarkId: string; paragraphIndex: number }>,
+): FieldRegistry {
+  const refreshed: FieldRegistryEntry[] = registry.supported.map((entry) => {
+    if (entry.fieldFamily === "TOC") {
+      // TOC refresh is handled through tocStructure, not individual entries
+      return { ...entry, refreshStatus: registry.tocStructure ? "current" : "stale" as FieldRefreshStatus };
+    }
+    if (!entry.fieldTarget) {
+      return { ...entry, refreshStatus: "unresolvable" as FieldRefreshStatus };
+    }
+    const bookmark = bookmarkNameMap.get(entry.fieldTarget);
+    if (!bookmark) {
+      return { ...entry, refreshStatus: "unresolvable" as FieldRefreshStatus };
+    }
+    return { ...entry, refreshStatus: "current" as FieldRefreshStatus };
+  });
+
+  return {
+    supported: refreshed,
+    preserveOnly: registry.preserveOnly,
+    ...(registry.tocStructure ? { tocStructure: registry.tocStructure } : {}),
+  };
+}
+
+// ─── Field registry internal helpers ────────────────────────────────────────
+
+function walkFieldDocument(
+  node: DocumentNode,
+  visit: (node: DocumentNode, paragraphIndex: number) => void,
+  paragraphIndex = -1,
+): number {
+  if (node.type === "paragraph") {
+    paragraphIndex += 1;
+  }
+  visit(node, paragraphIndex);
+
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      paragraphIndex = walkFieldDocument(child as DocumentNode, visit, paragraphIndex);
+    }
+  }
+  if (node.type === "table") {
+    for (const row of node.rows) {
+      paragraphIndex = walkFieldDocument(row, visit, paragraphIndex);
+    }
+  } else if (node.type === "table_row") {
+    for (const cell of node.cells) {
+      paragraphIndex = walkFieldDocument(cell, visit, paragraphIndex);
+    }
+  }
+  return paragraphIndex;
+}
+
+function walkSubPartFields(
+  subParts: SubPartsCatalog,
+  visit: (node: DocumentNode, paragraphIndex: number) => void,
+): void {
+  for (const header of subParts.headers) {
+    for (const block of header.blocks) {
+      walkFieldDocument(block, visit);
+    }
+  }
+  for (const footer of subParts.footers) {
+    for (const block of footer.blocks) {
+      walkFieldDocument(block, visit);
+    }
+  }
+  if (subParts.footnoteCollection) {
+    for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
+      for (const block of note.blocks) {
+        walkFieldDocument(block, visit);
+      }
+    }
+    for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
+      for (const block of note.blocks) {
+        walkFieldDocument(block, visit);
+      }
+    }
+  }
+}
+
+function flattenFieldText(children: InlineNode[]): string {
+  return children
+    .map((child) => {
+      if (child.type === "text") return child.text;
+      if (child.type === "tab") return "\t";
+      if (child.type === "hard_break" || child.type === "column_break") return "\n";
+      return "";
+    })
+    .join("");
+}
+
+function flattenParagraphInlineText(children: InlineNode[]): string {
+  return children
+    .map((child) => {
+      if (child.type === "text") return child.text;
+      if (child.type === "tab") return "\t";
+      if (child.type === "hard_break" || child.type === "column_break") return "\n";
+      if (child.type === "hyperlink") return flattenFieldText(child.children);
+      if (child.type === "field") return flattenFieldText(child.children);
+      return "";
+    })
+    .join("");
+}
+
+function flattenBookmarkContent(
+  paragraph: ParagraphNode,
+  bookmarkId: string,
+): string {
+  let inside = false;
+  const parts: string[] = [];
+  for (const child of paragraph.children) {
+    if (child.type === "bookmark_start" && child.bookmarkId === bookmarkId) {
+      inside = true;
+      continue;
+    }
+    if (child.type === "bookmark_end" && child.bookmarkId === bookmarkId) {
+      break;
+    }
+    if (inside) {
+      if (child.type === "text") parts.push(child.text);
+      else if (child.type === "tab") parts.push("\t");
+      else if (child.type === "hard_break") parts.push("\n");
+    }
+  }
+  // If no bookmark boundaries found in this paragraph, return full paragraph text
+  if (!inside) {
+    return flattenParagraphInlineText(paragraph.children);
+  }
+  return parts.join("");
+}
+
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 
 function extractComplexFieldsFromParagraph(