docx-diff-editor 1.0.60 → 1.0.62

package/README.md

@@ -106,7 +106,7 @@ await editor.setSource({ type: 'doc', content: [...] });
 | `onReady` | `() => void` | - | Called when editor is ready |
 | `onSourceLoaded` | `(json) => void` | - | Called when source is loaded |
 | `onComparisonComplete` | `(result) => void` | - | Called after comparison |
-| `onError` | `(error) => void` | - | Called on errors |
+| `onError` | `(error: EditorError) => void` | - | Called on errors (see Error Handling) |
 | `className` | `string` | - | Container class |
 | `toolbarClassName` | `string` | - | Toolbar container class |
 | `editorClassName` | `string` | - | Editor container class |
@@ -119,11 +119,13 @@ await editor.setSource({ type: 'doc', content: [...] });
 ```tsx
 interface DocxDiffEditorRef {
   // Set the source/base document
-  setSource(content: DocxContent): Promise<void>;
+  // Returns void on success, SetSourceError on failure (editor preserved)
+  setSource(content: DocxContent): Promise<void | SetSourceError>;
 
   // Compare current editor content with new content, show track changes
   // Note: Compares against current editor state (not original source)
-  compareWith(content: DocxContent): Promise<ComparisonResult>;
+  // Returns ComparisonResult on success, ComparisonError on failure (editor preserved)
+  compareWith(content: DocxContent): Promise<CompareWithResult>;
 
   // Get diff data
   getDiffSegments(): DiffSegment[];
@@ -165,17 +167,86 @@ interface DocxDiffEditorRef {
 
 ```tsx
 interface ComparisonResult {
+  success: true;                      // Indicates successful comparison
   totalChanges: number;
   insertions: number;
   deletions: number;
   formatChanges: number;
-  structuralChanges: number;          // New: count of structural changes
+  structuralChanges: number;
   summary: string[];
   mergedJson: ProseMirrorJSON;
-  structuralChangeInfos: StructuralChangeInfo[];  // New: metadata for pane
+  structuralChangeInfos: StructuralChangeInfo[];
+  usedFallback?: boolean;             // True if track visualization unavailable
 }
 ```
 
+### Error Handling
+
+The component provides graceful error handling that preserves the editor state on recoverable failures.
+
+#### Error Types
+
+```tsx
+interface EditorError {
+  error: Error;           // The underlying error
+  type: 'fatal' | 'operation';  // Fatal = editor unusable, Operation = editor still works
+  operation?: 'setSource' | 'compareWith' | 'parseHtml' | 'export' | 'init';
+  recoverable: boolean;   // True if editor is still functional
+  message: string;        // Human-readable message
+  phase?: 'parsing' | 'diffing' | 'merging' | 'applying';  // For compareWith
+}
+```
+
+#### Result-Based Error Handling
+
+Both `setSource()` and `compareWith()` return result objects instead of throwing:
+
+```tsx
+// compareWith returns a union type
+const result = await editorRef.current?.compareWith(newContent);
+
+if (!result.success) {
+  // Editor is still intact! Show a friendly message
+  showModal({
+    title: 'Comparison Failed',
+    message: result.message,
+    phase: result.phase,  // 'parsing', 'diffing', 'merging', or 'applying'
+  });
+  return;
+}
+
+// Success - access the usual fields
+console.log(`Found ${result.totalChanges} changes`);
+```
+
+#### Using the onError Callback
+
+```tsx
+<DocxDiffEditor
+  ref={editorRef}
+  onError={(errorInfo) => {
+    if (errorInfo.type === 'fatal') {
+      // Editor is unusable - show full error page or reinitialize
+      console.error('Fatal editor error:', errorInfo.error);
+    } else {
+      // Editor still works - just show a notification
+      toast.error(`${errorInfo.operation} failed: ${errorInfo.message}`);
+    }
+  }}
+/>
+```
+
+#### Recovery Behavior
+
+When operations fail, the component attempts a multi-tier recovery:
+
+1. **Primary**: Apply the requested change
+2. **Fallback**: Try a simpler version (e.g., without track marks)
+3. **Rollback**: Restore the previous editor state
+4. **Fatal**: Only if all recovery attempts fail, show the error overlay
+
+This ensures users don't lose their work due to invalid comparison content or parsing errors.
+
 ### DocumentInfo
 
 ```tsx

package/dist/index.d.mts

@@ -170,9 +170,37 @@ interface StructuralChangeInfo {
     attrChanges?: AttrDiff[];
 }
 /**
- * Result returned after comparing two documents
+ * Operation types that can fail
+ */
+type EditorOperation = 'setSource' | 'compareWith' | 'parseHtml' | 'export' | 'init';
+/**
+ * Phase of compareWith where failure occurred
+ */
+type ComparisonPhase = 'parsing' | 'diffing' | 'merging' | 'applying';
+/**
+ * Enhanced error information passed to onError callback.
+ * Provides context about whether the error is recoverable and what operation failed.
+ */
+interface EditorError {
+    /** The underlying Error object */
+    error: Error;
+    /** Error classification: 'fatal' means editor is unusable, 'operation' means editor is still functional */
+    type: 'fatal' | 'operation';
+    /** Which operation failed */
+    operation?: EditorOperation;
+    /** Whether the editor is still usable after this error */
+    recoverable: boolean;
+    /** Human-readable error message */
+    message: string;
+    /** For compareWith: which phase failed */
+    phase?: ComparisonPhase;
+}
+/**
+ * Successful result returned after comparing two documents
  */
 interface ComparisonResult {
+    /** Indicates successful comparison */
+    success: true;
     /** Total number of changes */
     totalChanges: number;
     /** Number of insertions */
@@ -197,6 +225,25 @@ interface ComparisonResult {
      */
     usedFallback?: boolean;
 }
+/**
+ * Failed comparison result.
+ * Returned when compareWith fails but the editor is still functional.
+ */
+interface ComparisonError {
+    /** Indicates failed comparison */
+    success: false;
+    /** The underlying error */
+    error: Error;
+    /** Human-readable error message */
+    message: string;
+    /** Which phase of comparison failed */
+    phase: ComparisonPhase;
+}
+/**
+ * Union type for compareWith return value.
+ * Check the `success` field to determine which type you have.
+ */
+type CompareWithResult = ComparisonResult | ComparisonError;
 /**
  * Location context for a change
  */
@@ -326,8 +373,17 @@ interface DocxDiffEditorProps {
     onSourceLoaded?: (json: ProseMirrorJSON) => void;
     /** Callback when comparison completes */
     onComparisonComplete?: (result: ComparisonResult) => void;
-    /** Callback on errors */
-    onError?: (error: Error) => void;
+    /**
+     * Callback on errors.
+     *
+     * The EditorError object provides context about the error:
+     * - `type: 'fatal'` - Editor is unusable (overlay will be shown)
+     * - `type: 'operation'` - Operation failed but editor is still functional
+     *
+     * For operation errors, the editor remains visible and usable.
+     * You can use this callback to show a modal or toast notification.
+     */
+    onError?: (error: EditorError) => void;
     /** Container className */
     className?: string;
     /** Toolbar container className */
@@ -341,16 +397,40 @@ interface DocxDiffEditorProps {
     /** Hide structural changes pane entirely (default: false) */
     hideStructuralPane?: boolean;
 }
+/**
+ * Error result for setSource operation
+ */
+interface SetSourceError {
+    /** Indicates failure */
+    success: false;
+    /** The underlying error */
+    error: Error;
+    /** Human-readable error message */
+    message: string;
+}
 /**
  * Ref methods exposed by DocxDiffEditor
  */
 interface DocxDiffEditorRef {
-    /** Set the source/base document (destroys and recreates SuperDoc instance) */
-    setSource(content: DocxContent): Promise<void>;
+    /**
+     * Set the source/base document (destroys and recreates SuperDoc instance).
+     *
+     * On failure, returns an error object instead of throwing. The editor
+     * will attempt to restore the previous state if possible.
+     */
+    setSource(content: DocxContent): Promise<void | SetSourceError>;
     /** Update content in the existing editor without recreating SuperDoc instance */
     updateContent(json: ProseMirrorJSON): void;
-    /** Compare source with new content, show track changes */
-    compareWith(content: DocxContent): Promise<ComparisonResult>;
+    /**
+     * Compare source with new content, show track changes.
+     *
+     * Returns a union type - check `result.success` to determine outcome:
+     * - `success: true` - Comparison succeeded, access result fields
+     * - `success: false` - Comparison failed, editor unchanged, check error
+     *
+     * On failure, the editor is preserved in its previous state.
+     */
+    compareWith(content: DocxContent): Promise<CompareWithResult>;
     /** Get raw diff segments */
     getDiffSegments(): DiffSegment[];
     /** Get enriched changes with context for LLM processing */
@@ -765,4 +845,4 @@ declare function getBlankTemplateBlob(): Blob;
  */
 declare function isValidDocxFile(file: File): boolean;
 
-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 };
+export { type AttrDiff, type AttributeChange, CSS_PREFIX, type ChangeLocation, type CompareWithResult, type ComparisonError, type ComparisonPhase, type ComparisonResult, DEFAULT_AUTHOR, DEFAULT_SUPERDOC_USER, type DiffResult, type DiffSegment, type DocumentInfo, type DocumentProperties, type DocxContent, DocxDiffEditor, type DocxDiffEditorProps, type DocxDiffEditorRef, type EditorError, type EditorOperation, type EnrichedChange, type FingerprintedNode, type FormatChange, type FormatDetails, type HybridDiffResult, type NodeMatch, type ProseMirrorJSON, type ProseMirrorMark, type ProseMirrorNode, type SetSourceError, 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 };

package/dist/index.d.ts

@@ -170,9 +170,37 @@ interface StructuralChangeInfo {
     attrChanges?: AttrDiff[];
 }
 /**
- * Result returned after comparing two documents
+ * Operation types that can fail
+ */
+type EditorOperation = 'setSource' | 'compareWith' | 'parseHtml' | 'export' | 'init';
+/**
+ * Phase of compareWith where failure occurred
+ */
+type ComparisonPhase = 'parsing' | 'diffing' | 'merging' | 'applying';
+/**
+ * Enhanced error information passed to onError callback.
+ * Provides context about whether the error is recoverable and what operation failed.
+ */
+interface EditorError {
+    /** The underlying Error object */
+    error: Error;
+    /** Error classification: 'fatal' means editor is unusable, 'operation' means editor is still functional */
+    type: 'fatal' | 'operation';
+    /** Which operation failed */
+    operation?: EditorOperation;
+    /** Whether the editor is still usable after this error */
+    recoverable: boolean;
+    /** Human-readable error message */
+    message: string;
+    /** For compareWith: which phase failed */
+    phase?: ComparisonPhase;
+}
+/**
+ * Successful result returned after comparing two documents
  */
 interface ComparisonResult {
+    /** Indicates successful comparison */
+    success: true;
     /** Total number of changes */
     totalChanges: number;
     /** Number of insertions */
@@ -197,6 +225,25 @@ interface ComparisonResult {
      */
     usedFallback?: boolean;
 }
+/**
+ * Failed comparison result.
+ * Returned when compareWith fails but the editor is still functional.
+ */
+interface ComparisonError {
+    /** Indicates failed comparison */
+    success: false;
+    /** The underlying error */
+    error: Error;
+    /** Human-readable error message */
+    message: string;
+    /** Which phase of comparison failed */
+    phase: ComparisonPhase;
+}
+/**
+ * Union type for compareWith return value.
+ * Check the `success` field to determine which type you have.
+ */
+type CompareWithResult = ComparisonResult | ComparisonError;
 /**
  * Location context for a change
  */
@@ -326,8 +373,17 @@ interface DocxDiffEditorProps {
     onSourceLoaded?: (json: ProseMirrorJSON) => void;
     /** Callback when comparison completes */
     onComparisonComplete?: (result: ComparisonResult) => void;
-    /** Callback on errors */
-    onError?: (error: Error) => void;
+    /**
+     * Callback on errors.
+     *
+     * The EditorError object provides context about the error:
+     * - `type: 'fatal'` - Editor is unusable (overlay will be shown)
+     * - `type: 'operation'` - Operation failed but editor is still functional
+     *
+     * For operation errors, the editor remains visible and usable.
+     * You can use this callback to show a modal or toast notification.
+     */
+    onError?: (error: EditorError) => void;
     /** Container className */
     className?: string;
     /** Toolbar container className */
@@ -341,16 +397,40 @@ interface DocxDiffEditorProps {
     /** Hide structural changes pane entirely (default: false) */
     hideStructuralPane?: boolean;
 }
+/**
+ * Error result for setSource operation
+ */
+interface SetSourceError {
+    /** Indicates failure */
+    success: false;
+    /** The underlying error */
+    error: Error;
+    /** Human-readable error message */
+    message: string;
+}
 /**
  * Ref methods exposed by DocxDiffEditor
  */
 interface DocxDiffEditorRef {
-    /** Set the source/base document (destroys and recreates SuperDoc instance) */
-    setSource(content: DocxContent): Promise<void>;
+    /**
+     * Set the source/base document (destroys and recreates SuperDoc instance).
+     *
+     * On failure, returns an error object instead of throwing. The editor
+     * will attempt to restore the previous state if possible.
+     */
+    setSource(content: DocxContent): Promise<void | SetSourceError>;
     /** Update content in the existing editor without recreating SuperDoc instance */
     updateContent(json: ProseMirrorJSON): void;
-    /** Compare source with new content, show track changes */
-    compareWith(content: DocxContent): Promise<ComparisonResult>;
+    /**
+     * Compare source with new content, show track changes.
+     *
+     * Returns a union type - check `result.success` to determine outcome:
+     * - `success: true` - Comparison succeeded, access result fields
+     * - `success: false` - Comparison failed, editor unchanged, check error
+     *
+     * On failure, the editor is preserved in its previous state.
+     */
+    compareWith(content: DocxContent): Promise<CompareWithResult>;
     /** Get raw diff segments */
     getDiffSegments(): DiffSegment[];
     /** Get enriched changes with context for LLM processing */
@@ -765,4 +845,4 @@ declare function getBlankTemplateBlob(): Blob;
  */
 declare function isValidDocxFile(file: File): boolean;
 
-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 };
+export { type AttrDiff, type AttributeChange, CSS_PREFIX, type ChangeLocation, type CompareWithResult, type ComparisonError, type ComparisonPhase, type ComparisonResult, DEFAULT_AUTHOR, DEFAULT_SUPERDOC_USER, type DiffResult, type DiffSegment, type DocumentInfo, type DocumentProperties, type DocxContent, DocxDiffEditor, type DocxDiffEditorProps, type DocxDiffEditorRef, type EditorError, type EditorOperation, type EnrichedChange, type FingerprintedNode, type FormatChange, type FormatDetails, type HybridDiffResult, type NodeMatch, type ProseMirrorJSON, type ProseMirrorMark, type ProseMirrorNode, type SetSourceError, 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 };