nokodiff 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd5f28a6d69fffa081eb6dd4ade65be6aa8b2e309c7be553ab6820ffb7ab480e
-  data.tar.gz: 9b54a7aa1d6437c41ae47c5b3a6869ce97544426a9fae655940c227de34f5867
+  metadata.gz: e12bce0257af1ebff2c6de595dce5d68cefc73feb5ae4a419a98a81d9dbac212
+  data.tar.gz: 9479aa3c4ae7f3481a0a96baf002735fb02a4848530a9fc38565c72118e4a2eb
 SHA512:
-  metadata.gz: 9f6088d65f6e4e007a39a4b30c07d6cc99080714952c68dd3ecc34cac4a10881910f3ce9d99826db4ecbd45917e8161e4f0f6b134c54d1d2ca31217b857b336e
-  data.tar.gz: af6c8bcaf758d33001c07f23d94d6897a83e3425c3093d342e05dde16fc6a6a0f59c6cfe2d46f1356da75c7c51babaf496947d1f01f4cb921d58908fa8c2be2d
+  metadata.gz: 864f165ec8332dbcc0a61cffda45f6649ed00d5483e969ad7d55dc9af2e4acdbe202f54686424ff387f6f36ecd160b3834e89f4d1633a8bf311534b6c09eb0b3
+  data.tar.gz: f182809b76cf85e8ce23002575fb5c2708e527cd3659628d0ef248fdce79e1581ed6a551f99ca41a16dff7bacf9d67db87579185761052136e3f491d227f8bf6

data/README.md

@@ -50,6 +50,116 @@ In your application.scss file include:
 
 This will include the styling for `<del>`, `<ins>` and `<strong>` 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><strong>S</strong>e<strong>cond</strong> paragraph</p></del>
+    </div>
+    <div class="diff">
+      <ins aria-label="added content"><p><strong>N</strong>e<strong>w</strong> 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/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

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nokodiff
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 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.0
 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