dommy 0.5.0

data/lib/dommy/internal/cookie_jar.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Manages document cookie storage (in-memory, not persisted).
+    # Implements the simple document.cookie key=value; key=value interface.
+    class CookieJar
+      def initialize
+        @cookies = {}
+      end
+
+      # Return all cookies as "name=value; name=value" string
+      def to_cookie_string
+        @cookies.map { |k, v| "#{k}=#{v}" }.join("; ")
+      end
+
+      # Parse and store a cookie from a Set-Cookie-style string
+      def set_cookie(value)
+        pair = value.to_s.split(";", 2).first.to_s.strip
+        return if pair.empty?
+
+        key, val = pair.split("=", 2)
+        @cookies[key.to_s.strip] = val.to_s.strip if key
+      end
+    end
+  end
+end

data/lib/dommy/internal/dom_matching.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Shared matching primitives used by both RSpec matchers and
+    # Minitest assertions. Centralizes selector / text / count
+    # interpretation so the two frameworks behave identically.
+    module DomMatching
+      module_function
+
+      # Find elements in scope matching selector, optionally filtered
+      # by text content.
+      #
+      # @param scope [#query_selector_all] Document / Element / ShadowRoot / Fragment
+      # @param selector [String]
+      # @param text [String, Regexp, nil]
+      # @return [Array<Dommy::Element>]
+      def filter(scope, selector, text: nil)
+        elements = scope.query_selector_all(selector).to_a
+        return elements if text.nil?
+
+        elements.select { |el| text_matches?(el.text_content, text) }
+      end
+
+      # @param actual [String]
+      # @param expected [String, Regexp]
+      # @param exact [Boolean] when true, require exact equality (string)
+      #   or full-string regexp match.
+      def text_matches?(actual, expected, exact: false)
+        actual = actual.to_s
+        case expected
+        when Regexp
+          exact ? actual.match?(expected) && actual == actual[expected] : actual.match?(expected)
+        else
+          exact ? actual.strip == expected.to_s : actual.include?(expected.to_s)
+        end
+      end
+
+      # @param actual [Integer]
+      # @param expected [Integer, Range, nil] — nil means "at least one"
+      def count_matches?(actual, expected)
+        case expected
+        when nil
+          actual.positive?
+        when Integer
+          actual == expected
+        when Range
+          expected.cover?(actual)
+        else
+          false
+        end
+      end
+
+      # Normalize an HTML string for structural comparison.
+      # Re-parses through Nokogiri and re-serializes, which collapses
+      # whitespace differences and attribute ordering quirks.
+      #
+      # @param html [String]
+      def normalize_html(html)
+        Nokogiri::HTML5.fragment(html.to_s).to_html.gsub(/\s+/, " ").strip
+      end
+
+      # Get the text_content of a scope, handling Document (which has
+      # no text_content directly — its body does).
+      def text_of(scope)
+        if scope.respond_to?(:text_content)
+          scope.text_content.to_s
+        elsif scope.respond_to?(:body) && scope.body
+          scope.body.text_content.to_s
+        else
+          scope.to_s
+        end
+      end
+
+      # Get the inner_html of a scope, falling back to body for Document.
+      def html_of(scope)
+        if scope.respond_to?(:inner_html)
+          scope.inner_html.to_s
+        elsif scope.respond_to?(:body) && scope.body
+          scope.body.inner_html.to_s
+        else
+          scope.to_s
+        end
+      end
+
+      # Best-effort visibility check using HTML-level signals only.
+      # Does NOT evaluate CSS stylesheets — `display: none` via class
+      # is NOT detected. See README for details and workarounds.
+      #
+      # Detects: `hidden` attribute, `<input type=hidden>`, non-rendering
+      # ancestors (head/script/style/template), inline `display:none` /
+      # `visibility:hidden` on element or any ancestor.
+      def visible?(element)
+        return true unless element.respond_to?(:__node__)
+
+        node = element.__node__
+        return false if node_invisible_self?(node)
+
+        NodeTraversal.each_ancestor(node) do |ancestor|
+          return false if non_rendering_tag?(ancestor)
+          return false if node_invisible_self?(ancestor)
+        end
+
+        true
+      end
+
+      # Filter elements by Capybara-style :visible option.
+      # @param elements [Array]
+      # @param visible [:visible, :all, :hidden, true, false, nil]
+      def filter_by_visibility(elements, visible)
+        case visible
+        when nil, :all, false
+          elements
+        when :hidden
+          elements.reject { |el| visible?(el) }
+        else
+          elements.select { |el| visible?(el) }
+        end
+      end
+
+      # ----- Implementation details for visible? -----
+      # @api private (kept module-level only because visible? calls them)
+
+      def node_invisible_self?(node)
+        return false unless node.respond_to?(:[])
+
+        return true if node["hidden"]
+        return true if node.respond_to?(:name) && node.name == "input" && node["type"] == "hidden"
+
+        style = node["style"].to_s
+        style.match?(/display\s*:\s*none/i) || style.match?(/visibility\s*:\s*hidden/i)
+      end
+
+      def non_rendering_tag?(node)
+        node.respond_to?(:name) && %w[head script style template].include?(node.name)
+      end
+
+      private_class_method :node_invisible_self?, :non_rendering_tag?
+    end
+  end
+end

data/lib/dommy/internal/mutation_coordinator.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Coordinates mutation notification to observers and custom element lifecycle callbacks.
+    # Isolates mutation observation and custom element logic from Document's public API.
+    class MutationCoordinator
+      def initialize(document, observer_manager)
+        @document = document
+        @observer_manager = observer_manager
+      end
+
+      def register_observer(observer)
+        @observer_manager.register(observer)
+        nil
+      end
+
+      def unregister_observer(observer)
+        @observer_manager.unregister(observer)
+        nil
+      end
+
+      # Fire CustomElement lifecycle: connected (synchronous, before mutation delivery)
+      def notify_connected(element)
+        return unless element&.respond_to?(:connected_callback)
+
+        element.connected_callback
+      rescue StandardError
+        nil
+      end
+
+      def notify_disconnected(element)
+        return unless element&.respond_to?(:disconnected_callback)
+
+        element.disconnected_callback
+      rescue StandardError
+        nil
+      end
+
+      # Walk a subtree and fire connected/disconnected callbacks for all elements
+      def notify_connected_subtree(nk)
+        return unless nk.respond_to?(:element?)
+
+        if nk.element?
+          wrapped = @document.wrap_node(nk)
+          notify_connected(wrapped) if wrapped
+        end
+
+        nk.children.each { |c| notify_connected_subtree(c) } if nk.respond_to?(:children)
+      end
+
+      def notify_disconnected_subtree(nk)
+        return unless nk.respond_to?(:element?)
+
+        if nk.element?
+          wrapped = @document.wrap_node(nk)
+          notify_disconnected(wrapped) if wrapped
+        end
+
+        nk.children.each { |c| notify_disconnected_subtree(c) } if nk.respond_to?(:children)
+      end
+
+      def notify_attribute_changed(element, name, old_value, new_value)
+        return unless element&.respond_to?(:attribute_changed_callback)
+
+        klass = element.class
+        return unless klass.respond_to?(:observed_attributes)
+        return unless klass.observed_attributes.include?(name.to_s.downcase)
+
+        element.attribute_changed_callback(name, old_value, new_value)
+      rescue StandardError
+        nil
+      end
+
+      # Fire MutationObserver childList records
+      def notify_child_list_mutation(
+        target_node:,
+        added_nodes:,
+        removed_nodes:,
+        previous_sibling: nil,
+        next_sibling: nil
+      )
+        target = @document.wrap_node(target_node)
+        return nil unless target
+        return nil if added_nodes.empty? && removed_nodes.empty?
+
+        wrapped_added = added_nodes.map { |node| @document.wrap_node(node) }.compact
+        wrapped_removed = removed_nodes.map { |node| @document.wrap_node(node) }.compact
+
+        # Fire Custom Element lifecycle callbacks (synchronous, before MutationObserver microtask)
+        added_nodes.each { |nk| notify_connected_subtree(nk) }
+        removed_nodes.each { |nk| notify_disconnected_subtree(nk) }
+
+        # Capture previousSibling / nextSibling (the position within target)
+        prev_w = previous_sibling
+        next_w = next_sibling
+        if (prev_w.nil? && next_w.nil?) && !added_nodes.empty?
+          first_nk = added_nodes.first
+          last_nk = added_nodes.last
+          prev_w ||= @document.wrap_node(first_nk.previous) if first_nk.respond_to?(:previous)
+          next_w ||= @document.wrap_node(last_nk.next) if last_nk.respond_to?(:next)
+        end
+
+        record = MutationRecord.new(
+          type: "childList",
+          target: target,
+          added_nodes: wrapped_added,
+          removed_nodes: wrapped_removed,
+          previous_sibling: prev_w,
+          next_sibling: next_w
+        )
+        @observer_manager.observers_matching(target).each do |observer|
+          observer.enqueue(record)
+        end
+
+        nil
+      end
+
+      # Fire MutationObserver attribute records
+      def notify_attribute_mutation(target_node:, attribute_name:, old_value:)
+        target = @document.wrap_node(target_node)
+        return nil unless target
+
+        attr = attribute_name.to_s.downcase
+        new_value = target_node[attr]
+
+        # Custom Element attributeChangedCallback (synchronous)
+        notify_attribute_changed(target, attr, old_value, new_value)
+
+        @observer_manager.observers_matching(target).each do |observer|
+          entry = observer.find_matching_entry(target)
+          next unless entry && entry[:attributes]
+
+          filter = entry[:attribute_filter]
+          next if filter && !filter.include?(attr)
+
+          observer.enqueue(
+            MutationRecord.new(
+              type: "attributes",
+              target: target,
+              attribute_name: attr,
+              old_value: entry[:attribute_old_value] ? old_value : nil
+            )
+          )
+        end
+
+        nil
+      end
+
+      # Fire MutationObserver characterData records
+      def notify_character_data_mutation(target_node:, old_value:)
+        target = @document.wrap_node(target_node)
+        return nil unless target
+
+        @observer_manager.observers_matching(target).each do |observer|
+          entry = observer.find_matching_entry(target)
+          next unless entry && entry[:character_data]
+
+          observer.enqueue(
+            MutationRecord.new(
+              type: "characterData",
+              target: target,
+              old_value: entry[:character_data_old_value] ? old_value : nil
+            )
+          )
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/dommy/internal/node_traversal.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Node tree traversal utilities.
+    # Centralizes ancestor walking logic to hide Nokogiri implementation details.
+    # Prevents duplication of tree traversal code across Observer, EventTarget, etc.
+    module NodeTraversal
+      # Walk from a node up to document, yielding each ancestor.
+      # Stops at Nokogiri::XML::Document (the root).
+      def self.each_ancestor(node)
+        current = node.respond_to?(:parent) ? node.parent : nil
+        while current && !current.is_a?(Nokogiri::XML::Document)
+          yield current
+          current = current.respond_to?(:parent) ? current.parent : nil
+        end
+      end
+
+      # Check if ancestor is an ancestor of node.
+      def self.ancestor_of?(ancestor, node)
+        each_ancestor(node) { |n| return true if n == ancestor }
+        false
+      end
+
+      # Find the first ancestor matching a predicate.
+      # Returns the result of the block, not the node itself.
+      def self.find_ancestor(node)
+        each_ancestor(node) { |n|
+          result = yield(n)
+          return result if result
+        }
+        nil
+      end
+    end
+  end
+end

data/lib/dommy/internal/node_wrapper_cache.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Manages DOM node identity via wrapper caching.
+    # Ensures that wrap_node(nokogiri_node) always returns the same Ruby object.
+    # Separates identity/caching management from Document's public DOM API.
+    class NodeWrapperCache
+      NAME_RE = /\A[a-z][\w.\-]*\z/i
+
+      def initialize(document)
+        @document = document
+        @wrappers = {}
+      end
+
+      # Returns the wrapped node, creating and caching if needed.
+      # Maintains DOM identity across repeated traversals.
+      def wrap(node)
+        return nil unless node
+
+        cached = @wrappers[node.object_id]
+        return cached if cached
+
+        wrapper = build_wrapper_for(node)
+        @wrappers[node.object_id] = wrapper if wrapper
+        wrapper
+      end
+
+      # Factory methods
+
+      def create_element(name)
+        str = name.to_s
+        raise DOMException::InvalidCharacterError, "name must not be empty" if str.empty?
+        raise DOMException::InvalidCharacterError, "invalid element name: #{str.inspect}" unless str.match?(NAME_RE)
+
+        wrap_node(Nokogiri::XML::Node.new(str.downcase, @document.nokogiri_doc))
+      end
+
+      def create_text_node(text)
+        wrap_node(Nokogiri::XML::Text.new(text.to_s, @document.nokogiri_doc))
+      end
+
+      def create_comment(text)
+        wrap_node(Nokogiri::XML::Comment.new(@document.nokogiri_doc, text.to_s))
+      end
+
+      def create_document_fragment
+        wrap_node(@document.nokogiri_doc.fragment(""))
+      end
+
+      def create_attribute(name)
+        str = name.to_s
+        raise DOMException::InvalidCharacterError, "name must not be empty" if str.empty?
+        raise DOMException::InvalidCharacterError, "invalid attribute name: #{str.inspect}" unless str.match?(NAME_RE)
+
+        Attr.new(str)
+      end
+
+      def create_attribute_ns(_namespace_uri, qualified_name)
+        str = qualified_name.to_s
+        raise DOMException::InvalidCharacterError, "name must not be empty" if str.empty?
+        raise DOMException::InvalidCharacterError, "invalid qualified name: #{str.inspect}" unless str.match?(NAME_RE)
+
+        Attr.new(str)
+      end
+
+      def create_element_ns(namespace_uri, qualified_name)
+        str = qualified_name.to_s
+        raise DOMException::InvalidCharacterError, "name must not be empty" if str.empty?
+        raise DOMException::InvalidCharacterError, "invalid qualified name: #{str.inspect}" unless str.match?(NAME_RE)
+
+        el = Nokogiri::XML::Node.new(str, @document.nokogiri_doc)
+        el.add_namespace_definition(nil, namespace_uri.to_s) if namespace_uri && !namespace_uri.to_s.empty?
+        wrap(el)
+      end
+
+      # Query methods
+
+      def query_selector(selector)
+        return nil if selector.nil? || selector.to_s.empty?
+
+        wrap(@document.nokogiri_doc.at_css(selector.to_s))
+      end
+
+      def query_selector_all(selector)
+        return NodeList.new if selector.nil? || selector.to_s.empty?
+
+        NodeList.new(@document.nokogiri_doc.css(selector.to_s).map { |node| wrap(node) }.compact)
+      end
+
+      def get_element_by_id(id)
+        return nil if id.nil? || id.to_s.empty?
+
+        wrap(@document.nokogiri_doc.at_css("##{id}"))
+      end
+
+      def get_elements_by_tag_name(name)
+        n = name.to_s.downcase
+        doc = @document.nokogiri_doc
+        cache = self
+        if n == "*"
+          HTMLCollection.new { doc.css("*").map { |x| cache.wrap(x) }.compact }
+        else
+          HTMLCollection.new { doc.css(n).map { |x| cache.wrap(x) }.compact }
+        end
+      end
+
+      def get_elements_by_name(name)
+        doc = @document.nokogiri_doc
+        cache = self
+        key = name.to_s
+        HTMLCollection.new do
+          doc.css("[name='#{key}']").map { |x| cache.wrap(x) }.compact
+        end
+      end
+
+      def get_elements_by_class_name(name)
+        tokens = name.to_s.split(/\s+/).reject(&:empty?)
+        doc = @document.nokogiri_doc
+        cache = self
+        HTMLCollection.new do
+          next [] if tokens.empty?
+
+          selector = tokens.map { |t| ".#{t}" }.join("")
+          doc.css(selector).map { |n| cache.wrap(n) }.compact
+        end
+      end
+
+      # Clear cached wrapper (used by customElements.define for upgrades)
+      def reset_wrapper(nokogiri_node)
+        @wrappers.delete(nokogiri_node.object_id)
+      end
+
+      private
+
+      def wrap_node(node)
+        wrap(node)
+      end
+
+      def build_wrapper_for(node)
+        case node
+        when Nokogiri::XML::Element
+          build_element_wrapper(node)
+        when Nokogiri::XML::Text
+          TextNode.new(@document, node)
+        when Nokogiri::XML::Comment
+          CommentNode.new(@document, node)
+        when Nokogiri::XML::DocumentFragment
+          Fragment.new(@document, node)
+        end
+      end
+
+      def build_element_wrapper(node)
+        custom_klass = custom_element_class_for(node.name)
+        klass = custom_klass || Dommy.element_class_for(node.name)
+        instance = klass.new(@document, node)
+
+        @wrappers[node.object_id] = instance
+
+        if custom_klass && instance.respond_to?(:construct)
+          begin
+            instance.construct
+          rescue StandardError
+            nil
+          end
+        end
+
+        instance
+      end
+
+      def custom_element_class_for(tag_name)
+        # Custom elements are registered on window, not document.
+        # Access via default_view if available.
+        default_view = @document.default_view
+        default_view&.custom_elements&.get(tag_name)
+      end
+    end
+  end
+end

data/lib/dommy/internal/observer_manager.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Manages MutationObserver registration and matching.
+    # Filters observers based on mutation target to avoid unnecessary lookups.
+    class ObserverManager
+      def initialize
+        @observers = []
+      end
+
+      def register(observer)
+        @observers << observer unless @observers.include?(observer)
+      end
+
+      def unregister(observer)
+        @observers.delete(observer)
+      end
+
+      # Returns all observers that match the given wrapped target.
+      # Delegates to each observer's matches_wrapped? method.
+      def observers_matching(target_wrapped)
+        @observers.select { |observer| observer.matches_wrapped?(target_wrapped) }
+      end
+
+      def all
+        @observers.dup
+      end
+    end
+  end
+end

data/lib/dommy/internal/observer_matcher.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Matches a mutation target against an observed node based on observer options.
+    # Works exclusively with wrapped DOM nodes (not Nokogiri internals).
+    class ObserverMatcher
+      def initialize
+      end
+
+      # Does this observer's target scope match the mutation target?
+      # Returns true if:
+      #   - target == observed (exact match), OR
+      #   - subtree=true AND target is descendant of observed
+      def matches?(observed_wrapped, target_wrapped, subtree:)
+        return true if target_wrapped.equal?(observed_wrapped)
+        return false unless subtree
+        return false unless observed_wrapped.respond_to?(:contains?)
+
+        observed_wrapped.contains?(target_wrapped)
+      end
+
+      # Special case: Document observation
+      # Matches if subtree=false (never) or target is in document (always)
+      def matches_document?(target_wrapped, subtree:)
+        return true if subtree
+        false
+      end
+    end
+  end
+end

data/lib/dommy/internal/scope_resolution.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Resolve various subject types into a uniform DOM scope for
+    # matchers and assertions to operate on.
+    #
+    # Test helpers want to let callers pass whatever they have on hand
+    # — `rendered`, `response.body`, a Document, an Element — and have
+    # it Just Work. This module centralizes that conversion so the
+    # matchers themselves stay focused on matching logic.
+    module ScopeResolution
+      module_function
+
+      # Convert the given subject into a scope usable by query_selector
+      # / text_content / inner_html.
+      #
+      # - String: parsed as HTML (full document or body fragment, per
+      #   `Dommy.parse`)
+      # - Anything else: returned as-is (Document, Element, Fragment,
+      #   ShadowRoot, etc.)
+      def resolve(scope)
+        scope.is_a?(String) ? Dommy.parse(scope).document : scope
+      end
+    end
+  end
+end

data/lib/dommy/internal/shadow_root_registry.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "node_traversal"
+
+module Dommy
+  module Internal
+    # Manages ShadowRoot identity and shadow boundary traversal.
+    # Maps Nokogiri DocumentFragment (shadow tree backing) to ShadowRoot wrapper.
+    class ShadowRootRegistry
+      def initialize
+        @shadow_roots = {}
+      end
+
+      # Register a shadow root by its backing fragment node
+      def register(fragment_node, shadow_root)
+        @shadow_roots[fragment_node.object_id] = shadow_root
+      end
+
+      # Find the ShadowRoot for a given fragment (if any)
+      def find_for_fragment(fragment_node)
+        return nil unless fragment_node
+        @shadow_roots[fragment_node.object_id]
+      end
+
+      # Find the enclosing ShadowRoot for a given node.
+      # Walks up the ancestor chain looking for a shadow root.
+      # Uses NodeTraversal to avoid duplication of tree walking logic.
+      def find_enclosing(nokogiri_node)
+        NodeTraversal.find_ancestor(nokogiri_node) do |ancestor|
+          find_for_fragment(ancestor)
+        end
+      end
+    end
+  end
+end