@beyondwork/docx-react-component 1.0.29 → 1.0.31

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

@@ -0,0 +1,670 @@
+import type {
+  AltChunkNode,
+  BlockNode,
+  CustomXmlNode,
+  DiagnosticStore,
+  DocumentRootNode,
+  FieldRegistry,
+  InlineNode,
+  MediaCatalog,
+  OpaqueBlockNode,
+  OpaqueFragmentRecord,
+  OpaqueInlineNode,
+  ParagraphNode,
+  PreservationStore,
+  SectionBreakNode,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+  TextMark,
+  TextNode,
+  SdtNode,
+} from "../../model/canonical-document.ts";
+import type {
+  ParsedAltChunkNode,
+  ParsedBlockNode,
+  ParsedCustomXmlNode,
+  ParsedHyperlinkNode,
+  ParsedInlineNode,
+  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 {
+  nextFragmentIndex: number;
+  nextWarningIndex: number;
+  nextDiagnosticIndex: number;
+  cursor: number;
+  media: MediaCatalog;
+  preservation: PreservationStore;
+  diagnostics: DiagnosticStore;
+}
+
+export function normalizeParsedTextDocument(
+  document: ParsedMainDocument,
+  packagePartName = "/word/document.xml",
+  options?: { styles?: import("../../model/canonical-document.ts").StylesCatalog },
+): NormalizedTextDocument {
+  const state: NormalizationState = {
+    nextFragmentIndex: 1,
+    nextWarningIndex: 1,
+    nextDiagnosticIndex: 1,
+    cursor: 0,
+    media: {
+      items: {},
+    },
+    preservation: {
+      opaqueFragments: {},
+      packageParts: {},
+    },
+    diagnostics: {
+      warnings: [],
+      errors: [],
+    },
+  };
+
+  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";
+    }
+  }
+
+  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,
+    media: state.media,
+    preservation: state.preservation,
+    diagnostics: state.diagnostics,
+    ...(document.finalSectionProperties !== undefined
+      ? { finalSectionProperties: document.finalSectionProperties }
+      : {}),
+    ...(hasFields ? { fieldRegistry } : {}),
+  };
+}
+
+function normalizeBlocks(
+  block: ParsedBlockNode,
+  state: NormalizationState,
+  packagePartName: string,
+): 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,
+      },
+    ];
+  }
+
+  if (block.type === "table") {
+    return [normalizeTable(block, state, packagePartName)];
+  }
+
+  if (block.type === "sdt") {
+    return [normalizeSdt(block, state, packagePartName)];
+  }
+
+  if (block.type === "custom_xml") {
+    return [normalizeCustomXml(block, state, packagePartName)];
+  }
+
+  if (block.type === "alt_chunk") {
+    return [normalizeAltChunk(block, state)];
+  }
+
+  if (block.type === "section_break") {
+    return [normalizeSectionBreak(block)];
+  }
+
+  const normalizedParagraph = normalizeParagraph(block, state, packagePartName);
+  return block.sectionProperties
+    ? [normalizedParagraph, normalizeInlineSectionBreak(block)]
+    : [normalizedParagraph];
+}
+
+function normalizeParagraph(
+  paragraph: ParsedParagraphNode,
+  state: NormalizationState,
+  packagePartName: string,
+): ParagraphNode {
+  const children = normalizeInlineChildren(paragraph.children, state, packagePartName);
+  return {
+    type: "paragraph",
+    ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
+    ...(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 } : {}),
+    ...(paragraph.keepLines ? { keepLines: paragraph.keepLines } : {}),
+    ...(paragraph.outlineLevel !== undefined ? { outlineLevel: paragraph.outlineLevel } : {}),
+    ...(paragraph.pageBreakBefore ? { pageBreakBefore: paragraph.pageBreakBefore } : {}),
+    ...(paragraph.bidi ? { bidi: paragraph.bidi } : {}),
+    ...(paragraph.borders ? { borders: paragraph.borders } : {}),
+    ...(paragraph.shading ? { shading: paragraph.shading } : {}),
+    children,
+  };
+}
+
+function normalizeTable(
+  table: ParsedTableBlockNode,
+  state: NormalizationState,
+  packagePartName: string,
+): TableNode {
+  const rows = table.rows.map((row) => normalizeTableRow(row, state, packagePartName));
+  state.cursor += 1;
+  return {
+    type: "table",
+    ...(table.styleId ? { styleId: table.styleId } : {}),
+    ...(table.propertiesXml ? { propertiesXml: table.propertiesXml } : {}),
+    gridColumns: table.gridColumns,
+    rows,
+    ...(table.width ? { width: table.width } : {}),
+    ...(table.alignment ? { alignment: table.alignment } : {}),
+    ...(table.borders ? { borders: table.borders } : {}),
+    ...(table.cellMargins ? { cellMargins: table.cellMargins } : {}),
+    ...(table.tblLook ? { tblLook: table.tblLook } : {}),
+  };
+}
+
+function normalizeTableRow(
+  row: ParsedTableRowNode,
+  state: NormalizationState,
+  packagePartName: string,
+): TableRowNode {
+  const cells = row.cells.map((cell) => normalizeTableCell(cell, state, packagePartName));
+  return {
+    type: "table_row",
+    ...(row.propertiesXml ? { propertiesXml: row.propertiesXml } : {}),
+    ...(row.gridBefore !== undefined ? { gridBefore: row.gridBefore } : {}),
+    ...(row.widthBefore ? { widthBefore: row.widthBefore } : {}),
+    ...(row.gridAfter !== undefined ? { gridAfter: row.gridAfter } : {}),
+    ...(row.widthAfter ? { widthAfter: row.widthAfter } : {}),
+    ...(row.height !== undefined ? { height: row.height } : {}),
+    ...(row.heightRule ? { heightRule: row.heightRule } : {}),
+    ...(row.isHeader !== undefined ? { isHeader: row.isHeader } : {}),
+    cells,
+  };
+}
+
+function normalizeTableCell(
+  cell: ParsedTableCellNode,
+  state: NormalizationState,
+  packagePartName: string,
+): TableCellNode {
+  const children: BlockNode[] = [];
+  for (const block of cell.children) {
+    children.push(...normalizeBlocks(block, state, packagePartName));
+  }
+  // Ensure at least one child (OOXML requires at least one <w:p> per cell)
+  if (children.length === 0) {
+    children.push({ type: "paragraph", children: [] });
+  }
+  return {
+    type: "table_cell",
+    ...(cell.propertiesXml ? { propertiesXml: cell.propertiesXml } : {}),
+    ...(cell.gridSpan ? { gridSpan: cell.gridSpan } : {}),
+    ...(cell.verticalMerge ? { verticalMerge: cell.verticalMerge } : {}),
+    ...(cell.width ? { width: cell.width } : {}),
+    ...(cell.borders ? { borders: cell.borders } : {}),
+    ...(cell.shading ? { shading: cell.shading } : {}),
+    ...(cell.verticalAlign ? { verticalAlign: cell.verticalAlign } : {}),
+    children,
+  };
+}
+
+function normalizeSdt(
+  block: ParsedSdtNode,
+  state: NormalizationState,
+  packagePartName: string,
+): SdtNode {
+  return {
+    type: "sdt",
+    properties: { ...block.properties },
+    children: block.children.flatMap((child) => normalizeBlocks(child, state, packagePartName)),
+  };
+}
+
+function normalizeCustomXml(
+  block: ParsedCustomXmlNode,
+  state: NormalizationState,
+  packagePartName: string,
+): CustomXmlNode {
+  return {
+    type: "custom_xml",
+    ...(block.uri ? { uri: block.uri } : {}),
+    ...(block.element ? { element: block.element } : {}),
+    ...(block.rawXml ? { rawXml: block.rawXml } : {}),
+    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!,
+  };
+}
+
+function normalizeAltChunk(
+  block: ParsedAltChunkNode,
+  state: NormalizationState,
+): AltChunkNode {
+  state.cursor += 1;
+  return {
+    type: "alt_chunk",
+    relationshipId: block.relationshipId,
+  };
+}
+
+function normalizeInlineChildren(
+  nodes: ParsedInlineNode[],
+  state: NormalizationState,
+  packagePartName: string,
+): InlineNode[] {
+  const normalized: InlineNode[] = [];
+
+  for (const node of nodes) {
+    switch (node.type) {
+      case "text": {
+        if (node.text.length === 0) {
+          continue;
+        }
+
+        const previous = normalized[normalized.length - 1];
+        if (previous?.type === "text" && sameMarks(previous.marks, node.marks)) {
+          previous.text += node.text;
+        } else {
+          normalized.push({
+            type: "text",
+            text: node.text,
+            ...(node.marks && node.marks.length > 0 ? { marks: node.marks } : {}),
+          });
+        }
+        state.cursor += Array.from(node.text).length;
+        break;
+      }
+      case "tab":
+        normalized.push({ type: "tab" });
+        state.cursor += 1;
+        break;
+      case "hard_break":
+        normalized.push({ type: "hard_break" });
+        state.cursor += 1;
+        break;
+      case "image":
+        normalized.push(normalizeImageNode(node, state));
+        state.cursor += 1;
+        break;
+      case "hyperlink":
+        normalized.push(normalizeHyperlink(node));
+        state.cursor += measureHyperlink(node);
+        break;
+      case "opaque_inline": {
+        const opaque = recordOpaqueFragment("opaque_inline", node.rawXml, state, packagePartName);
+        normalized.push(opaque as OpaqueInlineNode);
+        state.cursor += 1;
+        break;
+      }
+      case "symbol":
+        normalized.push({
+          type: "symbol",
+          char: node.char,
+          font: node.font,
+          ...(node.marks && node.marks.length > 0 ? { marks: node.marks } : {}),
+        });
+        state.cursor += 1;
+        break;
+      case "column_break":
+        normalized.push({ type: "column_break" });
+        state.cursor += 1;
+        break;
+      case "chart_preview":
+        normalized.push({
+          type: "chart_preview",
+          ...(node.previewMediaId ? { previewMediaId: node.previewMediaId } : {}),
+          rawXml: node.rawXml,
+        });
+        state.cursor += 1;
+        break;
+      case "smartart_preview":
+        normalized.push({
+          type: "smartart_preview",
+          ...(node.previewMediaId ? { previewMediaId: node.previewMediaId } : {}),
+          rawXml: node.rawXml,
+        });
+        state.cursor += 1;
+        break;
+      case "shape":
+        normalized.push({
+          type: "shape",
+          ...(node.text ? { text: node.text } : {}),
+          ...(node.geometry ? { geometry: node.geometry } : {}),
+          ...(node.isTextBox ? { isTextBox: true } : {}),
+          rawXml: node.rawXml,
+        });
+        state.cursor += 1;
+        break;
+      case "wordart":
+        normalized.push({
+          type: "wordart",
+          text: node.text,
+          ...(node.geometry ? { geometry: node.geometry } : {}),
+          rawXml: node.rawXml,
+        });
+        state.cursor += 1;
+        break;
+      case "vml_shape":
+        normalized.push({
+          type: "vml_shape",
+          ...(node.text ? { text: node.text } : {}),
+          ...(node.shapeType ? { shapeType: node.shapeType } : {}),
+          rawXml: node.rawXml,
+        });
+        state.cursor += 1;
+        break;
+      case "bookmark_start":
+        normalized.push({
+          type: "bookmark_start",
+          bookmarkId: node.bookmarkId,
+          name: node.name,
+        });
+        break;
+      case "bookmark_end":
+        normalized.push({
+          type: "bookmark_end",
+          bookmarkId: node.bookmarkId,
+        });
+        break;
+      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;
+        const renderedLength = measureNormalizedInlineDisplayLength(fieldChildren);
+        normalized.push({
+          type: "field",
+          fieldType: node.fieldType,
+          instruction: node.instruction,
+          children: fieldChildren,
+          fieldFamily: classification.family,
+          ...(classification.target ? { fieldTarget: classification.target } : {}),
+          refreshStatus: classification.supported ? "stale" : "preserve-only",
+        });
+        state.cursor += renderedLength > 0 ? renderedLength : 1;
+        break;
+      }
+    }
+  }
+
+  return normalized;
+}
+
+function normalizeImageNode(
+  node: ParsedImageNode,
+  state: NormalizationState,
+): InlineNode {
+  const existingMediaItem = state.media.items[node.mediaId];
+  if (!existingMediaItem) {
+    const packagePartName =
+      typeof node.packagePartName === "string" && node.packagePartName.length > 0
+        ? node.packagePartName
+        : `/${node.mediaId.slice("media:".length)}`;
+    const filename =
+      typeof node.filename === "string" && node.filename.length > 0
+        ? node.filename
+        : packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "image.bin";
+    state.media.items[node.mediaId] = {
+      mediaId: node.mediaId,
+      contentType: node.contentType ?? "application/octet-stream",
+      filename,
+      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 } : {}),
+    };
+  }
+
+  return {
+    type: "image",
+    mediaId: node.mediaId,
+    ...(node.altText ? { altText: node.altText } : {}),
+    ...(node.placementXml ? { placementXml: node.placementXml } : {}),
+    ...(node.display ? { display: node.display } : {}),
+    ...(node.floating ? { floating: node.floating } : {}),
+  };
+}
+
+function normalizeHyperlink(node: ParsedHyperlinkNode): {
+  type: "hyperlink";
+  href: string;
+  children: Array<TextNode | { type: "hard_break" } | { type: "tab" }>;
+} {
+  const children: Array<TextNode | { type: "hard_break" } | { type: "tab" }> = [];
+
+  for (const child of node.children) {
+    switch (child.type) {
+      case "text": {
+        if (child.text.length === 0) {
+          continue;
+        }
+        const previous = children[children.length - 1];
+        if (previous?.type === "text" && sameMarks(previous.marks, child.marks)) {
+          previous.text += child.text;
+        } else {
+          children.push({
+            type: "text",
+            text: child.text,
+            ...(child.marks && child.marks.length > 0 ? { marks: child.marks } : {}),
+          });
+        }
+        break;
+      }
+      case "tab":
+        children.push({ type: "tab" });
+        break;
+      case "hard_break":
+        children.push({ type: "hard_break" });
+        break;
+    }
+  }
+
+  return {
+    type: "hyperlink",
+    href: node.href,
+    children,
+  };
+}
+
+function measureHyperlink(node: ParsedHyperlinkNode): number {
+  return node.children.reduce<number>((size, child) => {
+    if (child.type === "text") {
+      return size + Array.from(child.text).length;
+    }
+    return size + 1;
+  }, 0);
+}
+
+function sameMarks(left: TextMark[] | undefined, right: TextMark[] | undefined): boolean {
+  const leftMarks = normalizeMarks(left);
+  const rightMarks = normalizeMarks(right);
+  return leftMarks.length === rightMarks.length && leftMarks.every((mark, index) => mark === rightMarks[index]);
+}
+
+function normalizeMarks(marks: TextMark[] | undefined): string[] {
+  return [...(marks ?? []).map(serializeMark)].sort();
+}
+
+function serializeMark(mark: TextMark): string {
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(mark).sort(([left], [right]) => left.localeCompare(right)),
+    ),
+  );
+}
+
+function recordOpaqueFragment(
+  nodeType: "opaque_inline" | "opaque_block",
+  rawXml: string,
+  state: NormalizationState,
+  packagePartName: string,
+): { type: "opaque_inline" | "opaque_block"; fragmentId: string; warningId: string } {
+  const fragmentId = `fragment:import-${state.nextFragmentIndex}`;
+  state.nextFragmentIndex += 1;
+  const warningId = `warning:import-${state.nextWarningIndex}`;
+  state.nextWarningIndex += 1;
+  const diagnosticId = `diagnostic:import-${state.nextDiagnosticIndex}`;
+  state.nextDiagnosticIndex += 1;
+
+  const rangeStart = state.cursor;
+  const rangeEnd = state.cursor + 1;
+
+  const record: OpaqueFragmentRecord = {
+    fragmentId,
+    payloadKind: "xml-subtree",
+    payloadReference: rawXml,
+    featureClass: "preserve-only",
+    lastKnownRange: {
+      from: rangeStart,
+      to: rangeEnd,
+    },
+    warningId,
+    packagePartName,
+  };
+
+  state.preservation.opaqueFragments[fragmentId] = record;
+  state.diagnostics.warnings.push({
+    diagnosticId,
+    warningId,
+    source: "import",
+    message:
+      nodeType === "opaque_inline"
+        ? "Unsupported inline OOXML was preserved as an opaque placeholder."
+        : "Unsupported block OOXML was preserved as an opaque placeholder.",
+  });
+
+  return {
+    type: nodeType,
+    fragmentId,
+    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;
+}
+
+function measureNormalizedInlineDisplayLength(nodes: InlineNode[]): number {
+  return nodes.reduce((total, node) => {
+    switch (node.type) {
+      case "text":
+        return total + Array.from(node.text).length;
+      case "hyperlink":
+      case "field":
+        return total + measureNormalizedInlineDisplayLength(node.children);
+      case "bookmark_start":
+      case "bookmark_end":
+        return total;
+      default:
+        return total + 1;
+    }
+  }, 0);
+}

package/src/io/ooxml/README.md

@@ -0,0 +1,3 @@
+# IO OOXML
+
+WordprocessingML parsing and intermediate OOXML structures belong here.

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,
+  };
+}