nokodiff 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd5f28a6d69fffa081eb6dd4ade65be6aa8b2e309c7be553ab6820ffb7ab480e
-  data.tar.gz: 9b54a7aa1d6437c41ae47c5b3a6869ce97544426a9fae655940c227de34f5867
+  metadata.gz: 4804027f53e38322927f18d80b25a0c9cdfa659154e56090ba61e895dbde68f8
+  data.tar.gz: 855959815a1284325a50326d962127ff44feee8d16adfd74fd0e7af300b99ab9
 SHA512:
-  metadata.gz: 9f6088d65f6e4e007a39a4b30c07d6cc99080714952c68dd3ecc34cac4a10881910f3ce9d99826db4ecbd45917e8161e4f0f6b134c54d1d2ca31217b857b336e
-  data.tar.gz: af6c8bcaf758d33001c07f23d94d6897a83e3425c3093d342e05dde16fc6a6a0f59c6cfe2d46f1356da75c7c51babaf496947d1f01f4cb921d58908fa8c2be2d
+  metadata.gz: e9484c5b5682e6d8299d1c8d7ff9b38d6a9c53c85ffc15cbef6bdfd234d3bd81df05ba90423924511db20381e44fb70c078cbbef15fdfea631ad5d583647aede
+  data.tar.gz: 3563899d45760342ac2a70ad7977b35a8e7bfc5aeb058aba2a69ad567865a6a8de628a4240f687439e2f48e5ef3ddba1d82e0916d72910d89e2b149897fbe659

data/README.md

@@ -4,7 +4,7 @@ A Ruby Gem to highlight additions, deletions and character level changes while p
 
 It includes functionality to:
 * Compare two HTML fragments and output diffs with semantic HTML
-* Inline character differences highlighting using `<strong>` tagging
+* Inline character differences highlighting using `<span class="diff-marker">` tagging
 * Blocks of added or removed content wrapped in aria labelled `<ins>` and `<del>` tags
 * Optional CSS for styling the visual differences
 
@@ -48,8 +48,118 @@ In your application.scss file include:
 @import "nokodiff";
 ```
 
-This will include the styling for `<del>`, `<ins>` and `<strong>` tags to allow colour coding, highlighting and underlining of changes.
+This will include the styling for `<del>`, `<ins>` and `<span>` tags to allow colour coding, highlighting and underlining of changes.
+
+### More complex diffing with `data-diff-key`
+
+For more complex HTML structures, a standard diff can produce surprising or misleading results when elements are added, removed, or reordered. To get around this, add a `data-diff-key` attribute to elements you want compared in isolation.
+
+Each element with a unique `data-diff-key` value is diffed independently against its counterpart in the other HTML fragment. This prevents unrelated changes from affecting each other and produces more accurate, contextually meaningful output.
+
+The key value can be any unique string — it just needs to match between your `before` and `after` HTML for the elements you want paired together.
+
+#### Adding a new element
+
+When a `data-diff-key` element is present in `after` but not in `before`, its content is wrapped in an `<ins>` tag:
+
+```ruby
+before = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+  </div>
+HTML
+
+after = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+    <div data-diff-key="zm7q">
+      <p>Second paragraph</p>
+    </div>
+  </div>
+HTML
+
+Nokodiff.diff(before, after)
+```
+
+Output:
+
+```html
+<div>
+  <div data-diff-key="ixn4">
+    <p>First paragraph</p>
+  </div>
+  <div data-diff-key="zm7q">
+    <div class="diff">
+      <ins aria-label="added content"><p>Second paragraph</p></ins>
+    </div>
+  </div>
+</div>
+```
+
+![Adding a new element](docs/adding-a-new-element.png)
+
+#### Modifying an existing element
+
+When a `data-diff-key` element exists in both fragments but its content has changed, the element is diffed in isolation. Character-level changes are highlighted within `<del>` and `<ins>` tags:
+
+```ruby
+before = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+    <div data-diff-key="zm7q">
+      <p>Second paragraph</p>
+    </div>
+  </div>
+HTML
+
+after = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+    <div data-diff-key="zm7q">
+      <p>New paragraph</p>
+    </div>
+  </div>
+HTML
+
+Nokodiff.diff(before, after)
+```
+
+Output:
+
+```html
+<div>
+  <div data-diff-key="ixn4"><p>First paragraph</p></div>
+  <div data-diff-key="zm7q">
+    <div class="diff">
+      <del aria-label="removed content"><p><span class="diff-marker">S</span>e<span class="diff-marker">cond</span> paragraph</p></del>
+    </div>
+    <div class="diff">
+      <ins aria-label="added content"><p><span class="diff-marker">N</span>e<span class="diff-marker">w</span> paragraph</p></ins>
+    </div>
+  </div>
+</div>
+```
+
+![Modifying an existing element](docs/modifying-an-existing-element.png)
+
+#### Unchanged elements
+
+If a `data-diff-key` element's content is identical in both fragments, no diff markup is added and the element is returned as-is.
+
+#### Limitations
+
+Currently, the gem does not support highlighting removed `data-diff-key` elements. If a keyed element is present in `before` but absent from `after`, it will not be marked as deleted in the output.
+
+Thanks to [HTML Diff](https://html-diff.lix.dev/index.html) for inspiring this approach!
 
 ## Licence
 
-The gem is available as open source under the terms of the [MIT License.](https://opensource.org/license/MIT)
+The gem is available as open source under the terms of the [MIT License.](https://opensource.org/license/MIT)

data/app/assets/stylesheets/nokodiff.scss

@@ -1,9 +1,9 @@
 // stylelint-disable selector-no-qualifying-type, max-nesting-depth
 // Diff of two editions
 $added-color: #e6fff3;
-$strong-added-color: #99ffcf;
+$diff-marker-added-color: #99ffcf;
 $removed-color: #fadede;
-$strong-removed-color: #f3aeac;
+$diff-marker-removed-color: #f3aeac;
 $text-colour: #0b0c0c;
 $light-grey: #f3f2f1;
 $black: #0b0c0c;
@@ -33,9 +33,9 @@ $black: #0b0c0c;
     background-color: $removed-color;
     padding-bottom: 2px;
 
-    strong {
+    span.diff-marker {
       font-weight: normal;
-      background-color: $strong-removed-color;
+      background-color: $diff-marker-removed-color;
       border-bottom: 2px dashed $black;
     }
   }
@@ -44,9 +44,9 @@ $black: #0b0c0c;
     background-color: $added-color;
     padding-bottom: 2px;
 
-    strong {
+    span.diff-marker {
       font-weight: normal;
-      background-color: $strong-added-color;
+      background-color: $diff-marker-added-color;
       border-bottom: 2px dashed $black;
     }
   }
@@ -63,13 +63,13 @@ $black: #0b0c0c;
 
   del::before {
     color: $text-colour;
-    background-color: $strong-removed-color;
+    background-color: $diff-marker-removed-color;
     content: "−";
   }
 
   ins::before {
     color: $text-colour;
-    background-color: $strong-added-color;
+    background-color: $diff-marker-added-color;
     content: "+";
   }
-}
+}

data/lib/nokodiff/changes_in_fragments.rb

@@ -43,18 +43,18 @@ module Nokodiff
       append_accumulated_text(before_fragment, accumulated_before_text)
       append_accumulated_text(after_fragment, accumulated_after_text)
 
-      before_fragment.add_child(wrap_in_strong(change.old_element, before_fragment))
-      after_fragment.add_child(wrap_in_strong(change.new_element, after_fragment))
+      before_fragment.add_child(highlight_changes(change.old_element, before_fragment))
+      after_fragment.add_child(highlight_changes(change.new_element, after_fragment))
     end
 
     def emphasise_deletion(change)
       append_accumulated_text(before_fragment, accumulated_before_text)
-      before_fragment.add_child(wrap_in_strong(change.old_element, before_fragment))
+      before_fragment.add_child(highlight_changes(change.old_element, before_fragment))
     end
 
     def emphasise_addition(change)
       append_accumulated_text(after_fragment, accumulated_after_text)
-      after_fragment.add_child(wrap_in_strong(change.new_element, after_fragment))
+      after_fragment.add_child(highlight_changes(change.new_element, after_fragment))
     end
 
     def append_accumulated_text(fragment, accumulated_text)

data/lib/nokodiff/differ.rb

@@ -1,8 +1,8 @@
 module Nokodiff
   class Differ
-    def initialize(before_html, after_html)
-      @before = Nokogiri::HTML.fragment(before_html)
-      @after = Nokogiri::HTML.fragment(after_html)
+    def initialize(before, after)
+      @before = before
+      @after = after
     end
 
     def to_html
@@ -42,8 +42,8 @@ module Nokodiff
 
       before_fragment, after_fragment = Nokodiff::TextNodeDiffs.new(before_dup, after_dup).call
 
-      merge_adjacent_strong_tags(before_fragment)
-      merge_adjacent_strong_tags(after_fragment)
+      merge_adjacent_highlighted_changes(before_fragment)
+      merge_adjacent_highlighted_changes(after_fragment)
 
       [before_fragment.to_html, after_fragment.to_html]
     end
@@ -62,24 +62,28 @@ module Nokodiff
       end
     end
 
-    def merge_adjacent_strong_tags(node)
+    def merge_adjacent_highlighted_changes(node)
       return unless node.element?
 
       node.children.each do |child|
-        merge_adjacent_strong_tags(child) if child.element?
+        merge_adjacent_highlighted_changes(child) if child.element?
       end
 
       node.children.each_cons(2) do |left, right|
-        next unless left.name == "strong" && right.name == "strong"
+        next unless node_is_a_change?(left) && node_is_a_change?(right)
 
         left.content = left.content + right.content
         right.remove
 
-        merge_adjacent_strong_tags(node)
+        merge_adjacent_highlighted_changes(node)
         break
       end
     end
 
+    def node_is_a_change?(node)
+      node.name == "span" && node["class"] == "diff-marker"
+    end
+
     def unchanged_block(html)
       html.to_s
     end

data/lib/nokodiff/formatting_helpers.rb

@@ -1,11 +1,14 @@
 module Nokodiff
   module FormattingHelpers
-    def wrap_in_strong(char, fragment)
-      Nokogiri::XML::Node.new("strong", fragment.document).tap { |n| n.content = char }
+    def highlight_changes(char, fragment)
+      Nokogiri::XML::Node.new("span", fragment.document).tap do |n|
+        n.content = char
+        n["class"] = "diff-marker"
+      end
     end
 
-    def strong(text_node)
-      text_node.replace(wrap_in_strong(text_node.to_html, text_node.parent))
+    def highlighted_change(text_node)
+      text_node.replace(highlight_changes(text_node.to_html, text_node.parent))
     end
   end
 end

data/lib/nokodiff/html_fragment.rb

@@ -0,0 +1,40 @@
+require "forwardable"
+
+module Nokodiff
+  class HTMLFragment
+    extend Forwardable
+
+    class InvalidHTMLError < StandardError; end
+
+    def initialize(html)
+      @fragment = Nokogiri::HTML.fragment(html)
+      validate!
+      remove_blank_nodes!
+      remove_comments!
+    end
+
+    def_delegators :@fragment, :children, :css, :at, :to_html
+
+  private
+
+    def validate!
+      invalid_text_nodes = @fragment.children.reject do |node|
+        node.element? || node.comment? || (node.text? && node.text.strip.empty?)
+      end
+
+      unless invalid_text_nodes.empty?
+        raise InvalidHTMLError, "Invalid HTML input: #{@fragment.to_html}"
+      end
+    end
+
+    def remove_blank_nodes!
+      @fragment.traverse do |node|
+        node.remove if node.blank?
+      end
+    end
+
+    def remove_comments!
+      @fragment.css("comment()").remove
+    end
+  end
+end

data/lib/nokodiff/text_node_diffs.rb

@@ -31,8 +31,8 @@ module Nokodiff
     end
 
     def diff_text_node_content(before_text_node, after_text_node)
-      return strong(before_text_node) if text_removed?(before_text_node, after_text_node)
-      return strong(after_text_node) if text_added?(before_text_node, after_text_node)
+      return highlighted_change(before_text_node) if text_removed?(before_text_node, after_text_node)
+      return highlighted_change(after_text_node) if text_added?(before_text_node, after_text_node)
 
       before_chars = before_text_node.text.chars
       after_chars = after_text_node.text.chars

data/lib/nokodiff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nokodiff
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/nokodiff.rb

@@ -9,13 +9,17 @@ require_relative "nokodiff/differ"
 require_relative "nokodiff/engine"
 require_relative "nokodiff/text_node_diffs"
 require_relative "nokodiff/changes_in_fragments"
+require_relative "nokodiff/html_fragment"
 
 module Nokodiff
   def self.diff(before_html, after_html)
-    HTMLFragmentValidator.validate_html!(before_html)
-    HTMLFragmentValidator.validate_html!(after_html)
+    before = Nokodiff::HTMLFragment.new(before_html)
+    after = Nokodiff::HTMLFragment.new(after_html)
 
-    html = Differ.new(before_html, after_html).to_html
+    before_nodes, after_nodes = nodes(before, after)
+    keys = (before_nodes.keys + after_nodes.keys).uniq
+
+    html = keys.any? ? diff_by_keys(after, keys, before_nodes, after_nodes) : Differ.new(before, after).to_html
     safe_html(html)
   end
 
@@ -23,31 +27,25 @@ module Nokodiff
     html.respond_to?(:html_safe) ? html.html_safe : html
   end
 
-  class Error < StandardError; end
-
-  module HTMLFragmentValidator
-  module_function
-
-    def validate_html!(html)
-      document = Nokogiri::HTML::DocumentFragment.parse(html)
-
-      invalid_text_nodes = document.children.select do |node|
-        if node.element?
-          false
-        elsif node.comment?
-          false
-        elsif node.text?
-          !node.text.strip.empty?
-        else
-          true
-        end
-      end
+  private_class_method def self.nodes(before, after)
+    [
+      fetch_diff_nodes(before),
+      fetch_diff_nodes(after),
+    ]
+  end
 
-      unless invalid_text_nodes.empty?
-        raise ArgumentError, "Invalid HTML input"
-      end
+  private_class_method def self.fetch_diff_nodes(fragment)
+    fragment.css("[data-diff-key]").map { |node| [node["data-diff-key"], node] }.to_h
+  end
 
-      document
+  private_class_method def self.diff_by_keys(after, keys, before_nodes, after_nodes)
+    keys.each do |key|
+      diff = Differ.new(
+        before_nodes.fetch(key, Nokogiri::HTML.fragment("")),
+        after_nodes.fetch(key, Nokogiri::HTML.fragment("")),
+      ).to_html
+      after.at("[data-diff-key='#{key}']")&.inner_html = diff
     end
+    after.to_html
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nokodiff
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - GOV.UK Dev
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.1.20
+        version: 5.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.1.20
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -209,6 +209,7 @@ files:
 - lib/nokodiff/differ.rb
 - lib/nokodiff/engine.rb
 - lib/nokodiff/formatting_helpers.rb
+- lib/nokodiff/html_fragment.rb
 - lib/nokodiff/text_node_diffs.rb
 - lib/nokodiff/version.rb
 homepage: https://github.com/alphagov/nokodiff
@@ -229,7 +230,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.7
 specification_version: 4
 summary: A Ruby Gem to highlight additions, deletions and character level changes
   while preserving original HTML