@beyondwork/docx-react-component 1.0.14 → 1.0.16

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
+  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -33,10 +34,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"
@@ -45,6 +54,29 @@
     "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  },
   "keywords": [
     "docx",
     "word",
@@ -90,7 +122,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",
@@ -107,27 +139,14 @@
     "tsup": "^8.3.0",
     "tsx": "^4.21.0"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
 }

package/src/api/public-types.ts

@@ -125,6 +125,13 @@ export interface TrackedChangesSnapshot {
 
 export type FormattingAlignment = "left" | "center" | "right" | "justify";
 
+export interface FormattingBreadcrumbItem {
+  kind: "table" | "table_row" | "table_cell" | "paragraph" | "sdt_block" | "opaque_block";
+  label: string;
+  from: number;
+  to: number;
+}
+
 export interface FormattingStateSnapshot {
   bold: boolean;
   italic: boolean;
@@ -137,6 +144,7 @@ export interface FormattingStateSnapshot {
   textColor?: string;
   highlightColor?: string | null;
   alignment?: FormattingAlignment;
+  breadcrumb: FormattingBreadcrumbItem[];
 }
 
 export interface SearchOptions {
@@ -571,17 +579,23 @@ 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;
+  replaceText(text: string, target?: EditorAnchorProjection): void;
   toggleBold(): void;
   toggleItalic(): void;
   toggleUnderline(): void;
@@ -610,6 +624,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/core/commands/formatting-commands.ts

@@ -21,12 +21,14 @@ import type { Command } from "prosemirror-state";
 import type { MarkType, Schema } from "prosemirror-model";
 
 import type {
+  FormattingBreadcrumbItem,
   FormattingAlignment,
   FormattingStateSnapshot,
   PersistedEditorSnapshot,
   RuntimeRenderSnapshot,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
+  SurfaceTableCellSnapshot,
 } from "../../api/public-types";
 import type {
   BlockNode,
@@ -209,6 +211,7 @@ const DEFAULT_FORMATTING_STATE: FormattingStateSnapshot = {
   strikethrough: false,
   superscript: false,
   subscript: false,
+  breadcrumb: [],
 };
 
 const INDENT_STEP_TWIPS = 720;
@@ -268,9 +271,231 @@ export function getFormattingStateFromRenderSnapshot(
     alignment: getConsistentValue(paragraphs, (paragraph) =>
       toPublicAlignment(paragraph.alignment),
     ),
+    breadcrumb: getSelectionBreadcrumb(surface.blocks, snapshot.selection),
   };
 }
 
+function getSelectionBreadcrumb(
+  blocks: SurfaceBlockSnapshot[],
+  selection: RuntimeRenderSnapshot["selection"],
+): FormattingBreadcrumbItem[] {
+  const paths = collectSelectionBreadcrumbPaths(blocks, selection);
+  if (paths.length === 0) {
+    return [];
+  }
+
+  let commonLength = paths[0]?.length ?? 0;
+  for (let pathIndex = 1; pathIndex < paths.length; pathIndex += 1) {
+    const currentPath = paths[pathIndex] ?? [];
+    commonLength = Math.min(commonLength, currentPath.length);
+
+    let compareIndex = 0;
+    while (
+      compareIndex < commonLength &&
+      breadcrumbItemsEqual(paths[0]![compareIndex]!, currentPath[compareIndex]!)
+    ) {
+      compareIndex += 1;
+    }
+    commonLength = compareIndex;
+  }
+
+  return paths[0]!.slice(0, commonLength);
+}
+
+function collectSelectionBreadcrumbPaths(
+  blocks: SurfaceBlockSnapshot[],
+  selection: RuntimeRenderSnapshot["selection"],
+  path: FormattingBreadcrumbItem[] = [],
+  output: FormattingBreadcrumbItem[][] = [],
+): FormattingBreadcrumbItem[][] {
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
+    const block = blocks[blockIndex];
+    if (!block) {
+      continue;
+    }
+
+    if (
+      !selectionTouchesRange(
+        selection.anchor,
+        selection.head,
+        block.from,
+        block.to,
+      )
+    ) {
+      continue;
+    }
+
+    if (block.kind === "paragraph") {
+      output.push([
+        ...path,
+        {
+          kind: "paragraph" as const,
+          label: block.styleId ? `Paragraph (${block.styleId})` : "Paragraph",
+          from: block.from,
+          to: block.to,
+        },
+      ]);
+      continue;
+    }
+
+    if (block.kind === "opaque_block") {
+      output.push([
+        ...path,
+        {
+          kind: "opaque_block" as const,
+          label: block.label,
+          from: block.from,
+          to: block.to,
+        },
+      ]);
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      collectSelectionBreadcrumbPaths(
+        block.children,
+        selection,
+        [
+          ...path,
+          {
+            kind: "sdt_block" as const,
+            label: block.alias ?? block.tag ?? block.sdtType ?? "Content control",
+            from: block.from,
+            to: block.to,
+          },
+        ],
+        output,
+      );
+      continue;
+    }
+
+    if (block.kind === "table") {
+      const tablePath = [
+        ...path,
+        {
+          kind: "table" as const,
+          label: block.styleId ? `Table (${block.styleId})` : "Table",
+          from: block.from,
+          to: block.to,
+        },
+      ];
+
+      for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+        const row = block.rows[rowIndex];
+        if (!row) {
+          continue;
+        }
+        const rowRange = getTableRowRange(block, row);
+        if (
+          !selectionTouchesRange(
+            selection.anchor,
+            selection.head,
+            rowRange.from,
+            rowRange.to,
+          )
+        ) {
+          continue;
+        }
+
+        const rowPath = [
+          ...tablePath,
+          {
+            kind: "table_row" as const,
+            label: `Row ${rowIndex + 1}`,
+            from: rowRange.from,
+            to: rowRange.to,
+          },
+        ];
+
+        for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+          const cell = row.cells[cellIndex];
+          if (!cell) {
+            continue;
+          }
+          const cellRange = getTableCellRange(block, cell);
+          if (
+            !selectionTouchesRange(
+              selection.anchor,
+              selection.head,
+              cellRange.from,
+              cellRange.to,
+            )
+          ) {
+            continue;
+          }
+
+          collectSelectionBreadcrumbPaths(
+            cell.content,
+            selection,
+            [
+              ...rowPath,
+              {
+                kind: "table_cell",
+                label: `Cell ${cellIndex + 1}`,
+                from: cellRange.from,
+                to: cellRange.to,
+              },
+            ],
+            output,
+          );
+        }
+      }
+    }
+  }
+
+  return output;
+}
+
+function getTableRowRange(
+  table: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+  row: (typeof table.rows)[number],
+): { from: number; to: number } {
+  let from = Number.POSITIVE_INFINITY;
+  let to = Number.NEGATIVE_INFINITY;
+
+  for (const cell of row.cells) {
+    const range = getTableCellRange(table, cell);
+    from = Math.min(from, range.from);
+    to = Math.max(to, range.to);
+  }
+
+  return Number.isFinite(from) && Number.isFinite(to)
+    ? { from, to }
+    : { from: table.from, to: table.to };
+}
+
+function getTableCellRange(
+  table: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+  cell: SurfaceTableCellSnapshot,
+): { from: number; to: number } {
+  if (cell.content.length === 0) {
+    return { from: table.from, to: table.to };
+  }
+
+  let from = Number.POSITIVE_INFINITY;
+  let to = Number.NEGATIVE_INFINITY;
+  for (const child of cell.content) {
+    from = Math.min(from, child.from);
+    to = Math.max(to, child.to);
+  }
+
+  return Number.isFinite(from) && Number.isFinite(to)
+    ? { from, to }
+    : { from: table.from, to: table.to };
+}
+
+function breadcrumbItemsEqual(
+  left: FormattingBreadcrumbItem,
+  right: FormattingBreadcrumbItem,
+): boolean {
+  return (
+    left.kind === right.kind &&
+    left.label === right.label &&
+    left.from === right.from &&
+    left.to === right.to
+  );
+}
+
 export function applyFormattingOperationToDocument(
   document: CanonicalDocumentEnvelope,
   snapshot: RuntimeRenderSnapshot,

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;");
+}