@beyondwork/docx-react-component 1.0.14 → 1.0.15

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [
@@ -33,10 +33,18 @@
       "types": "./src/api/public-types.ts",
       "import": "./src/api/public-types.ts"
     },
+    "./compare": {
+      "types": "./src/compare/index.ts",
+      "import": "./src/compare/index.ts"
+    },
     "./io/docx-session": {
       "types": "./src/io/docx-session.ts",
       "import": "./src/io/docx-session.ts"
     },
+    "./legal": {
+      "types": "./src/legal/index.ts",
+      "import": "./src/legal/index.ts"
+    },
     "./runtime/document-runtime": {
       "types": "./src/runtime/document-runtime.ts",
       "import": "./src/runtime/document-runtime.ts"
@@ -90,7 +98,7 @@
     "tailwindcss": "^4.2.2"
   },
   "devDependencies": {
-    "@chllming/wave-orchestration": "^0.9.13",
+    "@chllming/wave-orchestration": "^0.9.15",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@typescript/native-preview": "7.0.0-dev.20260409.1",

package/src/api/public-types.ts

@@ -571,16 +571,21 @@ export interface WordReviewEditorRef {
   reopenComment(commentId: string): void;
   addCommentReply(commentId: string, body: string): void;
   editCommentBody(commentId: string, body: string): void;
+  deleteComment(commentId: string): void;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
   rejectAllChanges(): void;
   exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
   getSnapshot(): PersistedEditorSnapshot;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
   getCompatibilityReport(): CompatibilityReport;
   getWarnings(): EditorWarning[];
+  getCommentSidebarSnapshot(): CommentSidebarSnapshot;
+  getTrackedChangesSnapshot(): TrackedChangesSnapshot;
   getComments(): CommentSidebarSnapshot;
   getTrackedChanges(): TrackedChangesSnapshot;
+  isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
   toggleBold(): void;
   toggleItalic(): void;
@@ -610,6 +615,7 @@ export interface WordReviewEditorRef {
   setCellBackground(color: string): void;
   search(query: string, options?: SearchOptions): SearchResultSnapshot[];
   clearSearch(): void;
+  setSelection(selection: SelectionSnapshot | null): void;
   scrollToRevision(revisionId: string): void;
   scrollToComment(commentId: string): void;
 }

package/src/compare/diff-engine.ts

@@ -20,6 +20,7 @@ export interface CompareVersionRef {
 export type CompareChangeKind =
   | "paragraph-insertion"
   | "paragraph-deletion"
+  | "paragraph-modification"
   | "structural-insertion"
   | "structural-deletion";
 
@@ -96,6 +97,22 @@ export function compareDocumentSnapshots(
       const insertBlock = nextTargetIndex < match.targetIndex ? targetBlocks[nextTargetIndex] : undefined;
 
       if (deleteBlock && insertBlock) {
+        if (deleteBlock.type === "paragraph" && insertBlock.type === "paragraph") {
+          const modificationId = `change-${nextChangeNumber}`;
+          nextChangeNumber += 1;
+          addParagraphModificationEntry(
+            buildEntries,
+            changes,
+            modificationId,
+            deleteBlock,
+            insertBlock,
+            nextTargetIndex,
+          );
+          nextBaseIndex += 1;
+          nextTargetIndex += 1;
+          continue;
+        }
+
         const deletionId = `change-${nextChangeNumber}`;
         nextChangeNumber += 1;
         addTrackedOrStructuralEntry(
@@ -153,13 +170,34 @@ export function compareDocumentSnapshots(
     }
 
     if (match.baseIndex < baseBlocks.length && match.targetIndex < targetBlocks.length) {
-      buildEntries.push({
-        block: cloneBlock(targetBlocks[match.targetIndex]),
-        tracked: false,
-        blockType: targetBlocks[match.targetIndex].type,
-        beforeText: getBlockDisplayText(baseBlocks[match.baseIndex]),
-        afterText: getBlockDisplayText(targetBlocks[match.targetIndex]),
-      });
+      const baseText = getBlockDisplayText(baseBlocks[match.baseIndex]);
+      const targetText = getBlockDisplayText(targetBlocks[match.targetIndex]);
+      const isModified =
+        baseBlocks[match.baseIndex].type === "paragraph" &&
+        targetBlocks[match.targetIndex].type === "paragraph" &&
+        baseText !== targetText;
+
+      if (isModified) {
+        const modChangeId = `change-${nextChangeNumber}`;
+        nextChangeNumber += 1;
+        addParagraphModificationEntry(
+          buildEntries,
+          changes,
+          modChangeId,
+          baseBlocks[match.baseIndex] as ParagraphNode,
+          targetBlocks[match.targetIndex] as ParagraphNode,
+          match.targetIndex,
+        );
+      } else {
+        buildEntries.push({
+          block: cloneBlock(targetBlocks[match.targetIndex]),
+          tracked: false,
+          blockType: targetBlocks[match.targetIndex].type,
+          beforeText: baseText,
+          afterText: targetText,
+        });
+      }
+
       nextBaseIndex = match.baseIndex + 1;
       nextTargetIndex = match.targetIndex + 1;
     }
@@ -222,6 +260,45 @@ function addTrackedOrStructuralEntry(
   });
 }
 
+function addParagraphModificationEntry(
+  buildEntries: BuildEntry[],
+  changes: CompareChange[],
+  changeId: string,
+  baseParagraph: ParagraphNode,
+  targetParagraph: ParagraphNode,
+  targetIndex: number,
+): void {
+  const beforeText = getBlockDisplayText(baseParagraph);
+  const afterText = getBlockDisplayText(targetParagraph);
+
+  buildEntries.push({
+    changeId: `${changeId}-before`,
+    block: cloneBlock(baseParagraph),
+    trackChange: "deletion",
+    tracked: true,
+    blockType: "paragraph",
+    beforeText,
+  });
+  buildEntries.push({
+    changeId: `${changeId}-after`,
+    block: cloneBlock(targetParagraph),
+    trackChange: "insertion",
+    tracked: true,
+    blockType: "paragraph",
+    afterText,
+  });
+
+  changes.push({
+    changeId,
+    kind: "paragraph-modification",
+    tracked: true,
+    blockType: "paragraph",
+    beforeText,
+    afterText,
+    targetIndex,
+  });
+}
+
 function buildComparedDocument(
   base: CanonicalDocument,
   target: CanonicalDocument,

package/src/compare/index.ts

@@ -0,0 +1,25 @@
+export {
+  compareDocumentSnapshots,
+  type CompareChange,
+  type CompareChangeKind,
+  type CompareDocumentVersionsOptions,
+  type CompareVersionRef,
+  type VersionCompareResult,
+} from "./diff-engine.ts";
+
+export {
+  exportComparedDocumentRedlines,
+  type ExportComparedDocumentOptions,
+  type ExportComparedDocumentResult,
+} from "./export-redlines.ts";
+
+export {
+  buildVersionAuditTrail,
+  createDocumentVersionSnapshot,
+  createDocumentVersionSnapshotId,
+  lockDocumentVersionSnapshot,
+  saveDocumentVersionSnapshot,
+  type CreateDocumentVersionSnapshotOptions,
+  type DocumentVersionSnapshot,
+  type VersionAuditEntry,
+} from "./snapshot.ts";

package/src/compare/snapshot.ts

@@ -53,6 +53,37 @@ export function saveDocumentVersionSnapshot(
   return next.sort(compareDocumentVersionSnapshots);
 }
 
+export interface VersionAuditEntry {
+  versionId: string;
+  name: string;
+  createdAt: string;
+  documentSignature: string;
+  action: "created" | "compared" | "locked";
+}
+
+export function buildVersionAuditTrail(
+  snapshots: readonly DocumentVersionSnapshot[],
+): VersionAuditEntry[] {
+  return snapshots.map((snapshot) => ({
+    versionId: snapshot.versionId,
+    name: snapshot.name,
+    createdAt: snapshot.createdAt,
+    documentSignature: snapshot.documentSignature,
+    action: "created",
+  }));
+}
+
+export function lockDocumentVersionSnapshot(
+  snapshot: DocumentVersionSnapshot,
+): DocumentVersionSnapshot {
+  return {
+    ...snapshot,
+    name: snapshot.name.startsWith("[locked] ")
+      ? snapshot.name
+      : `[locked] ${snapshot.name}`,
+  };
+}
+
 function compareDocumentVersionSnapshots(
   left: DocumentVersionSnapshot,
   right: DocumentVersionSnapshot,

package/src/formats/xlsx/io/serialize-shared-strings.ts

@@ -0,0 +1,72 @@
+import type { CanonicalWorkbook } from "../model/workbook.ts";
+import { listSheets } from "../model/workbook.ts";
+
+const SHARED_STRINGS_NAMESPACE = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+
+export interface SharedStringTableSerialization {
+  xml: string;
+  strings: string[];
+  indexByValue: Map<string, number>;
+  totalCount: number;
+}
+
+export function buildSharedStringsTable(
+  workbook: CanonicalWorkbook,
+): SharedStringTableSerialization {
+  const strings: string[] = [];
+  const indexByValue = new Map<string, number>();
+  let totalCount = 0;
+
+  for (const sheet of listSheets(workbook)) {
+    for (const cell of sheet.cells.values()) {
+      if (cell.kind !== "text") {
+        continue;
+      }
+
+      totalCount += 1;
+
+      if (!indexByValue.has(cell.value)) {
+        indexByValue.set(cell.value, strings.length);
+        strings.push(cell.value);
+      }
+    }
+  }
+
+  return {
+    xml: serializeSharedStringsXml(strings, totalCount),
+    strings,
+    indexByValue,
+    totalCount,
+  };
+}
+
+export function serializeSharedStringsXml(
+  strings: readonly string[],
+  totalCount: number = strings.length,
+): string {
+  const items = strings.map(serializeSharedStringItem);
+  const body = items.length > 0 ? `\n${items.join("\n")}\n` : "";
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<sst xmlns="${SHARED_STRINGS_NAMESPACE}" count="${totalCount}" uniqueCount="${strings.length}">${body}</sst>`,
+  ].join("\n");
+}
+
+function serializeSharedStringItem(value: string): string {
+  const preserveSpace = requiresPreservedSpace(value) ? ` xml:space="preserve"` : "";
+  return `  <si><t${preserveSpace}>${escapeXml(value)}</t></si>`;
+}
+
+function requiresPreservedSpace(value: string): boolean {
+  return /^\s/.test(value) || /\s$/.test(value);
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/'/g, "&apos;");
+}

package/src/formats/xlsx/io/serialize-sheet.ts

@@ -0,0 +1,333 @@
+import type { CellKey, CellValue, FormulaCell } from "../model/cell.ts";
+import { parseCellKey } from "../model/cell.ts";
+import type { CanonicalSheet, MergeRange, SheetPaneState } from "../model/sheet.ts";
+
+const WORKSHEET_NAMESPACE = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+
+export interface SheetSerializationOptions {
+  sharedStringIndexByValue?: ReadonlyMap<string, number>;
+}
+
+export function serializeSheetXml(
+  sheet: CanonicalSheet,
+  options: SheetSerializationOptions = {},
+): string {
+  const rows = groupCellsByRow(sheet);
+  const rowIndices = new Set<number>([
+    ...rows.keys(),
+    ...sheet.rowProps.keys(),
+  ]);
+  const sortedRowIndices = [...rowIndices].sort((left, right) => left - right);
+  const lines = [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<worksheet xmlns="${WORKSHEET_NAMESPACE}">`,
+    `  <dimension ref="${computeDimensionRef(sheet)}"/>`,
+    ...serializeSheetViews(sheet.paneState),
+    ...serializeColumns(sheet),
+  ];
+
+  if (sortedRowIndices.length === 0) {
+    lines.push(`  <sheetData/>`);
+  } else {
+    lines.push(`  <sheetData>`);
+    for (const rowIndex of sortedRowIndices) {
+      const rowProps = sheet.rowProps.get(rowIndex);
+      const rowCells = rows.get(rowIndex) ?? [];
+      const rowAttributes = [
+        `r="${rowIndex + 1}"`,
+      ];
+
+      if (rowProps?.heightPt !== undefined) {
+        rowAttributes.push(`ht="${formatNumber(rowProps.heightPt)}"`);
+      }
+      if (rowProps?.hidden) {
+        rowAttributes.push(`hidden="1"`);
+      }
+      if (rowProps?.customHeight) {
+        rowAttributes.push(`customHeight="1"`);
+      }
+      if (rowProps?.styleRef) {
+        rowAttributes.push(`s="${rowProps.styleRef.xfIndex}"`, `customFormat="1"`);
+      }
+
+      if (rowCells.length === 0) {
+        lines.push(`    <row ${rowAttributes.join(" ")}></row>`);
+        continue;
+      }
+
+      lines.push(`    <row ${rowAttributes.join(" ")}>`);
+      for (const cellEntry of rowCells) {
+        lines.push(`      ${serializeCellXml(cellEntry, options.sharedStringIndexByValue)}`);
+      }
+      lines.push(`    </row>`);
+    }
+    lines.push(`  </sheetData>`);
+  }
+
+  if (sheet.merges.length > 0) {
+    lines.push(`  <mergeCells count="${sheet.merges.length}">`);
+    for (const merge of [...sheet.merges].sort(compareMergeRanges)) {
+      lines.push(`    <mergeCell ref="${formatMergeRef(merge)}"/>`);
+    }
+    lines.push(`  </mergeCells>`);
+  }
+
+  lines.push(`</worksheet>`);
+  return lines.join("\n");
+}
+
+function groupCellsByRow(
+  sheet: CanonicalSheet,
+): Map<number, Array<[CellKey, CellValue]>> {
+  const rows = new Map<number, Array<[CellKey, CellValue]>>();
+  const sortedCells = [...sheet.cells.entries()].sort(
+    ([leftKey], [rightKey]) => compareCellKeys(leftKey, rightKey),
+  );
+
+  for (const entry of sortedCells) {
+    const { row } = parseCellKey(entry[0]);
+    const rowEntries = rows.get(row) ?? [];
+    rowEntries.push(entry);
+    rows.set(row, rowEntries);
+  }
+
+  return rows;
+}
+
+function serializeSheetViews(paneState: SheetPaneState | undefined): string[] {
+  if (!paneState || (paneState.frozenRows <= 0 && paneState.frozenCols <= 0)) {
+    return [];
+  }
+
+  const paneAttributes = [
+    `state="frozen"`,
+    `topLeftCell="${formatCellRef(paneState.frozenRows, paneState.frozenCols)}"`,
+    `activePane="${resolveActivePane(paneState)}"`,
+  ];
+
+  if (paneState.frozenCols > 0) {
+    paneAttributes.push(`xSplit="${paneState.frozenCols}"`);
+  }
+  if (paneState.frozenRows > 0) {
+    paneAttributes.push(`ySplit="${paneState.frozenRows}"`);
+  }
+
+  return [
+    `  <sheetViews>`,
+    `    <sheetView workbookViewId="0">`,
+    `      <pane ${paneAttributes.join(" ")}/>`,
+    `    </sheetView>`,
+    `  </sheetViews>`,
+  ];
+}
+
+function resolveActivePane(paneState: SheetPaneState): string {
+  if (paneState.frozenRows > 0 && paneState.frozenCols > 0) {
+    return "bottomRight";
+  }
+  if (paneState.frozenRows > 0) {
+    return "bottomLeft";
+  }
+  return "topRight";
+}
+
+function serializeColumns(sheet: CanonicalSheet): string[] {
+  const columns = [...sheet.colProps.values()].sort(
+    (left, right) => left.colIndex - right.colIndex,
+  );
+  if (columns.length === 0) {
+    return [];
+  }
+
+  const lines = [`  <cols>`];
+  for (const column of columns) {
+    const attributes = [
+      `min="${column.colIndex + 1}"`,
+      `max="${column.colIndex + 1}"`,
+    ];
+
+    if (column.widthChars !== undefined) {
+      attributes.push(`width="${formatNumber(column.widthChars)}"`);
+    }
+    if (column.hidden) {
+      attributes.push(`hidden="1"`);
+    }
+    if (column.customWidth) {
+      attributes.push(`customWidth="1"`);
+    }
+    if (column.styleRef) {
+      attributes.push(`style="${column.styleRef.xfIndex}"`);
+    }
+
+    lines.push(`    <col ${attributes.join(" ")}/>`);
+  }
+  lines.push(`  </cols>`);
+  return lines;
+}
+
+function serializeCellXml(
+  [key, cell]: [CellKey, CellValue],
+  sharedStringIndexByValue: ReadonlyMap<string, number> | undefined,
+): string {
+  const { row, col } = parseCellKey(key);
+  const ref = formatCellRef(row, col);
+  const styleAttr = cell.styleRef ? ` s="${cell.styleRef.xfIndex}"` : "";
+
+  switch (cell.kind) {
+    case "blank":
+      return `<c r="${ref}"${styleAttr}/>`;
+
+    case "text": {
+      if (sharedStringIndexByValue && sharedStringIndexByValue.has(cell.value)) {
+        return `<c r="${ref}"${styleAttr} t="s"><v>${sharedStringIndexByValue.get(cell.value)}</v></c>`;
+      }
+
+      const preserveSpace = requiresPreservedSpace(cell.value) ? ` xml:space="preserve"` : "";
+      return `<c r="${ref}"${styleAttr} t="inlineStr"><is><t${preserveSpace}>${escapeXml(cell.value)}</t></is></c>`;
+    }
+
+    case "number":
+      return `<c r="${ref}"${styleAttr}><v>${formatNumber(cell.value)}</v></c>`;
+
+    case "boolean":
+      return `<c r="${ref}"${styleAttr} t="b"><v>${cell.value ? "1" : "0"}</v></c>`;
+
+    case "error":
+      return `<c r="${ref}"${styleAttr} t="e"><v>${escapeXml(cell.errorCode)}</v></c>`;
+
+    case "formula":
+      return serializeFormulaCellXml(ref, styleAttr, cell);
+  }
+}
+
+function serializeFormulaCellXml(
+  ref: string,
+  styleAttr: string,
+  cell: FormulaCell,
+): string {
+  const cachedValue = serializeFormulaCachedValue(cell);
+  const typeAttr = cachedValue.typeCode ? ` t="${cachedValue.typeCode}"` : "";
+  const valueXml = cachedValue.valueXml ? `<v>${cachedValue.valueXml}</v>` : "";
+  return `<c r="${ref}"${styleAttr}${typeAttr}><f>${escapeXml(cell.formula)}</f>${valueXml}</c>`;
+}
+
+function serializeFormulaCachedValue(
+  cell: FormulaCell,
+): { typeCode?: string; valueXml?: string } {
+  if (!cell.cachedValue) {
+    return {};
+  }
+
+  switch (cell.cachedValue.type) {
+    case "blank":
+      return {};
+
+    case "number":
+      return { valueXml: formatNumber(cell.cachedValue.value) };
+
+    case "text":
+      return { typeCode: "str", valueXml: escapeXml(cell.cachedValue.value) };
+
+    case "boolean":
+      return { typeCode: "b", valueXml: cell.cachedValue.value ? "1" : "0" };
+
+    case "error":
+      return { typeCode: "e", valueXml: escapeXml(cell.cachedValue.errorCode) };
+  }
+}
+
+function computeDimensionRef(sheet: CanonicalSheet): string {
+  let minRow = Infinity;
+  let minCol = Infinity;
+  let maxRow = -Infinity;
+  let maxCol = -Infinity;
+
+  for (const key of sheet.cells.keys()) {
+    const { row, col } = parseCellKey(key);
+    minRow = Math.min(minRow, row);
+    minCol = Math.min(minCol, col);
+    maxRow = Math.max(maxRow, row);
+    maxCol = Math.max(maxCol, col);
+  }
+
+  for (const merge of sheet.merges) {
+    minRow = Math.min(minRow, merge.startRow);
+    minCol = Math.min(minCol, merge.startCol);
+    maxRow = Math.max(maxRow, merge.endRow);
+    maxCol = Math.max(maxCol, merge.endCol);
+  }
+
+  if (!Number.isFinite(minRow) || !Number.isFinite(minCol)) {
+    return "A1";
+  }
+
+  const start = formatCellRef(minRow, minCol);
+  const end = formatCellRef(maxRow, maxCol);
+  return start === end ? start : `${start}:${end}`;
+}
+
+function formatMergeRef(merge: MergeRange): string {
+  return `${formatCellRef(merge.startRow, merge.startCol)}:${formatCellRef(merge.endRow, merge.endCol)}`;
+}
+
+function formatCellRef(row: number, col: number): string {
+  return `${columnNumberToName(col)}${row + 1}`;
+}
+
+function columnNumberToName(col: number): string {
+  let index = col + 1;
+  let result = "";
+
+  while (index > 0) {
+    const remainder = (index - 1) % 26;
+    result = String.fromCharCode(65 + remainder) + result;
+    index = Math.floor((index - 1) / 26);
+  }
+
+  return result;
+}
+
+function compareCellKeys(left: CellKey, right: CellKey): number {
+  const leftAddress = parseCellKey(left);
+  const rightAddress = parseCellKey(right);
+
+  if (leftAddress.row !== rightAddress.row) {
+    return leftAddress.row - rightAddress.row;
+  }
+
+  return leftAddress.col - rightAddress.col;
+}
+
+function compareMergeRanges(left: MergeRange, right: MergeRange): number {
+  if (left.startRow !== right.startRow) {
+    return left.startRow - right.startRow;
+  }
+  if (left.startCol !== right.startCol) {
+    return left.startCol - right.startCol;
+  }
+  if (left.endRow !== right.endRow) {
+    return left.endRow - right.endRow;
+  }
+  return left.endCol - right.endCol;
+}
+
+function formatNumber(value: number): string {
+  if (!Number.isFinite(value)) {
+    throw new Error(`Cannot serialize non-finite numeric cell value ${value}.`);
+  }
+
+  return String(value);
+}
+
+function requiresPreservedSpace(value: string): boolean {
+  return /^\s/.test(value) || /\s$/.test(value);
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/'/g, "&apos;");
+}