@beyondwork/docx-react-component 1.0.19 → 1.0.21

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

@@ -38,9 +38,14 @@ export interface RevisionImportDiagnostic {
     | "preserve_only_move_revision"
     | "preserve_only_formatting_revision"
     | "nested_revision_preserve_only"
-    | "ambiguous_revision_anchor";
+    | "shallow_nested_revision_promoted"
+    | "linked_move_pair"
+    | "unlinked_move_revision"
+    | "ambiguous_revision_anchor"
+    | "table_structural_revision_preserve_only"
+    | "table_property_revision_parsed";
   message: string;
-  featureClass: "preserve-only";
+  featureClass: "preserve-only" | "supported" | "informational";
 }
 
 export interface ParsedRevisionsResult {
@@ -69,6 +74,7 @@ interface RevisionMetadata {
 const SUPPORTED_CONTAINER_TYPES = new Set(["ins", "del"]);
 const PRESERVE_ONLY_CONTAINER_TYPES = new Set(["moveFrom", "moveTo"]);
 const PROPERTY_CHANGE_REVISION_TYPES = new Set(["rPrChange", "pPrChange"]);
+const STRUCTURAL_TABLE_REVISION_TYPES = new Set(["cellIns", "cellDel", "cellMerge"]);
 
 export function parseRevisionsFromDocumentXml(
   documentXml: string,
@@ -124,6 +130,8 @@ export function parseRevisionsFromDocumentXml(
     previousWasParagraph = true;
   }
 
+  linkMoveRevisionPairs(state);
+
   return {
     revisions: state.revisions,
     preservedMarkup: state.preservedMarkup.sort((left, right) => left.xmlStart - right.xmlStart),
@@ -284,6 +292,46 @@ function walkContentNode(
 
     if (hasNestedRevision) {
       const nestedKind = type === "ins" ? "insertion" : type === "del" ? "deletion" : "move";
+      const isShallowNesting = isShallowPropertyChangeNesting(node);
+
+      if (isShallowNesting && SUPPORTED_CONTAINER_TYPES.has(type)) {
+        state.revisions.push(
+          createRevisionRecord({
+            revisionId: metadata.revisionId,
+            kind: nestedKind as "insertion" | "deletion",
+            anchor:
+              length > 0
+                ? createRevisionRangeAnchor(start, end)
+                : createDetachedAnchor({ from: start, to: end }, "importAmbiguity"),
+            authorId: metadata.authorId,
+            createdAt: metadata.createdAt,
+            metadata: {
+              source: "import",
+              importedRevisionForm:
+                type === "ins" ? "run-insertion" : "run-deletion",
+              originalRevisionType: type,
+              ooxmlRevisionId: metadata.ooxmlRevisionId,
+            },
+          }),
+        );
+        state.preservedMarkup.push({
+          revisionId: metadata.revisionId,
+          rawXml: state.documentXml.slice(node.start, node.end),
+          xmlStart: node.start,
+          xmlEnd: node.end,
+          originalRevisionType: type,
+        });
+        state.diagnostics.push({
+          revisionId: metadata.revisionId,
+          code: "shallow_nested_revision_promoted",
+          message: "Shallow nested revision (property changes inside ins/del) promoted to supported rendering.",
+          featureClass: "supported",
+        });
+        parseNestedPropertyChangeRevisions(node, paragraphIndex, state, start);
+        advanceCursor(node, setCursor, getCursor);
+        return;
+      }
+
       state.revisions.push(
         createRevisionRecord({
           revisionId: metadata.revisionId,
@@ -353,7 +401,7 @@ function walkContentNode(
       state.diagnostics.push({
         revisionId: metadata.revisionId,
         code: "preserve_only_move_revision",
-        message: "Tracked move revisions are preserve-only. Content is preserved for round-trip but cannot be accepted or rejected.",
+        message: "Move revision parsed as preserve-only. Content is preserved for round-trip; linking resolved in post-parse step.",
         featureClass: "preserve-only",
       });
       advanceCursor(node, setCursor, getCursor);
@@ -475,45 +523,169 @@ function parseTblPropertyRevisions(
   state: ParseState,
 ): void {
   const tblPr = findChildElement(table, "tblPr");
-  if (!tblPr) {
-    return;
-  }
+  if (tblPr) {
+    const tblPrChange = findChildElement(tblPr, "tblPrChange");
+    if (tblPrChange) {
+      const metadata = readRevisionMetadata(tblPrChange, state, "property-change");
+      const innerTblPr = findChildElement(tblPrChange, "tblPr");
+      const beforeXml = innerTblPr ? state.documentXml.slice(innerTblPr.start, innerTblPr.end) : "";
+      const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
 
-  const tblPrChange = findChildElement(tblPr, "tblPrChange");
-  if (!tblPrChange) {
-    return;
+      state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: "property-change",
+          anchor: createRevisionRangeAnchor(position, position),
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            originalRevisionType: "tblPrChange",
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+            propertyChangeData,
+          },
+        }),
+      );
+      state.preservedMarkup.push({
+        revisionId: metadata.revisionId,
+        rawXml: state.documentXml.slice(tblPrChange.start, tblPrChange.end),
+        xmlStart: tblPrChange.start,
+        xmlEnd: tblPrChange.end,
+        originalRevisionType: "tblPrChange",
+        containerXmlStart: tblPr.start,
+        containerXmlEnd: tblPr.end,
+        beforeContainerXml: beforeXml,
+      });
+      state.diagnostics.push({
+        revisionId: metadata.revisionId,
+        code: "table_property_revision_parsed",
+        message: "Table property change (tblPrChange) parsed as actionable property-change revision.",
+        featureClass: "supported",
+      });
+    }
   }
 
-  const metadata = readRevisionMetadata(tblPrChange, state, "property-change");
-  const innerTblPr = findChildElement(tblPrChange, "tblPr");
-  const beforeXml = innerTblPr ? state.documentXml.slice(innerTblPr.start, innerTblPr.end) : "";
-  const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
+  parseTableRowAndCellRevisions(table, position, state);
+}
 
-  state.revisions.push(
-    createRevisionRecord({
-      revisionId: metadata.revisionId,
-      kind: "property-change",
-      anchor: createRevisionRangeAnchor(position, position),
-      authorId: metadata.authorId,
-      createdAt: metadata.createdAt,
-      metadata: {
-        source: "import",
-        originalRevisionType: "tblPrChange",
-        ooxmlRevisionId: metadata.ooxmlRevisionId,
-        propertyChangeData,
-      },
-    }),
-  );
-  state.preservedMarkup.push({
-    revisionId: metadata.revisionId,
-    rawXml: state.documentXml.slice(tblPrChange.start, tblPrChange.end),
-    xmlStart: tblPrChange.start,
-    xmlEnd: tblPrChange.end,
-    originalRevisionType: "tblPrChange",
-    containerXmlStart: tblPr.start,
-    containerXmlEnd: tblPr.end,
-    beforeContainerXml: beforeXml,
-  });
+function parseTableRowAndCellRevisions(
+  table: XmlElementNode,
+  position: number,
+  state: ParseState,
+): void {
+  for (const child of table.children) {
+    if (child.type !== "element" || localName(child.name) !== "tr") {
+      continue;
+    }
+
+    const trPr = findChildElement(child, "trPr");
+    if (trPr) {
+      const trPrChange = findChildElement(trPr, "trPrChange");
+      if (trPrChange) {
+        const metadata = readRevisionMetadata(trPrChange, state, "property-change");
+        const innerTrPr = findChildElement(trPrChange, "trPr");
+        const beforeXml = innerTrPr ? state.documentXml.slice(innerTrPr.start, innerTrPr.end) : "";
+        const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
+
+        state.revisions.push(
+          createRevisionRecord({
+            revisionId: metadata.revisionId,
+            kind: "property-change",
+            anchor: createRevisionRangeAnchor(position, position),
+            authorId: metadata.authorId,
+            createdAt: metadata.createdAt,
+            metadata: {
+              source: "import",
+              originalRevisionType: "trPrChange",
+              ooxmlRevisionId: metadata.ooxmlRevisionId,
+              propertyChangeData,
+              preserveOnlyReason: "Row property changes remain preserve-only for export safety.",
+            },
+          }),
+        );
+        state.preservedMarkup.push({
+          revisionId: metadata.revisionId,
+          rawXml: state.documentXml.slice(trPrChange.start, trPrChange.end),
+          xmlStart: trPrChange.start,
+          xmlEnd: trPrChange.end,
+          originalRevisionType: "trPrChange",
+          containerXmlStart: trPr.start,
+          containerXmlEnd: trPr.end,
+          beforeContainerXml: beforeXml,
+        });
+      }
+    }
+
+    for (const tcNode of child.children) {
+      if (tcNode.type !== "element" || localName(tcNode.name) !== "tc") {
+        continue;
+      }
+
+      const tcPr = findChildElement(tcNode, "tcPr");
+      if (!tcPr) {
+        continue;
+      }
+
+      const tcPrChange = findChildElement(tcPr, "tcPrChange");
+      if (tcPrChange) {
+        const metadata = readRevisionMetadata(tcPrChange, state, "property-change");
+        const innerTcPr = findChildElement(tcPrChange, "tcPr");
+        const beforeXml = innerTcPr ? state.documentXml.slice(innerTcPr.start, innerTcPr.end) : "";
+        const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
+
+        state.revisions.push(
+          createRevisionRecord({
+            revisionId: metadata.revisionId,
+            kind: "property-change",
+            anchor: createRevisionRangeAnchor(position, position),
+            authorId: metadata.authorId,
+            createdAt: metadata.createdAt,
+            metadata: {
+              source: "import",
+              originalRevisionType: "tcPrChange",
+              ooxmlRevisionId: metadata.ooxmlRevisionId,
+              propertyChangeData,
+              preserveOnlyReason: "Cell property changes remain preserve-only for export safety.",
+            },
+          }),
+        );
+        state.preservedMarkup.push({
+          revisionId: metadata.revisionId,
+          rawXml: state.documentXml.slice(tcPrChange.start, tcPrChange.end),
+          xmlStart: tcPrChange.start,
+          xmlEnd: tcPrChange.end,
+          originalRevisionType: "tcPrChange",
+          containerXmlStart: tcPr.start,
+          containerXmlEnd: tcPr.end,
+          beforeContainerXml: beforeXml,
+        });
+      }
+
+      for (const tcChild of tcPr.children) {
+        if (tcChild.type !== "element") {
+          continue;
+        }
+
+        const tcChildName = localName(tcChild.name);
+        if (STRUCTURAL_TABLE_REVISION_TYPES.has(tcChildName)) {
+          const metadata = readRevisionMetadata(tcChild, state, tcChildName);
+          state.preservedMarkup.push({
+            revisionId: metadata.revisionId,
+            rawXml: state.documentXml.slice(tcChild.start, tcChild.end),
+            xmlStart: tcChild.start,
+            xmlEnd: tcChild.end,
+            originalRevisionType: tcChildName,
+          });
+          state.diagnostics.push({
+            revisionId: metadata.revisionId,
+            code: "table_structural_revision_preserve_only",
+            message: `Structural table revision (${tcChildName}) remains preserve-only; topology-altering changes cannot be safely applied.`,
+            featureClass: "preserve-only",
+          });
+        }
+      }
+    }
+  }
 }
 
 function parseSectPrRevisions(
@@ -604,6 +776,113 @@ function sanitizeRevisionToken(value: string): string {
   return sanitized.length > 0 ? sanitized : "unknown";
 }
 
+function linkMoveRevisionPairs(state: ParseState): void {
+  const moveRevisions = state.revisions.filter(
+    (r) => r.kind === "move" && r.metadata.moveData,
+  );
+
+  const byMoveId = new Map<string, typeof moveRevisions>();
+  for (const revision of moveRevisions) {
+    const moveId = revision.metadata.moveData!.moveId;
+    const group = byMoveId.get(moveId) ?? [];
+    group.push(revision);
+    byMoveId.set(moveId, group);
+  }
+
+  for (const [moveId, group] of byMoveId) {
+    const fromRevision = group.find(
+      (r) => r.metadata.moveData!.direction === "from",
+    );
+    const toRevision = group.find(
+      (r) => r.metadata.moveData!.direction === "to",
+    );
+
+    if (fromRevision && toRevision) {
+      fromRevision.metadata.moveData!.linkedRevisionId = toRevision.revisionId;
+      toRevision.metadata.moveData!.linkedRevisionId = fromRevision.revisionId;
+
+      state.diagnostics.push({
+        revisionId: fromRevision.revisionId,
+        code: "linked_move_pair",
+        message: `Move-from revision linked to move-to revision ${toRevision.revisionId} via moveId ${moveId}.`,
+        featureClass: "informational",
+      });
+      state.diagnostics.push({
+        revisionId: toRevision.revisionId,
+        code: "linked_move_pair",
+        message: `Move-to revision linked to move-from revision ${fromRevision.revisionId} via moveId ${moveId}.`,
+        featureClass: "informational",
+      });
+    } else {
+      for (const revision of group) {
+        state.diagnostics.push({
+          revisionId: revision.revisionId,
+          code: "unlinked_move_revision",
+          message: `Move revision has no matching counterpart for moveId ${moveId}. Remains preserve-only.`,
+          featureClass: "preserve-only",
+        });
+      }
+    }
+  }
+}
+
+function isShallowPropertyChangeNesting(node: XmlElementNode): boolean {
+  for (const child of node.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (SUPPORTED_CONTAINER_TYPES.has(name) || PRESERVE_ONLY_CONTAINER_TYPES.has(name)) {
+      return false;
+    }
+
+    if (name === "r") {
+      const runProperties = findChildElement(child, "rPr");
+      if (runProperties) {
+        for (const rpChild of runProperties.children) {
+          if (rpChild.type !== "element") {
+            continue;
+          }
+
+          const rpChildName = localName(rpChild.name);
+          if (
+            SUPPORTED_CONTAINER_TYPES.has(rpChildName) ||
+            PRESERVE_ONLY_CONTAINER_TYPES.has(rpChildName)
+          ) {
+            return false;
+          }
+        }
+      }
+      continue;
+    }
+
+    if (!isShallowPropertyChangeNesting(child)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function parseNestedPropertyChangeRevisions(
+  container: XmlElementNode,
+  paragraphIndex: number,
+  state: ParseState,
+  containerStart: number,
+): void {
+  for (const child of container.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    if (localName(child.name) === "r") {
+      parseRunFormattingRevisions(child, paragraphIndex, state, containerStart);
+    }
+  }
+}
+
 function containsNestedRevision(node: XmlElementNode): boolean {
   return node.children.some(
     (child) =>

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);