@createiq/htmldiff 1.0.4 → 1.0.5-beta.0

package/src/HtmlDiff.ts

@@ -80,8 +80,17 @@ export default class HtmlDiff {
   /** Maps content-word index → original word index */
   private oldContentToOriginal: number[] | null = null
   private newContentToOriginal: number[] | null = null
-  /** Tracks the last original old word index output, so equal operations can include leading structural tags */
+  /**
+   * Tracks the next unwritten word index in oldWords/newWords. Mutated only by
+   * {@link sliceOriginalWordsForOp} (each op reads a slice and advances its cursor).
+   * Advances monotonically. Used so:
+   *   - subsequent equal/delete ops know where in old to resume from
+   *   - subsequent insert ops know where in new to resume from
+   * The two cursors are independent: equal/delete output from old and advance the old
+   * cursor; insert outputs from new and advances the new cursor.
+   */
   private lastOriginalOldOutputIndex = 0
+  private lastOriginalNewOutputIndex = 0
   private matchGranularity = 0
   private blockExpressions: RegExp[] = []
 
@@ -185,23 +194,18 @@ export default class HtmlDiff {
   }
 
   /**
-   * Checks whether the two word arrays have structural HTML differences (different non-formatting tags
-   * or different whitespace between structural tags). When they do, builds "content projections" that
-   * strip structural noise so the diff algorithm only sees meaningful content and formatting changes.
+   * Builds "content projections" — word arrays with structural wrapper tags stripped — when
+   * structural normalization is appropriate for these inputs. The diff algorithm operates on
+   * the projections so wrapper-tag differences (e.g. `<p>` vs `<div>`) don't appear as content
+   * changes; structural tags are then folded back in at output time.
    */
   private buildContentProjections() {
-    // Only use projections if the structural tags actually differ.
-    // If structural tags are the same, the normal diff works fine and is simpler.
-    if (!HtmlDiff.hasStructuralDifferences(this.oldWords, this.newWords)) {
-      return
-    }
+    if (!HtmlDiff.hasStructuralDifferences(this.oldWords, this.newWords)) return
 
     const oldProjection = HtmlDiff.createContentProjection(this.oldWords)
     const newProjection = HtmlDiff.createContentProjection(this.newWords)
 
-    // Don't activate structural normalization when one side has no content —
-    // that's a genuine addition/deletion, not a re-wrapping scenario.
-    if (oldProjection.contentWords.length === 0 || newProjection.contentWords.length === 0) {
+    if (!HtmlDiff.shouldUseContentProjections(this.oldWords, this.newWords, oldProjection, newProjection)) {
       return
     }
 
@@ -211,6 +215,32 @@ export default class HtmlDiff {
     this.newContentToOriginal = newProjection.contentToOriginal
   }
 
+  /**
+   * Decides whether structural normalization should be activated for this pair of inputs.
+   * Each clause is a distinct correctness or fitness check — extend by adding a named
+   * sub-predicate rather than chaining ad-hoc conditions.
+   */
+  private static shouldUseContentProjections(
+    oldWords: string[],
+    newWords: string[],
+    oldProjection: { contentWords: string[]; contentToOriginal: number[] },
+    newProjection: { contentWords: string[]; contentToOriginal: number[] }
+  ): boolean {
+    // One side has no content at all: that's a genuine addition/deletion, not a wrapper rename.
+    // Normalization would mis-attribute the wrappers as part of the diff.
+    if (oldProjection.contentWords.length === 0 || newProjection.contentWords.length === 0) return false
+
+    // Asymmetric structural state: one side has no structural wrappers at all (e.g. plain text
+    // vs. wrapped HTML). Normalization would force the equal output to use the unwrapped side's
+    // (missing) structure and emit dangling closing tags from the wrapped side. The plain
+    // word-level diff handles this correctly without normalization.
+    const oldHasStructuralTags = oldProjection.contentWords.length < oldWords.length
+    const newHasStructuralTags = newProjection.contentWords.length < newWords.length
+    if (oldHasStructuralTags !== newHasStructuralTags) return false
+
+    return true
+  }
+
   /**
    * Tags that commonly serve as content wrappers and may change structurally
    * without affecting the actual content. Only these tags are stripped during
@@ -224,6 +254,11 @@ export default class HtmlDiff {
     return HtmlDiff.WrapperTags.has(tagName)
   }
 
+  /** True when the word is a structural opening tag (e.g. `<p>`, `<div>`). */
+  private static isOpeningStructuralTag(word: string): boolean {
+    return HtmlDiff.isStructuralTag(word) && !word.startsWith('</')
+  }
+
   /**
    * Returns true if words between structural tags are just whitespace (indentation).
    */
@@ -303,84 +338,90 @@ export default class HtmlDiff {
   }
 
   private processInsertOperation(operation: Operation, cssClass: string) {
-    const words = this.oldContentWords
-      ? this.getOriginalNewWords(operation.startInNew, operation.endInNew)
+    const words = this.usingContentProjections()
+      ? this.sliceOriginalWordsForOp('new', operation.startInNew, operation.endInNew)
       : this.newWords.slice(operation.startInNew, operation.endInNew)
     this.insertTag(HtmlDiff.InsTag, cssClass, words)
   }
 
   private processDeleteOperation(operation: Operation, cssClass: string) {
-    const words = this.oldContentWords
-      ? this.getOriginalOldWords(operation.startInOld, operation.endInOld)
+    const words = this.usingContentProjections()
+      ? this.sliceOriginalWordsForOp('old', operation.startInOld, operation.endInOld)
       : this.oldWords.slice(operation.startInOld, operation.endInOld)
     this.insertTag(HtmlDiff.DelTag, cssClass, words)
-
-    // Advance the tracking index past the deleted range so subsequent equal operations
-    // don't re-include structural tags from the deleted section.
-    if (this.oldContentToOriginal && operation.endInOld > 0) {
-      const lastDeletedOrigIdx = this.oldContentToOriginal[operation.endInOld - 1]
-      this.lastOriginalOldOutputIndex = Math.max(this.lastOriginalOldOutputIndex, lastDeletedOrigIdx + 1)
-    }
   }
 
   private processEqualOperation(operation: Operation) {
-    if (this.oldContentWords) {
-      // When using content projections, output from old original words to preserve old structure
-      const result = this.getOriginalOldWordsWithStructure(operation.startInOld, operation.endInOld)
+    if (this.usingContentProjections()) {
+      // Output from old to preserve old's HTML structure for the matched content.
+      const result = this.sliceOriginalWordsForOp('old', operation.startInOld, operation.endInOld)
       this.content.push(result.join(''))
+
+      // Advance new-side tracking past the equivalent range in new so the next insert op
+      // resumes from the correct position. We compute new's range with the same rule used
+      // for old (rather than mirroring old's count) so the two sides are independently sound
+      // when their structural tags don't perfectly parallel each other.
+      this.sliceOriginalWordsForOp('new', operation.startInNew, operation.endInNew)
     } else {
       const result = this.newWords.slice(operation.startInNew, operation.endInNew)
       this.content.push(result.join(''))
     }
   }
 
-  /**
-   * Gets original old words for a content-index range, including only content and formatting tags
-   * (used for delete/replace operations where we don't want structural tags).
-   */
-  private getOriginalOldWords(contentStart: number, contentEnd: number): string[] {
-    if (!this.oldContentToOriginal) return this.oldWords.slice(contentStart, contentEnd)
-    const result: string[] = []
-    for (let i = contentStart; i < contentEnd; i++) {
-      result.push(this.oldWords[this.oldContentToOriginal[i]])
-    }
-    return result
+  /** True when content projections are active for both sides — i.e. structural normalization is in effect. */
+  private usingContentProjections(): boolean {
+    return this.oldContentToOriginal !== null && this.newContentToOriginal !== null
   }
 
   /**
-   * Gets original new words for a content-index range, including only content and formatting tags
-   * (used for insert/replace operations where we don't want structural tags).
+   * Returns the slice of original (old or new) words covering a content-index range,
+   * including the structural tags that surround the content. Advances the side's cursor
+   * past the slice so the next op resumes correctly.
+   *
+   * The slice extends:
+   *   - LEADING: from the side's cursor (or the first content word's original index,
+   *     whichever is smaller) so structural tags that precede the first content word
+   *     are picked up by this op rather than left orphaned.
+   *   - TRAILING (non-last range): from just after the last content word, including
+   *     closing structural tags that close *this* op's paragraphs, but stopping at
+   *     the first opening structural tag — that opening tag belongs to the next
+   *     op's paragraph and would otherwise be emitted twice.
+   *   - TRAILING (last range): all the way to the end of words, since there is no next
+   *     op to claim the trailing tags.
    */
-  private getOriginalNewWords(contentStart: number, contentEnd: number): string[] {
-    if (!this.newContentToOriginal) return this.newWords.slice(contentStart, contentEnd)
-    const result: string[] = []
-    for (let i = contentStart; i < contentEnd; i++) {
-      result.push(this.newWords[this.newContentToOriginal[i]])
-    }
-    return result
-  }
+  private sliceOriginalWordsForOp(side: 'old' | 'new', contentStart: number, contentEnd: number): string[] {
+    const words = side === 'old' ? this.oldWords : this.newWords
+    const contentToOriginal = side === 'old' ? this.oldContentToOriginal : this.newContentToOriginal
 
-  /**
-   * Gets original old words for a content-index range, INCLUDING structural tags and whitespace
-   * between the content words (used for equal operations to preserve old HTML structure).
-   */
-  private getOriginalOldWordsWithStructure(contentStart: number, contentEnd: number): string[] {
-    if (!this.oldContentToOriginal) return this.oldWords.slice(contentStart, contentEnd)
+    if (!contentToOriginal) return words.slice(contentStart, contentEnd)
     if (contentStart >= contentEnd) return []
 
-    // Start from where we last left off in the original array (or the first content word's
-    // original index, whichever is smaller) to include any structural tags that precede
-    // the content words in this range.
-    const firstContentOrigIdx = this.oldContentToOriginal[contentStart]
-    const origStart = Math.min(this.lastOriginalOldOutputIndex, firstContentOrigIdx)
+    const firstContentOrigIdx = contentToOriginal[contentStart]
+    const lastContentOrigIdx = contentToOriginal[contentEnd - 1]
+    const cursor = side === 'old' ? this.lastOriginalOldOutputIndex : this.lastOriginalNewOutputIndex
+    const origStart = Math.min(cursor, firstContentOrigIdx)
+
+    let origEnd: number
+    if (contentEnd < contentToOriginal.length) {
+      // Non-last range: walk trailing tags after the last content word, stopping at the
+      // first opening structural tag so it can be emitted by the next op.
+      const limit = contentToOriginal[contentEnd]
+      origEnd = lastContentOrigIdx + 1
+      while (origEnd < limit && !HtmlDiff.isOpeningStructuralTag(words[origEnd])) {
+        origEnd++
+      }
+    } else {
+      // Last range: include everything to the end.
+      origEnd = words.length
+    }
 
-    // Include up to (but not including) the next content word's original index,
-    // or to the end of oldWords if this is the last content range
-    const origEnd =
-      contentEnd < this.oldContentToOriginal.length ? this.oldContentToOriginal[contentEnd] : this.oldWords.length
+    if (side === 'old') {
+      this.lastOriginalOldOutputIndex = origEnd
+    } else {
+      this.lastOriginalNewOutputIndex = origEnd
+    }
 
-    this.lastOriginalOldOutputIndex = origEnd
-    return this.oldWords.slice(origStart, origEnd)
+    return words.slice(origStart, origEnd)
   }
 
   /**

package/test/HtmlDiff.spec.ts

@@ -339,4 +339,122 @@ describe('HtmlDiff', () => {
       )
     ).toEqual(`<div data-html="bar">Some<ins class='diffins'>&nbsp;different</ins> text here</div>`)
   })
+
+  it('should keep added paragraphs as separate <p> blocks instead of concatenating their content', () => {
+    // When new content adds extra paragraphs alongside an existing one, structural
+    // normalization currently strips the wrappers and emits the added content as a
+    // single concatenated <ins> ("BoopShoop"). Each added paragraph should remain
+    // its own <p> so they render on separate lines.
+    expect(HtmlDiff.execute('<p>shared</p>', '<p>shared</p><p>Boop</p><p>Shoop</p>')).toEqual(
+      `<p>shared</p><p><ins class='diffins'>Boop</ins></p><p><ins class='diffins'>Shoop</ins></p>`
+    )
+  })
+
+  it('should keep removed paragraphs as separate <p> blocks instead of concatenating their content', () => {
+    expect(HtmlDiff.execute('<p>shared</p><p>Boop</p><p>Shoop</p>', '<p>shared</p>')).toEqual(
+      `<p>shared</p><p><del class='diffdel'>Boop</del></p><p><del class='diffdel'>Shoop</del></p>`
+    )
+  })
+
+  it('should keep an added paragraph distinct from the preceding paragraph', () => {
+    // The compare-bubble regression: a single added <p>Boop</p> after a modified
+    // paragraph used to collapse onto the same line as "discovered." because the
+    // <p> wrapper was stripped from the inserted content.
+    expect(
+      HtmlDiff.execute(
+        '<p>Shared content has extra removed has been discovered.</p>',
+        '<p>Shared content has been discovered.</p><p>Boop</p>'
+      )
+    ).toEqual(
+      `<p>Shared content<del class='diffdel'>&nbsp;has extra removed</del> has been discovered.</p><p><ins class='diffins'>Boop</ins></p>`
+    )
+  })
+
+  it('should preserve new wrappers when old is plain text and new is wrapped', () => {
+    // Asymmetric structure case: when one side has no structural wrappers at all,
+    // normalization would produce dangling tags. We disable it for this case so the
+    // word-level diff can correctly emit new's structural wrappers around the diff.
+    expect(HtmlDiff.execute('X with extra', '<p>X</p><p>Boop</p>')).toEqual(
+      `<p>X<del class='diffmod'>&nbsp;with extra</del></p><p><ins class='diffmod'>Boop</ins></p>`
+    )
+  })
+
+  it('should preserve new wrappers when old is plain text spanning multiple paragraphs in new', () => {
+    expect(
+      HtmlDiff.execute(
+        'Shared content has extra removed has been discovered.',
+        '<div><p>Shared content has been discovered.</p><p>Boop</p></div>'
+      )
+    ).toEqual(
+      `<div><p>Shared content<del class='diffdel'>&nbsp;has extra removed</del> has been discovered.</p><p><ins class='diffins'>Boop</ins></p></div>`
+    )
+  })
+
+  it('should keep a paragraph added in the middle as its own block', () => {
+    expect(HtmlDiff.execute('<p>A</p><p>C</p>', '<p>A</p><p>B</p><p>C</p>')).toEqual(
+      `<p>A</p><p><ins class='diffins'>B</ins></p><p>C</p>`
+    )
+  })
+
+  it('should keep a paragraph added at the start as its own block', () => {
+    expect(HtmlDiff.execute('<p>B</p>', '<p>A</p><p>B</p>')).toEqual(`<p><ins class='diffins'>A</ins></p><p>B</p>`)
+  })
+
+  it('should keep multiple paragraphs added at the start as separate blocks', () => {
+    expect(HtmlDiff.execute('<p>C</p>', '<p>A</p><p>B</p><p>C</p>')).toEqual(
+      `<p><ins class='diffins'>A</ins></p><p><ins class='diffins'>B</ins></p><p>C</p>`
+    )
+  })
+
+  it('should keep a paragraph removed from the start as its own block', () => {
+    expect(HtmlDiff.execute('<p>A</p><p>B</p>', '<p>B</p>')).toEqual(`<p><del class='diffdel'>A</del></p><p>B</p>`)
+  })
+
+  it('should keep a paragraph removed from the middle as its own block', () => {
+    expect(HtmlDiff.execute('<p>A</p><p>B</p><p>C</p>', '<p>A</p><p>C</p>')).toEqual(
+      `<p>A</p><p><del class='diffdel'>B</del></p><p>C</p>`
+    )
+  })
+
+  it('should keep paragraph boundaries on a replace operation that spans multiple paragraphs', () => {
+    // The diff algorithm treats this as a single Replace block (delete A,B then insert X,Y,Z)
+    // rather than aligning per-paragraph; we accept that as the price of a single-pass algorithm
+    // but verify each paragraph still renders as its own <p> rather than concatenating.
+    expect(HtmlDiff.execute('<p>A</p><p>B</p>', '<p>X</p><p>Y</p><p>Z</p>')).toEqual(
+      `<p><del class='diffmod'>A</del></p><p><del class='diffmod'>B</del></p><p><ins class='diffmod'>X</ins></p><p><ins class='diffmod'>Y</ins></p><p><ins class='diffmod'>Z</ins></p>`
+    )
+  })
+
+  it('should keep added paragraphs containing inline formatting as their own blocks', () => {
+    expect(HtmlDiff.execute('<p>shared</p>', '<p>shared</p><p><strong>bold added</strong></p>')).toEqual(
+      `<p>shared</p><p><strong><ins class='diffins'>bold added</ins></strong></p>`
+    )
+  })
+
+  it('should preserve a paragraph added inside a list item', () => {
+    expect(HtmlDiff.execute('<ol><li><p>shared</p></li></ol>', '<ol><li><p>shared</p><p>added</p></li></ol>')).toEqual(
+      `<ol><li><p>shared</p><p><ins class='diffins'>added</ins></p></li></ol>`
+    )
+  })
+
+  it('should preserve old wrapper structure when old is wrapped and new is plain text', () => {
+    // Inverse of the plain-text-old / wrapped-new asymmetric case. With one side unwrapped,
+    // the asymmetric guardrail should disable structural normalization. The word-level diff
+    // emits old's paragraph structure with deletions in their original paragraphs and the
+    // new content appended inline.
+    expect(HtmlDiff.execute('<p>X</p><p>Boop</p>', 'X with extra')).toEqual(
+      `<p>X</p><p><del class='diffmod'>Boop</del></p><ins class='diffmod'>&nbsp;with extra</ins>`
+    )
+  })
+
+  it.each([
+    ['section', '<section>X</section>', '<section>X</section><section>Boop</section>'],
+    ['article', '<article>X</article>', '<article>X</article><article>Boop</article>'],
+    ['aside', '<aside>X</aside>', '<aside>X</aside><aside>Boop</aside>'],
+    ['nav', '<nav>X</nav>', '<nav>X</nav><nav>Boop</nav>'],
+  ])('should treat <%s> as a structural wrapper for paragraph-add diffs', (tag, oldText, newText) => {
+    expect(HtmlDiff.execute(oldText, newText)).toEqual(
+      `<${tag}>X</${tag}><${tag}><ins class='diffins'>Boop</ins></${tag}>`
+    )
+  })
 })