docx-diff-editor 1.0.40 → 1.0.42

package/README.md

@@ -6,8 +6,10 @@ A React component for DOCX document comparison with track changes visualization.
 
 - 📄 Compare two DOCX documents side by side
 - 🔍 Character-level diff with track changes
+- 📊 **Block-level diffing** for tables, lists, and images
 - ✅ Accept/reject individual changes
 - 🎨 Visual track changes (insert, delete, format)
+- 📋 **Structural Changes Pane** for table rows, list items, images
 - 🤖 Extract enriched change context for LLM processing
 - 📤 Export merged document to DOCX
 
@@ -103,6 +105,9 @@ await editor.setSource({ type: 'doc', content: [...] });
 | `className` | `string` | - | Container class |
 | `toolbarClassName` | `string` | - | Toolbar container class |
 | `editorClassName` | `string` | - | Editor container class |
+| `structuralPanePosition` | `StructuralPanePosition` | `'bottom-right'` | Position of structural changes pane |
+| `structuralPaneCollapsed` | `boolean` | `false` | Start with pane collapsed |
+| `hideStructuralPane` | `boolean` | `false` | Hide structural changes pane entirely |
 
 ### Ref Methods
 
@@ -144,6 +149,9 @@ interface DocxDiffEditorRef {
 
   // Set document core properties (partial update)
   setProperties(properties: Partial<DocumentProperties>): Promise<boolean>;
+
+  // Parse HTML to ProseMirror JSON
+  parseHtml(html: string): Promise<ProseMirrorJSON>;
 }
 ```
 
@@ -155,8 +163,10 @@ interface ComparisonResult {
   insertions: number;
   deletions: number;
   formatChanges: number;
+  structuralChanges: number;          // New: count of structural changes
   summary: string[];
   mergedJson: ProseMirrorJSON;
+  structuralChangeInfos: StructuralChangeInfo[];  // New: metadata for pane
 }
 ```
 
@@ -244,6 +254,23 @@ await editorRef.current?.setProperties({
 });
 ```
 
+## Parsing HTML to JSON
+
+Convert HTML strings to ProseMirror JSON without visible rendering:
+
+```tsx
+// Using the ref method (requires editor to be initialized)
+const json = await editorRef.current?.parseHtml('<h1>Title</h1><p>Content here</p>');
+console.log(json); // { type: 'doc', content: [...] }
+
+// Use with other methods
+await editorRef.current?.updateContent(json);
+
+// Or use the standalone function (requires SuperDoc class)
+import { parseHtmlToJson } from 'docx-diff-editor';
+const json = await parseHtmlToJson(htmlString, SuperDocClass);
+```
+
 ## Customization
 
 ### CSS Variables
@@ -281,6 +308,54 @@ The component supports three types of track changes:
 | **Delete** | Red strikethrough | Text removed |
 | **Format** | Gold highlight | Formatting changed |
 
+## Structural Changes Pane
+
+When comparing documents with structural differences (tables, lists, images), a floating pane appears showing these changes with Accept/Reject controls.
+
+### What's Detected
+
+| Change Type | Description |
+|-------------|-------------|
+| **Table Rows** | Inserted or deleted rows |
+| **Table Columns** | Added or removed columns |
+| **List Items** | New or removed list items (including nested) |
+| **Paragraphs** | Entire paragraphs added or deleted |
+| **Images** | New or removed images |
+
+### Pane Features
+
+- **Floating Position**: Configurable position (`top-right`, `bottom-right`, `top-left`, `bottom-left`)
+- **Collapsible**: Click header to minimize to just the title bar
+- **Accept/Reject**: Per-change or bulk actions
+- **Counter Badge**: Shows remaining changes
+- **Auto-Hide**: Disappears when all changes are resolved
+- **Bubble Sync**: Stays in sync when changes are accepted via SuperDoc's bubbles
+
+### Configuration
+
+```tsx
+<DocxDiffEditor
+  ref={editorRef}
+  structuralPanePosition="bottom-right"  // Position of the pane
+  structuralPaneCollapsed={false}         // Start expanded
+  hideStructuralPane={false}              // Show the pane
+/>
+```
+
+### Accessing Structural Changes Programmatically
+
+```tsx
+const result = await editorRef.current?.compareWith(newDocument);
+
+// Get structural change count
+console.log(`${result.structuralChanges} structural changes detected`);
+
+// Access detailed info
+result.structuralChangeInfos.forEach(change => {
+  console.log(`${change.type}: ${change.location} - ${change.preview}`);
+});
+```
+
 ## License
 
 Apache 2.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import react__default from 'react';
 
 /**
  * Type definitions for DocxDiffEditor
@@ -54,6 +55,114 @@ interface DiffResult {
     /** Human-readable summary */
     summary: string[];
 }
+/**
+ * Type of structural change
+ */
+type StructuralChangeType = 'rowInsert' | 'rowDelete' | 'columnInsert' | 'columnDelete' | 'paragraphInsert' | 'paragraphDelete' | 'listItemInsert' | 'listItemDelete' | 'imageInsert' | 'imageDelete' | 'attrChange';
+/**
+ * A structural change (node added/removed/moved)
+ */
+interface StructuralChange {
+    /** Unique ID shared across all marks in this structural change */
+    id: string;
+    /** Type of structural change */
+    type: StructuralChangeType;
+    /** The node type affected (e.g., 'tableRow', 'paragraph', 'listItem') */
+    nodeType: string;
+    /** Path to the node in the document tree */
+    path: number[];
+    /** The affected node */
+    node: ProseMirrorJSON;
+    /** For moves: original path */
+    fromPath?: number[];
+    /** For moves: new path */
+    toPath?: number[];
+}
+/**
+ * Single attribute difference
+ */
+interface AttrDiff {
+    /** Attribute key (e.g., "borders.top.color") */
+    key: string;
+    /** Value before the change */
+    before: unknown;
+    /** Value after the change */
+    after: unknown;
+}
+/**
+ * An attribute change on a matched node
+ */
+interface AttributeChange {
+    /** Unique ID for this attribute change */
+    id: string;
+    /** The node type affected */
+    nodeType: string;
+    /** Path in original document */
+    pathA: number[];
+    /** Path in new document */
+    pathB: number[];
+    /** List of attribute differences */
+    changes: AttrDiff[];
+}
+/**
+ * Record of matched nodes between documents
+ */
+interface NodeMatch {
+    /** Path in original document */
+    pathA: number[];
+    /** Path in new document */
+    pathB: number[];
+    /** Fingerprint used for matching */
+    fingerprint: string;
+    /** Similarity score (0.0 - 1.0) */
+    similarity: number;
+}
+/**
+ * Node with computed fingerprint (used in alignment)
+ */
+interface FingerprintedNode {
+    /** The original node */
+    node: ProseMirrorJSON;
+    /** Content-based fingerprint */
+    fingerprint: string;
+    /** Path in the document tree */
+    path: number[];
+    /** Child fingerprinted nodes */
+    children?: FingerprintedNode[];
+}
+/**
+ * Extended diff result with structural awareness
+ */
+interface HybridDiffResult extends DiffResult {
+    /** Structural changes (rows, paragraphs, list items added/removed) */
+    structuralChanges: StructuralChange[];
+    /** Attribute changes on matched nodes */
+    attributeChanges: AttributeChange[];
+    /** Node matching information (for debugging) */
+    nodeMatches: NodeMatch[];
+}
+/**
+ * Metadata for the Structural Changes Pane
+ * Generated during merge, stored in component state
+ */
+interface StructuralChangeInfo {
+    /** Shared ID across all marks in this structural change */
+    id: string;
+    /** Type of structural change */
+    type: StructuralChangeType;
+    /** The node type affected */
+    nodeType: string;
+    /** Human-readable location (e.g., "Table 1, Row 3") */
+    location: string;
+    /** Truncated content preview */
+    preview: string;
+    /** Author of the change */
+    author: TrackChangeAuthor;
+    /** ISO timestamp */
+    date: string;
+    /** For attribute changes, the specific diffs */
+    attrChanges?: AttrDiff[];
+}
 /**
  * Result returned after comparing two documents
  */
@@ -66,20 +175,33 @@ interface ComparisonResult {
     deletions: number;
     /** Number of format changes */
     formatChanges: number;
+    /** Number of structural changes (rows, paragraphs, etc.) */
+    structuralChanges: number;
     /** Human-readable summary strings */
     summary: string[];
     /** The merged JSON document with track changes */
     mergedJson: ProseMirrorJSON;
+    /** Metadata for structural changes (for the pane) */
+    structuralChangeInfos: StructuralChangeInfo[];
 }
 /**
  * Location context for a change
  */
 interface ChangeLocation {
-    nodeType: 'heading' | 'paragraph' | 'listItem' | 'tableCell' | 'unknown';
+    nodeType: 'heading' | 'paragraph' | 'listItem' | 'tableCell' | 'table' | 'image' | 'unknown';
     headingLevel?: number;
     paragraphIndex?: number;
     sectionTitle?: string;
     description: string;
+    /** Table coordinates (for table-related changes) */
+    tableCoords?: {
+        row: number;
+        column: number;
+    };
+    /** List item index */
+    listIndex?: number;
+    /** List nesting depth */
+    listDepth?: number;
 }
 /**
  * Format change details
@@ -101,6 +223,20 @@ interface EnrichedChange {
     charCount?: number;
     /** The sentence or clause containing the change */
     surroundingText?: string;
+    /** Structural change type (for block-level changes) */
+    structuralType?: StructuralChangeType;
+    /** Attribute changes (for attribute-only changes) */
+    attributeChanges?: AttrDiff[];
+    /** Table position (for table-related changes) */
+    tablePosition?: {
+        row: number;
+        column: number;
+    };
+    /** List position (for list-related changes) */
+    listPosition?: {
+        index: number;
+        depth: number;
+    };
 }
 /**
  * Author information for track changes
@@ -153,6 +289,10 @@ interface DocumentInfo {
     /** Page count */
     pages: number;
 }
+/**
+ * Position of the structural changes pane
+ */
+type StructuralPanePosition = 'top-right' | 'bottom-right' | 'top-left' | 'bottom-left';
 /**
  * Props for DocxDiffEditor component
  */
@@ -181,6 +321,12 @@ interface DocxDiffEditorProps {
     toolbarClassName?: string;
     /** Editor container className */
     editorClassName?: string;
+    /** Position of structural changes pane (default: 'bottom-right') */
+    structuralPanePosition?: StructuralPanePosition;
+    /** Start with pane collapsed (default: false) */
+    structuralPaneCollapsed?: boolean;
+    /** Hide structural changes pane entirely (default: false) */
+    hideStructuralPane?: boolean;
 }
 /**
  * Ref methods exposed by DocxDiffEditor
@@ -216,6 +362,8 @@ interface DocxDiffEditorRef {
     getProperties(): Promise<DocumentProperties | null>;
     /** Set document core properties (partial update) */
     setProperties(properties: Partial<DocumentProperties>): Promise<boolean>;
+    /** Parse HTML string to ProseMirror JSON (uses hidden SuperDoc instance) */
+    parseHtml(html: string): Promise<ProseMirrorJSON>;
 }
 
 /**
@@ -223,6 +371,38 @@ interface DocxDiffEditorRef {
  */
 declare const DocxDiffEditor: react.ForwardRefExoticComponent<DocxDiffEditorProps & react.RefAttributes<DocxDiffEditorRef>>;
 
+/**
+ * Structural Changes Pane Component
+ *
+ * A floating, collapsible panel that displays structural changes
+ * (table rows, list items, images, etc.) with Accept/Reject controls.
+ *
+ * Uses SuperDoc's acceptTrackedChangeById/rejectTrackedChangeById commands
+ * to handle accept/reject actions.
+ */
+
+interface StructuralChangesPaneProps {
+    /** Array of structural changes to display */
+    changes: StructuralChangeInfo[];
+    /** Position of the pane */
+    position?: StructuralPanePosition;
+    /** Start collapsed? */
+    initiallyCollapsed?: boolean;
+    /** Callback when a change is accepted */
+    onAccept: (changeId: string) => void;
+    /** Callback when a change is rejected */
+    onReject: (changeId: string) => void;
+    /** Callback when Accept All is clicked */
+    onAcceptAll: () => void;
+    /** Callback when Reject All is clicked */
+    onRejectAll: () => void;
+    /** Callback when a change is clicked (for navigation) */
+    onNavigate?: (changeId: string) => void;
+    /** Callback when pane is dismissed */
+    onDismiss?: () => void;
+}
+declare const StructuralChangesPane: react__default.FC<StructuralChangesPaneProps>;
+
 /**
  * Content Resolver Service
  * Detects content type and parses DOCX files to ProseMirror JSON.
@@ -242,6 +422,10 @@ declare function detectContentType(content: DocxContent): 'file' | 'html' | 'jso
  * Validate that content looks like ProseMirror JSON
  */
 declare function isProseMirrorJSON(content: unknown): boolean;
+/**
+ * Parse an HTML string into ProseMirror JSON using a hidden SuperDoc instance.
+ */
+declare function parseHtmlToJson(html: string, SuperDoc: SuperDocConstructor): Promise<ProseMirrorJSON>;
 /**
  * Parse a DOCX File into ProseMirror JSON using a hidden SuperDoc instance.
  */
@@ -303,12 +487,181 @@ declare function createTrackFormatMark(before: ProseMirrorMark[], after: ProseMi
  * Change Context Extractor
  * Extracts enriched changes with semantic context from merged document.
  * Provides surrounding text so the LLM can understand what the change is about.
+ *
+ * Updated to include structural change information (tables, lists, images).
  */
 
 /**
  * Main entry point - extract enriched changes from merged document
  */
 declare function extractEnrichedChanges(mergedJson: ProseMirrorJSON): EnrichedChange[];
+/**
+ * Extract enriched changes with structural change infos included.
+ * This merges inline text changes with structural change metadata.
+ */
+declare function extractEnrichedChangesWithStructural(mergedJson: ProseMirrorJSON, structuralInfos: StructuralChangeInfo[]): EnrichedChange[];
+
+/**
+ * Node Fingerprint Service
+ *
+ * Generates content-based fingerprints for ProseMirror nodes.
+ * Fingerprints are used to match nodes between documents during diffing.
+ *
+ * Key principle: Two nodes with the same content (ignoring styles/attrs)
+ * should produce the same or similar fingerprints.
+ */
+
+/**
+ * Generate a fingerprint for a single node.
+ *
+ * Fingerprint format by node type:
+ * - text: "t:{hash}"
+ * - paragraph: "p:{hash}"
+ * - heading: "h{level}:{hash}"
+ * - table: "table:{rowCount}:{hash}"
+ * - tableRow: "tr:{cellCount}:{hash}"
+ * - tableCell: "tc:{hash}"
+ * - listItem: "li:{hash}"
+ * - image: "img:{srcHash}"
+ * - hardBreak: "br"
+ * - horizontalRule: "hr"
+ * - other: "{type}:{hash}"
+ */
+declare function generateFingerprint(node: ProseMirrorJSON): string;
+
+/**
+ * Node Aligner Service
+ *
+ * Aligns nodes between two documents using fingerprints and LCS algorithm.
+ * Produces matched pairs, insertions, and deletions.
+ */
+
+/**
+ * Result of aligning two node sequences
+ */
+interface AlignmentResult {
+    /** Nodes that match between documents */
+    matched: NodeMatch[];
+    /** Nodes only in document A (deleted) */
+    deletions: FingerprintedNode[];
+    /** Nodes only in document B (inserted) */
+    insertions: FingerprintedNode[];
+}
+/**
+ * Align top-level blocks between two documents.
+ */
+declare function alignDocuments(docA: ProseMirrorJSON, docB: ProseMirrorJSON): AlignmentResult;
+
+/**
+ * Table Block Differ Service
+ *
+ * Specialized diffing logic for tables:
+ * - Row insertions/deletions
+ * - Column insertions/deletions
+ * - Cell-level content changes
+ * - Table/cell attribute changes
+ */
+
+/**
+ * Result of diffing two tables
+ */
+interface TableDiffResult {
+    /** Row-level structural changes */
+    rowChanges: StructuralChange[];
+    /** Column-level structural changes (detected from cell patterns) */
+    columnChanges: StructuralChange[];
+    /** Cell-level matches for content diffing */
+    cellMatches: NodeMatch[];
+    /** Attribute changes on the table itself */
+    tableAttrChanges: AttributeChange | null;
+    /** Attribute changes on cells */
+    cellAttrChanges: AttributeChange[];
+}
+/**
+ * Diff two tables and return all detected changes.
+ */
+declare function diffTables(tableA: ProseMirrorJSON, tableB: ProseMirrorJSON, tablePathA: number[], tablePathB: number[]): TableDiffResult;
+/**
+ * Check if a node is a table.
+ */
+declare function isTable(node: ProseMirrorJSON): boolean;
+
+/**
+ * List Block Differ Service
+ *
+ * Specialized diffing logic for lists:
+ * - List item insertions/deletions
+ * - List item reordering detection
+ * - Nested list handling
+ */
+
+/**
+ * Result of diffing two lists
+ */
+interface ListDiffResult {
+    /** Item-level structural changes */
+    itemChanges: StructuralChange[];
+    /** Item matches for content diffing */
+    itemMatches: NodeMatch[];
+    /** Nested list changes (recursive) */
+    nestedChanges: ListDiffResult[];
+}
+/**
+ * Check if a node is a list (ordered or unordered).
+ */
+declare function isList(node: ProseMirrorJSON): boolean;
+/**
+ * Diff two lists and return all detected changes.
+ */
+declare function diffLists(listA: ProseMirrorJSON, listB: ProseMirrorJSON, listPathA: number[], listPathB: number[], depth?: number): ListDiffResult;
+
+/**
+ * Non-Text Node Differ Service
+ *
+ * Handles diffing of atomic non-text nodes:
+ * - Images
+ * - Horizontal rules
+ * - Page breaks
+ * - Embedded objects (equations, etc.)
+ */
+
+/**
+ * Check if a node is an image.
+ */
+declare function isImage(node: ProseMirrorJSON): boolean;
+/**
+ * Check if a node is an atomic (non-text, leaf) node.
+ */
+declare function isAtomicNode(node: ProseMirrorJSON): boolean;
+/**
+ * Diff images between two documents.
+ */
+declare function diffImages(docA: ProseMirrorJSON, docB: ProseMirrorJSON): {
+    inserted: StructuralChange[];
+    deleted: StructuralChange[];
+};
+
+/**
+ * Block Level Merger Service
+ *
+ * Handles merging of structural changes (tables, lists, images)
+ * with shared IDs for all marks within a structural change.
+ *
+ * This allows the Structural Changes Pane to accept/reject
+ * entire structural units (e.g., a whole table row) with a single action.
+ */
+
+/**
+ * Process structural changes and generate marked blocks with shared IDs.
+ */
+declare function processStructuralChanges(docA: ProseMirrorNode, docB: ProseMirrorNode, author?: TrackChangeAuthor): {
+    changes: StructuralChange[];
+    infos: StructuralChangeInfo[];
+};
+/**
+ * Generate a summary of structural changes.
+ */
+declare function generateStructuralChangeSummary(infos: StructuralChangeInfo[]): string[];
 
 /**
  * Constants for DocxDiffEditor
@@ -363,4 +716,4 @@ declare function getBlankTemplateBlob(): Blob;
  */
 declare function isValidDocxFile(file: File): boolean;
 
-export { CSS_PREFIX, type ChangeLocation, type ComparisonResult, DEFAULT_AUTHOR, DEFAULT_SUPERDOC_USER, type DiffResult, type DiffSegment, type DocumentInfo, type DocumentProperties, type DocxContent, DocxDiffEditor, type DocxDiffEditorProps, type DocxDiffEditorRef, type EnrichedChange, type FormatChange, type FormatDetails, type ProseMirrorJSON, type ProseMirrorMark, type ProseMirrorNode, type TrackChangeAuthor, createTrackDeleteMark, createTrackFormatMark, createTrackInsertMark, DocxDiffEditor as default, detectContentType, diffDocuments, extractEnrichedChanges, getBlankTemplateBlob, getBlankTemplateFile, isProseMirrorJSON, isValidDocxFile, mergeDocuments, parseDocxFile };
+export { type AttrDiff, type AttributeChange, CSS_PREFIX, type ChangeLocation, type ComparisonResult, DEFAULT_AUTHOR, DEFAULT_SUPERDOC_USER, type DiffResult, type DiffSegment, type DocumentInfo, type DocumentProperties, type DocxContent, DocxDiffEditor, type DocxDiffEditorProps, type DocxDiffEditorRef, type EnrichedChange, type FingerprintedNode, type FormatChange, type FormatDetails, type HybridDiffResult, type NodeMatch, type ProseMirrorJSON, type ProseMirrorMark, type ProseMirrorNode, type StructuralChange, type StructuralChangeInfo, type StructuralChangeType, StructuralChangesPane, type StructuralPanePosition, type TrackChangeAuthor, alignDocuments, createTrackDeleteMark, createTrackFormatMark, createTrackInsertMark, DocxDiffEditor as default, detectContentType, diffDocuments, diffImages, diffLists, diffTables, extractEnrichedChanges, extractEnrichedChangesWithStructural, generateFingerprint, generateStructuralChangeSummary, getBlankTemplateBlob, getBlankTemplateFile, isAtomicNode, isImage, isList, isProseMirrorJSON, isTable, isValidDocxFile, mergeDocuments, parseDocxFile, parseHtmlToJson, processStructuralChanges };