@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/io/export/serialize-numbering.ts

@@ -1,15 +1,23 @@
 import type { NumberingCatalog, ParagraphNode } from "../../model/canonical-document.ts";
+import {
+  isSyntheticDocxNullAbstractDefinition,
+  isSyntheticDocxNullNumberingInstance,
+} from "../ooxml/numbering-sentinels.ts";
 
 export const WORD_NUMBERING_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml";
 
 export function serializeNumberingXml(catalog: NumberingCatalog): string {
-  const abstractDefinitions = Object.values(catalog.abstractDefinitions).sort((left, right) =>
-    compareSerializedIds(left.abstractNumberingId, right.abstractNumberingId),
-  );
-  const instances = Object.values(catalog.instances).sort((left, right) =>
-    compareSerializedIds(left.numberingInstanceId, right.numberingInstanceId),
-  );
+  const abstractDefinitions = Object.values(catalog.abstractDefinitions)
+    .filter((definition) => !isSyntheticDocxNullAbstractDefinition(definition))
+    .sort((left, right) =>
+      compareSerializedIds(left.abstractNumberingId, right.abstractNumberingId),
+    );
+  const instances = Object.values(catalog.instances)
+    .filter((instance) => !isSyntheticDocxNullNumberingInstance(instance))
+    .sort((left, right) =>
+      compareSerializedIds(left.numberingInstanceId, right.numberingInstanceId),
+    );
 
   const body = [
     ...abstractDefinitions.map((definition) => serializeAbstractDefinition(definition)),
@@ -22,6 +30,17 @@ export function serializeNumberingXml(catalog: NumberingCatalog): string {
   ].join("\n");
 }
 
+export function hasSerializableNumberingEntries(catalog: NumberingCatalog): boolean {
+  return (
+    Object.values(catalog.abstractDefinitions).some(
+      (definition) => !isSyntheticDocxNullAbstractDefinition(definition),
+    ) ||
+    Object.values(catalog.instances).some(
+      (instance) => !isSyntheticDocxNullNumberingInstance(instance),
+    )
+  );
+}
+
 export function serializeParagraphNumberingProperties(
   numbering: ParagraphNode["numbering"],
 ): string {
@@ -51,10 +70,12 @@ function serializeLevel(level: NumberingCatalog["abstractDefinitions"][string]["
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
+  const isLegal = level.isLegalNumbering ? "<w:isLgl/>" : "";
+  const suffix = level.suffix ? `<w:suff w:val="${escapeAttribute(level.suffix)}"/>` : "";
 
   return `<w:lvl w:ilvl="${level.level}">${start}<w:numFmt w:val="${escapeAttribute(
     level.format,
-  )}"/><w:lvlText w:val="${escapeAttribute(level.text)}"/>${paragraphStyle}</w:lvl>`;
+  )}"/><w:lvlText w:val="${escapeAttribute(level.text)}"/>${paragraphStyle}${isLegal}${suffix}</w:lvl>`;
 }
 
 function serializeInstance(instance: NumberingCatalog["instances"][string]): string {

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,
@@ -11,6 +12,7 @@ import type {
   OpaqueInlineNode,
   ParagraphNode,
   PreservationStore,
+  SectionBreakNode,
   TableCellNode,
   TableNode,
   TableRowNode,
@@ -27,17 +29,22 @@ import type {
   ParsedImageNode,
   ParsedMainDocument,
   ParsedParagraphNode,
+  ParsedSectionBreakNode,
   ParsedSdtNode,
   ParsedTableBlockNode,
   ParsedTableCellNode,
   ParsedTableRowNode,
 } from "../ooxml/parse-main-document.ts";
+import { classifyFieldInstruction, buildFieldRegistry } from "../ooxml/parse-fields.ts";
 
 export interface NormalizedTextDocument {
   content: DocumentRootNode;
   media: MediaCatalog;
   preservation: PreservationStore;
   diagnostics: DiagnosticStore;
+  finalSectionProperties?: ParsedMainDocument["finalSectionProperties"];
+  /** Package-backed field registry built during normalization. */
+  fieldRegistry?: FieldRegistry;
 }
 
 interface NormalizationState {
@@ -53,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,
@@ -72,61 +80,82 @@ export function normalizeParsedTextDocument(
     },
   };
 
-  const children = document.blocks.map((block, index) => {
-    if (
-      index > 0 &&
-      document.blocks[index - 1]?.type === "paragraph" &&
-      block.type === "paragraph"
-    ) {
-      state.cursor += 1;
+  const children: BlockNode[] = [];
+  let previousParagraph = false;
+
+  for (const block of document.blocks) {
+    const normalizedBlocks = normalizeBlocks(block, state, packagePartName);
+    for (const normalizedBlock of normalizedBlocks) {
+      if (previousParagraph && normalizedBlock.type === "paragraph") {
+        state.cursor += 1;
+      }
+      children.push(normalizedBlock);
+      previousParagraph = normalizedBlock.type === "paragraph";
     }
+  }
 
-    return normalizeBlock(block, state, packagePartName);
-  });
+  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 } : {}),
   };
 }
 
-function normalizeBlock(
+function normalizeBlocks(
   block: ParsedBlockNode,
   state: NormalizationState,
   packagePartName: string,
-): BlockNode {
+): BlockNode[] {
   if (block.type === "opaque_block") {
     const opaque = recordOpaqueFragment("opaque_block", block.rawXml, state, packagePartName);
     state.cursor += 1;
-    return {
-      type: "opaque_block",
-      fragmentId: opaque.fragmentId,
-      warningId: opaque.warningId,
-    };
+    return [
+      {
+        type: "opaque_block",
+        fragmentId: opaque.fragmentId,
+        warningId: opaque.warningId,
+      },
+    ];
   }
 
   if (block.type === "table") {
-    return normalizeTable(block, state, packagePartName);
+    return [normalizeTable(block, state, packagePartName)];
   }
 
   if (block.type === "sdt") {
-    return normalizeSdt(block, state, packagePartName);
+    return [normalizeSdt(block, state, packagePartName)];
   }
 
   if (block.type === "custom_xml") {
-    return normalizeCustomXml(block, state, packagePartName);
+    return [normalizeCustomXml(block, state, packagePartName)];
   }
 
   if (block.type === "alt_chunk") {
-    return normalizeAltChunk(block, state);
+    return [normalizeAltChunk(block, state)];
   }
 
-  return normalizeParagraph(block, state, packagePartName);
+  if (block.type === "section_break") {
+    return [normalizeSectionBreak(block)];
+  }
+
+  const normalizedParagraph = normalizeParagraph(block, state, packagePartName);
+  return block.sectionProperties
+    ? [normalizedParagraph, normalizeInlineSectionBreak(block)]
+    : [normalizedParagraph];
 }
 
 function normalizeParagraph(
@@ -141,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 } : {}),
@@ -190,7 +222,7 @@ function normalizeTableCell(
 ): TableCellNode {
   const children: BlockNode[] = [];
   for (const block of cell.children) {
-    children.push(normalizeBlock(block, state, packagePartName));
+    children.push(...normalizeBlocks(block, state, packagePartName));
   }
   // Ensure at least one child (OOXML requires at least one <w:p> per cell)
   if (children.length === 0) {
@@ -213,7 +245,7 @@ function normalizeSdt(
   return {
     type: "sdt",
     properties: { ...block.properties },
-    children: block.children.map((child) => normalizeBlock(child, state, packagePartName)),
+    children: block.children.flatMap((child) => normalizeBlocks(child, state, packagePartName)),
   };
 }
 
@@ -226,7 +258,27 @@ function normalizeCustomXml(
     type: "custom_xml",
     ...(block.uri ? { uri: block.uri } : {}),
     ...(block.element ? { element: block.element } : {}),
-    children: block.children.map((child) => normalizeBlock(child, state, packagePartName)),
+    children: block.children.flatMap((child) => normalizeBlocks(child, state, packagePartName)),
+  };
+}
+
+function normalizeSectionBreak(block: ParsedSectionBreakNode): SectionBreakNode {
+  return {
+    type: "section_break",
+    sectionPropertiesXml: block.sectionPropertiesXml,
+    sectionProperties: block.sectionProperties,
+  };
+}
+
+function normalizeInlineSectionBreak(
+  paragraph: ParsedParagraphNode,
+): SectionBreakNode {
+  return {
+    type: "section_break",
+    ...(paragraph.sectionPropertiesXml
+      ? { sectionPropertiesXml: paragraph.sectionPropertiesXml }
+      : {}),
+    sectionProperties: paragraph.sectionProperties!,
   };
 }
 
@@ -324,6 +376,7 @@ function normalizeInlineChildren(
           type: "shape",
           ...(node.text ? { text: node.text } : {}),
           ...(node.geometry ? { geometry: node.geometry } : {}),
+          ...(node.isTextBox ? { isTextBox: true } : {}),
           rawXml: node.rawXml,
         });
         state.cursor += 1;
@@ -359,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;
+      }
     }
   }
 
@@ -378,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
@@ -394,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 } : {}),
     };
   }
 
@@ -521,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/numbering-sentinels.ts

@@ -0,0 +1,44 @@
+import type { NumberingCatalog } from "../../model/canonical-document.ts";
+
+export const DOCX_NULL_NUMBERING_INSTANCE_ID = "num:0";
+export const DOCX_NULL_ABSTRACT_NUMBERING_ID = "abstract-num:__docx-import-null__";
+
+export function createSyntheticDocxNullNumberingCatalog(): Pick<
+  NumberingCatalog,
+  "abstractDefinitions" | "instances"
+> {
+  return {
+    abstractDefinitions: {
+      [DOCX_NULL_ABSTRACT_NUMBERING_ID]: {
+        abstractNumberingId: DOCX_NULL_ABSTRACT_NUMBERING_ID,
+        levels: Array.from({ length: 9 }, (_unused, level) => ({
+          level,
+          format: "none",
+          text: "",
+        })),
+      },
+    },
+    instances: {
+      [DOCX_NULL_NUMBERING_INSTANCE_ID]: {
+        numberingInstanceId: DOCX_NULL_NUMBERING_INSTANCE_ID,
+        abstractNumberingId: DOCX_NULL_ABSTRACT_NUMBERING_ID,
+        overrides: [],
+      },
+    },
+  };
+}
+
+export function isSyntheticDocxNullAbstractDefinition(
+  definition: NumberingCatalog["abstractDefinitions"][string],
+): boolean {
+  return definition.abstractNumberingId === DOCX_NULL_ABSTRACT_NUMBERING_ID;
+}
+
+export function isSyntheticDocxNullNumberingInstance(
+  instance: NumberingCatalog["instances"][string],
+): boolean {
+  return (
+    instance.numberingInstanceId === DOCX_NULL_NUMBERING_INSTANCE_ID &&
+    instance.abstractNumberingId === DOCX_NULL_ABSTRACT_NUMBERING_ID
+  );
+}