@beyondwork/docx-react-component 1.0.19 → 1.0.21

package/src/io/export/split-review-boundaries.ts

@@ -18,25 +18,9 @@ export function splitDocumentAtReviewBoundaries(
     return content;
   }
 
-  let cursor = 0;
-  const children = content.children.map((block, index) => {
-    if (index > 0 && content.children[index - 1]?.type === "paragraph" && block.type === "paragraph") {
-      cursor += 1;
-    }
-
-    if (block.type !== "paragraph") {
-      cursor += 1;
-      return block;
-    }
-
-    const next = splitParagraph(block, splitPositions, cursor);
-    cursor = next.cursor;
-    return next.paragraph;
-  });
-
   return {
     type: "doc",
-    children,
+    children: splitBlockNodes(content.children, splitPositions, 0, true).children,
   };
 }
 
@@ -98,7 +82,7 @@ function splitParagraph(
     }
 
     children.push(child);
-    nextCursor += 1;
+    nextCursor += measureInlineNodeForReviewBoundaries(child);
   }
 
   return {
@@ -110,6 +94,147 @@ function splitParagraph(
   };
 }
 
+function splitBlockNodes(
+  blocks: readonly DocumentRootNode["children"][number][],
+  splitPositions: ReadonlySet<number>,
+  cursor: number,
+  useSurfaceParagraphSeparators: boolean,
+): {
+  children: DocumentRootNode["children"];
+  cursor: number;
+} {
+  const children: DocumentRootNode["children"] = [];
+  let nextCursor = cursor;
+  for (const [index, block] of blocks.entries()) {
+    if (block.type === "paragraph") {
+      if (useSurfaceParagraphSeparators && index > 0) {
+        nextCursor += 1;
+      }
+      const next = splitParagraph(block, splitPositions, nextCursor);
+      children.push(next.paragraph);
+      nextCursor = next.cursor;
+      continue;
+    }
+
+    if (block.type === "table") {
+      const next = splitTableAtReviewBoundaries(block, splitPositions, nextCursor);
+      children.push(next.table);
+      nextCursor = next.cursor;
+      continue;
+    }
+
+    if (block.type === "sdt") {
+      const next = splitBlockNodes(block.children, splitPositions, nextCursor, false);
+      children.push({
+        ...block,
+        children: next.children,
+      });
+      nextCursor = next.cursor;
+      continue;
+    }
+
+    if (block.type === "custom_xml") {
+      children.push(block);
+      nextCursor += 1;
+      continue;
+    }
+
+    children.push(block);
+    nextCursor += 1;
+  }
+
+  return {
+    children,
+    cursor: nextCursor,
+  };
+}
+
+function splitTableAtReviewBoundaries(
+  table: Extract<DocumentRootNode["children"][number], { type: "table" }>,
+  splitPositions: ReadonlySet<number>,
+  cursor: number,
+): {
+  table: Extract<DocumentRootNode["children"][number], { type: "table" }>;
+  cursor: number;
+} {
+  let nextCursor = cursor;
+  const rows = table.rows.map((row) => ({
+    ...row,
+    cells: row.cells.map((cell) => {
+      const next = splitBlockNodes(cell.children, splitPositions, nextCursor, false);
+      nextCursor = next.cursor;
+      return {
+        ...cell,
+        children: next.children,
+      };
+    }),
+  }));
+
+  return {
+    table: {
+      ...table,
+      rows,
+    },
+    cursor: nextCursor,
+  };
+}
+
+function advanceCursorThroughTable(
+  table: Extract<DocumentRootNode["children"][number], { type: "table" }>,
+  cursor: number,
+): number {
+  let nextCursor = cursor;
+  for (const row of table.rows) {
+    for (const cell of row.cells) {
+      nextCursor = measureBlockNodesForReviewBoundaries(cell.children, nextCursor, false);
+    }
+  }
+  return nextCursor;
+}
+
+function measureBlockNodesForReviewBoundaries(
+  blocks: readonly DocumentRootNode["children"][number][],
+  cursor: number,
+  useSurfaceParagraphSeparators: boolean,
+): number {
+  let nextCursor = cursor;
+  for (const [index, block] of blocks.entries()) {
+    if (block.type === "paragraph") {
+      if (useSurfaceParagraphSeparators && index > 0) {
+        nextCursor += 1;
+      }
+      nextCursor += block.children.reduce(
+        (size, child) => size + measureInlineNodeForReviewBoundaries(child),
+        0,
+      );
+      continue;
+    }
+
+    if (block.type === "table") {
+      nextCursor = advanceCursorThroughTable(block, nextCursor);
+      continue;
+    }
+
+    if (block.type === "sdt") {
+      nextCursor = measureBlockNodesForReviewBoundaries(
+        block.children,
+        nextCursor,
+        false,
+      );
+      continue;
+    }
+
+    if (block.type === "custom_xml") {
+      nextCursor += 1;
+      continue;
+    }
+
+    nextCursor += 1;
+  }
+
+  return nextCursor;
+}
+
 function splitHyperlinkNode(
   node: HyperlinkNode,
   splitPositions: ReadonlySet<number>,
@@ -132,7 +257,7 @@ function splitHyperlinkNode(
     }
 
     groups[groups.length - 1]?.push(child);
-    nextCursor += 1;
+    nextCursor += measureInlineNodeForReviewBoundaries(child);
     if (splitPositions.has(nextCursor)) {
       groups.push([]);
     }
@@ -192,3 +317,40 @@ function splitTextNode(
     cursor: cursor + codepoints.length,
   };
 }
+
+function measureInlineNodeForReviewBoundaries(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "bookmark_start":
+    case "bookmark_end":
+      return 0;
+    case "hyperlink":
+      return node.children.reduce(
+        (size, child) => size + measureInlineNodeForReviewBoundaries(child),
+        0,
+      );
+    case "field": {
+      const childWidth = node.children.reduce(
+        (size, child) => size + measureInlineNodeForReviewBoundaries(child),
+        0,
+      );
+      return childWidth > 0 ? childWidth : 1;
+    }
+    case "tab":
+    case "hard_break":
+    case "column_break":
+    case "footnote_ref":
+    case "image":
+    case "opaque_inline":
+    case "chart_preview":
+    case "smartart_preview":
+    case "shape":
+    case "wordart":
+    case "vml_shape":
+    case "symbol":
+      return 1;
+    default:
+      return 1;
+  }
+}

package/src/io/normalize/normalize-text.ts

@@ -4,6 +4,7 @@ import type {
   CustomXmlNode,
   DiagnosticStore,
   DocumentRootNode,
+  FieldRegistry,
   InlineNode,
   MediaCatalog,
   OpaqueBlockNode,
@@ -34,6 +35,7 @@ import type {
   ParsedTableCellNode,
   ParsedTableRowNode,
 } from "../ooxml/parse-main-document.ts";
+import { classifyFieldInstruction, buildFieldRegistry } from "../ooxml/parse-fields.ts";
 
 export interface NormalizedTextDocument {
   content: DocumentRootNode;
@@ -41,6 +43,8 @@ export interface NormalizedTextDocument {
   preservation: PreservationStore;
   diagnostics: DiagnosticStore;
   finalSectionProperties?: ParsedMainDocument["finalSectionProperties"];
+  /** Package-backed field registry built during normalization. */
+  fieldRegistry?: FieldRegistry;
 }
 
 interface NormalizationState {
@@ -56,6 +60,7 @@ interface NormalizationState {
 export function normalizeParsedTextDocument(
   document: ParsedMainDocument,
   packagePartName = "/word/document.xml",
+  options?: { styles?: import("../../model/canonical-document.ts").StylesCatalog },
 ): NormalizedTextDocument {
   const state: NormalizationState = {
     nextFragmentIndex: 1,
@@ -89,17 +94,24 @@ export function normalizeParsedTextDocument(
     }
   }
 
+  const content: DocumentRootNode = { type: "doc", children };
+
+  // Build the field registry from normalized content.
+  // When styles are available, the registry includes full TOC heading resolution.
+  // Without styles, it still catalogs all field instances for the supported/preserve-only partition.
+  const styles = options?.styles ?? { paragraphs: {}, characters: {}, tables: {} };
+  const fieldRegistry = buildFieldRegistry({ content, styles });
+  const hasFields = fieldRegistry.supported.length > 0 || fieldRegistry.preserveOnly.length > 0;
+
   return {
-    content: {
-      type: "doc",
-      children,
-    },
+    content,
     media: state.media,
     preservation: state.preservation,
     diagnostics: state.diagnostics,
     ...(document.finalSectionProperties !== undefined
       ? { finalSectionProperties: document.finalSectionProperties }
       : {}),
+    ...(hasFields ? { fieldRegistry } : {}),
   };
 }
 
@@ -158,6 +170,9 @@ function normalizeParagraph(
     ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
     ...(paragraph.alignment ? { alignment: paragraph.alignment } : {}),
     ...(paragraph.spacing ? { spacing: paragraph.spacing } : {}),
+    ...(paragraph.contextualSpacing !== undefined
+      ? { contextualSpacing: paragraph.contextualSpacing }
+      : {}),
     ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
     ...(paragraph.tabStops && paragraph.tabStops.length > 0 ? { tabStops: paragraph.tabStops } : {}),
     ...(paragraph.keepNext ? { keepNext: paragraph.keepNext } : {}),
@@ -397,15 +412,33 @@ function normalizeInlineChildren(
           bookmarkId: node.bookmarkId,
         });
         break;
-      case "field":
+      case "footnote_ref":
+        normalized.push({
+          type: "footnote_ref",
+          noteId: node.noteId,
+          noteKind: node.noteKind,
+        });
+        state.cursor += 1;
+        break;
+      case "field": {
+        const classification = classifyFieldInstruction(node.instruction);
+        const cursorBeforeField = state.cursor;
+        const fieldChildren = node.children
+          ? normalizeInlineChildren(node.children, state, packagePartName)
+          : normalizeFieldContentXml(node.contentXml ?? "");
+        state.cursor = cursorBeforeField;
         normalized.push({
           type: "field",
           fieldType: node.fieldType,
           instruction: node.instruction,
-          children: [],
+          children: fieldChildren,
+          fieldFamily: classification.family,
+          ...(classification.target ? { fieldTarget: classification.target } : {}),
+          refreshStatus: classification.supported ? "stale" : "preserve-only",
         });
-        state.cursor += 1;
+        state.cursor += fieldChildren.length > 0 ? fieldChildren.length : 1;
         break;
+      }
     }
   }
 
@@ -416,7 +449,8 @@ function normalizeImageNode(
   node: ParsedImageNode,
   state: NormalizationState,
 ): InlineNode {
-  if (!state.media.items[node.mediaId]) {
+  const existingMediaItem = state.media.items[node.mediaId];
+  if (!existingMediaItem) {
     const packagePartName =
       typeof node.packagePartName === "string" && node.packagePartName.length > 0
         ? node.packagePartName
@@ -432,6 +466,17 @@ function normalizeImageNode(
       packagePartName,
       ...(node.relationshipId ? { relationshipId: node.relationshipId } : {}),
       ...(node.altText ? { altText: node.altText } : {}),
+      ...(node.widthEmu !== undefined ? { widthEmu: node.widthEmu } : {}),
+      ...(node.heightEmu !== undefined ? { heightEmu: node.heightEmu } : {}),
+    };
+  } else if (
+    node.widthEmu !== undefined ||
+    node.heightEmu !== undefined
+  ) {
+    state.media.items[node.mediaId] = {
+      ...existingMediaItem,
+      ...(node.widthEmu !== undefined ? { widthEmu: node.widthEmu } : {}),
+      ...(node.heightEmu !== undefined ? { heightEmu: node.heightEmu } : {}),
     };
   }
 
@@ -559,3 +604,32 @@ function recordOpaqueFragment(
     warningId,
   };
 }
+
+/**
+ * Extract text content from field contentXml to populate the field's children
+ * array. This enables cross-reference and TOC content to be visible in the
+ * canonical model and surface projection.
+ */
+function normalizeFieldContentXml(contentXml: string | undefined): InlineNode[] {
+  if (!contentXml || contentXml.trim().length === 0) {
+    return [];
+  }
+
+  // Extract text from <w:t> elements within the content runs
+  const textPattern = /<w:t\b[^>]*>([\s\S]*?)<\/w:t>/g;
+  const children: InlineNode[] = [];
+
+  for (const match of contentXml.matchAll(textPattern)) {
+    const text = match[1]
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'");
+    if (text.length > 0) {
+      children.push({ type: "text", text });
+    }
+  }
+
+  return children;
+}

package/src/io/ooxml/highlight-colors.ts

@@ -0,0 +1,39 @@
+export const HIGHLIGHT_COLOR_MAP = {
+  black: "000000",
+  blue: "0000FF",
+  cyan: "00FFFF",
+  darkBlue: "000080",
+  darkCyan: "008080",
+  darkGray: "808080",
+  darkGreen: "008000",
+  darkMagenta: "800080",
+  darkRed: "8B0000",
+  darkYellow: "808000",
+  green: "00FF00",
+  lightGray: "C0C0C0",
+  magenta: "FF00FF",
+  red: "FF0000",
+  white: "FFFFFF",
+  yellow: "FFFF00",
+} as const;
+
+export type HighlightColorName = keyof typeof HIGHLIGHT_COLOR_MAP;
+
+export function resolveHighlightColor(
+  value: string | null | undefined,
+): { color: string; val: HighlightColorName } | undefined {
+  if (!value || value === "none") {
+    return undefined;
+  }
+
+  const normalizedValue = value as HighlightColorName;
+  const color = HIGHLIGHT_COLOR_MAP[normalizedValue];
+  if (!color) {
+    return undefined;
+  }
+
+  return {
+    color,
+    val: normalizedValue,
+  };
+}

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":