dommy 0.5.0

data/lib/dommy/internal/template_content_registry.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Manages <template> element content fragments.
+    # When HTML contains <template>X</template>, the inner content X is
+    # detached and stored in a separate DocumentFragment, accessed via
+    # the element's `content` property (per HTML spec).
+    #
+    # Keeping these fragments off-document is what makes template content
+    # invisible to querySelector, getElementById, etc., on the main tree.
+    class TemplateContentRegistry
+      def initialize(document)
+        @document = document
+        # template_node.object_id → Nokogiri fragment
+        @fragments = {}
+      end
+
+      # Parse HTML into a fragment and attach it as the template's content.
+      # Drops any pre-existing direct children of the template element.
+      def attach(template_element, html)
+        template_element.__node__.children.each(&:unlink)
+        fragment = @document.nokogiri_doc.fragment(html.to_s)
+        @fragments[template_element.__node__.object_id] = fragment
+        fragment
+      end
+
+      # Get the wrapped Fragment for a template element, seeding from
+      # the template's current children if not previously migrated.
+      def fragment_for(template_element)
+        fragment = @fragments[template_element.__node__.object_id]
+        fragment ||= seed(template_element)
+        @document.wrap_node(fragment)
+      end
+
+      # Raw (Nokogiri) fragment lookup by Nokogiri node — used by
+      # internal traversal to skip template-content sub-trees.
+      def raw_fragment_for(nokogiri_node)
+        @fragments[nokogiri_node.object_id]
+      end
+
+      def inner_html_of(template_element)
+        fragment = @fragments[template_element.__node__.object_id]
+        return "" unless fragment
+
+        fragment.children.map(&:to_html).join
+      end
+
+      def has_content?(nokogiri_node)
+        @fragments.key?(nokogiri_node.object_id)
+      end
+
+      # Direct register — called after manual fragment construction
+      # (e.g., when seeding from existing template children).
+      def store(template_node, fragment)
+        @fragments[template_node.object_id] = fragment
+      end
+
+      # Walk a Nokogiri subtree, finding <template> elements whose
+      # children are still direct (not yet migrated to a fragment), and
+      # migrate each one. Called after innerHTML / fragment-parsing to
+      # keep template content out of the main tree.
+      def migrate_descendants(root)
+        targets = []
+        targets << root if template_needing_migration?(root)
+        root.traverse do |node|
+          targets << node if template_needing_migration?(node)
+        end
+
+        targets.uniq.each { |t| migrate_one(t) }
+      end
+
+      private
+
+      def template_needing_migration?(node)
+        return false unless node.respond_to?(:name) && node.name == "template"
+
+        !has_content?(node)
+      end
+
+      def seed(template_element)
+        migrate_one(template_element.__node__)
+        @fragments[template_element.__node__.object_id]
+      end
+
+      def migrate_one(template_node)
+        fragment = @document.nokogiri_doc.fragment("")
+        template_node.children.to_a.each do |child|
+          child.unlink
+          fragment.add_child(child)
+        end
+
+        @fragments[template_node.object_id] = fragment
+      end
+    end
+  end
+end

data/lib/dommy/minitest/assertions.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../internal/dom_matching"
+require_relative "../internal/scope_resolution"
+
+module Dommy
+  module Minitest
+    # Custom Minitest assertions for testing Dommy DOM objects.
+    #
+    # @example
+    #   require "dommy/minitest"
+    #
+    #   class MyTest < Minitest::Test
+    #     include Dommy::Minitest::Assertions
+    #
+    #     def test_renders_button
+    #       dom = parse_html("<button class='primary'>Submit</button>")
+    #       assert_dom_contains(dom, "button.primary")
+    #       assert_dom_contains_text(dom, "Submit")
+    #     end
+    #   end
+    module Assertions
+      def assert_dom_contains(scope, selector, text: nil, count: nil, msg: nil)
+        matched = dom_matched_for(scope, selector, text: text)
+        msg ||= "expected to contain DOM matching #{selector.inspect}" \
+          "#{text ? " with text #{text.inspect}" : ""}" \
+          "#{count ? " (count: #{count.inspect})" : ""}, found #{matched.size}"
+        assert(Internal::DomMatching.count_matches?(matched.size, count), msg)
+      end
+
+      def refute_dom_contains(scope, selector, text: nil, count: nil, msg: nil)
+        matched = dom_matched_for(scope, selector, text: text)
+        msg ||= "expected NOT to contain DOM matching #{selector.inspect}" \
+          "#{text ? " with text #{text.inspect}" : ""}, found #{matched.size}"
+        refute(Internal::DomMatching.count_matches?(matched.size, count), msg)
+      end
+
+      def assert_dom_contains_text(scope, text, msg: nil)
+        actual = dom_text_of(scope)
+        msg ||= "expected text to include #{text.inspect}, got #{actual.inspect}"
+        assert(Internal::DomMatching.text_matches?(actual, text), msg)
+      end
+
+      def refute_dom_contains_text(scope, text, msg: nil)
+        actual = dom_text_of(scope)
+        msg ||= "expected text NOT to include #{text.inspect}, got #{actual.inspect}"
+        refute(Internal::DomMatching.text_matches?(actual, text), msg)
+      end
+
+      # Without a value argument, checks attribute existence only.
+      # With a value, checks string equality.
+      def assert_dom_has_attribute(element, name, value = UNSET, msg: nil)
+        present = element.has_attribute?(name.to_s)
+        if value.equal?(UNSET)
+          msg ||= "expected element to have attribute #{name.inspect}"
+          assert(present, msg)
+        else
+          actual = element.get_attribute(name.to_s)
+          msg ||= "expected attribute #{name.inspect} to equal #{value.inspect}, got #{actual.inspect}"
+          assert_equal(value.to_s, actual.to_s, msg)
+        end
+      end
+
+      def refute_dom_has_attribute(element, name, msg: nil)
+        present = element.has_attribute?(name.to_s)
+        msg ||= "expected element NOT to have attribute #{name.inspect}"
+        refute(present, msg)
+      end
+
+      def assert_dom_has_class(element, class_name, msg: nil)
+        actual_classes = element.class_list.value.to_s.split(/\s+/)
+        msg ||= "expected element to have class #{class_name.inspect}, got #{actual_classes.inspect}"
+        assert_includes(actual_classes, class_name.to_s, msg)
+      end
+
+      def refute_dom_has_class(element, class_name, msg: nil)
+        actual_classes = element.class_list.value.to_s.split(/\s+/)
+        msg ||= "expected element NOT to have class #{class_name.inspect}, got #{actual_classes.inspect}"
+        refute_includes(actual_classes, class_name.to_s, msg)
+      end
+
+      def assert_dom_html_equal(scope, expected_html, msg: nil)
+        scope = Internal::ScopeResolution.resolve(scope)
+        actual_n = Internal::DomMatching.normalize_html(Internal::DomMatching.html_of(scope))
+        expected_n = Internal::DomMatching.normalize_html(expected_html)
+        msg ||= "expected DOM HTML to match.\nExpected: #{expected_n}\nActual:   #{actual_n}"
+        assert_equal(expected_n, actual_n, msg)
+      end
+
+      # Sentinel for "value was not passed"
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      private
+
+      def dom_matched_for(scope, selector, text:)
+        Internal::DomMatching.filter(Internal::ScopeResolution.resolve(scope), selector, text: text)
+      end
+
+      def dom_text_of(scope)
+        Internal::DomMatching.text_of(Internal::ScopeResolution.resolve(scope))
+      end
+    end
+  end
+end

data/lib/dommy/minitest.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Entry point for using Dommy from Minitest test suites.
+# Loads the test helpers and DOM assertion modules so users can
+# `include` them into their test classes.
+#
+# @example
+#   require "dommy/minitest"
+#
+#   class MyTest < Minitest::Test
+#     include Dommy::TestHelpers
+#     include Dommy::Minitest::Assertions
+#   end
+
+require "dommy"
+require "dommy/test_helpers"
+require "dommy/minitest/assertions"

data/lib/dommy/navigator.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `window.navigator` — exposes browser-agent metadata plus
+  # `clipboard` / `permissions` sub-objects. Dommy returns sensible
+  # defaults (Dommy as user agent, "en" language, online=true) that
+  # tests can override.
+  class Navigator
+    DEFAULT_USER_AGENT = "Mozilla/5.0 (Dommy) Ruby"
+
+    attr_accessor :user_agent, :language, :languages, :platform, :vendor, :on_line, :cookie_enabled
+
+    def initialize(window)
+      @window = window
+      @user_agent = DEFAULT_USER_AGENT
+      @language = "en"
+      @languages = ["en"].freeze
+      @platform = "Dommy"
+      @vendor = "Dommy"
+      @on_line = true
+      @cookie_enabled = true
+      @clipboard = Clipboard.new(window)
+      @permissions = Permissions.new(window)
+    end
+
+    attr_reader :clipboard, :permissions
+
+    def [](key)
+      __js_get__(key.to_s)
+    end
+
+    def []=(k, v)
+      __js_set__(k.to_s, v)
+    end
+
+    def __js_get__(key)
+      case key
+      when "userAgent"
+        @user_agent
+      when "language"
+        @language
+      when "languages"
+        @languages
+      when "platform"
+        @platform
+      when "vendor"
+        @vendor
+      when "onLine"
+        @on_line
+      when "cookieEnabled"
+        @cookie_enabled
+      when "clipboard"
+        @clipboard
+      when "permissions"
+        @permissions
+      end
+    end
+
+    def __js_set__(_key, _value)
+      nil
+    end
+  end
+
+  # `navigator.clipboard` — an in-memory clipboard for tests. Real
+  # OS clipboard access is intentionally not implemented; reads and
+  # writes round-trip through Ruby memory only.
+  #
+  # Async APIs (`readText`/`writeText`/`read`/`write`) return
+  # PromiseValue so callers' `.await` chains keep working.
+  class Clipboard
+    include EventTarget
+
+    def initialize(window)
+      @window = window
+      @text = ""
+      @items = []
+    end
+
+    # Sync read for tests that don't want to await.
+    def text
+      @text
+    end
+
+    def text=(value)
+      @text = value.to_s
+    end
+
+    def read_text
+      PromiseValue.resolve(@window, @text)
+    end
+
+    def write_text(text)
+      @text = text.to_s
+      PromiseValue.resolve(@window, nil)
+    end
+
+    def read
+      PromiseValue.resolve(@window, @items.dup)
+    end
+
+    def write(items)
+      @items = items.is_a?(Array) ? items : [items]
+      PromiseValue.resolve(@window, nil)
+    end
+
+    def __js_get__(_key)
+      nil
+    end
+
+    def __js_set__(_key, _value)
+      nil
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "readText"
+        read_text
+      when "writeText"
+        write_text(args[0])
+      when "read"
+        read
+      when "write"
+        write(args[0])
+      when "addEventListener"
+        add_event_listener(args[0], args[1], args[2])
+      when "removeEventListener"
+        remove_event_listener(args[0], args[1])
+      when "dispatchEvent"
+        dispatch_event(args[0])
+      end
+    end
+
+    def __event_parent__
+      nil
+    end
+  end
+
+  # `navigator.permissions` — query returns a PermissionStatus whose
+  # `state` defaults to "granted" for every recognized name. Tests
+  # can override via `permissions.set("name", "denied")` before
+  # exercising user code.
+  class Permissions
+    KNOWN_NAMES = %w[
+      geolocation
+      notifications
+      push
+      midi
+      camera
+      microphone
+      clipboard-read
+      clipboard-write
+      background-fetch
+      background-sync
+      persistent-storage
+      accelerometer
+      gyroscope
+      magnetometer
+      screen-wake-lock
+      storage-access
+      window-management
+    ]
+      .freeze
+
+    def initialize(window)
+      @window = window
+      @overrides = {}
+    end
+
+    # Test helper: override the resolved state for a permission name.
+    # Subsequent `query()` calls will see the new value, and existing
+    # PermissionStatus objects fire `change` events.
+    def set(name, state)
+      key = name.to_s
+      @overrides[key] = state.to_s
+      @statuses ||= {}
+      status = @statuses[key]
+      status&.__set_state__(state.to_s)
+      nil
+    end
+
+    def query(descriptor)
+      name = if descriptor.is_a?(Hash)
+        (descriptor["name"] || descriptor[:name]).to_s
+      else
+        descriptor.to_s
+      end
+
+      state = @overrides[name] || "granted"
+      @statuses ||= {}
+      status = @statuses[name] ||= PermissionStatus.new(@window, name, state)
+      PromiseValue.resolve(@window, status)
+    end
+
+    def __js_get__(_key)
+      nil
+    end
+
+    def __js_set__(_key, _value)
+      nil
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "query"
+        query(args[0])
+      end
+    end
+  end
+
+  # `PermissionStatus` — `state` + `onchange` event handler. Fires a
+  # `change` event when `Permissions#set` mutates the underlying
+  # value (mirrors browser behavior where the user toggles a
+  # permission).
+  class PermissionStatus
+    include EventTarget
+
+    attr_reader :name, :state
+
+    def initialize(window, name, state)
+      @window = window
+      @name = name
+      @state = state
+      @onchange = nil
+    end
+
+    def __set_state__(new_state)
+      return if @state == new_state
+
+      @state = new_state
+      dispatch_event(Event.new("change"))
+    end
+
+    def __js_get__(key)
+      case key
+      when "name"
+        @name
+      when "state"
+        @state
+      when "onchange"
+        @onchange
+      end
+    end
+
+    def __js_set__(key, value)
+      case key
+      when "onchange"
+        # Assigning to onchange overwrites the previous handler.
+        remove_event_listener("change", @onchange) if @onchange
+        @onchange = value
+        add_event_listener("change", value) if value
+      end
+
+      nil
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "addEventListener"
+        add_event_listener(args[0], args[1], args[2])
+      when "removeEventListener"
+        remove_event_listener(args[0], args[1])
+      when "dispatchEvent"
+        dispatch_event(args[0])
+      end
+    end
+
+    def __event_parent__
+      nil
+    end
+  end
+end

data/lib/dommy/node.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `NodeList` — Array sub-class that adds the DOM NodeList surface
+  # (`item(i)` / `forEach(cb)` / `entries` / `keys` / `values`) on
+  # top of regular Array operations. Returned from
+  # `querySelectorAll`, `getElementsBy*`, `childNodes`, etc.
+  #
+  # Live vs. static collections aren't distinguished here — Dommy
+  # snapshots tree state at the time of the query, matching what
+  # most happy-dom test patterns expect.
+  class NodeList < Array
+    # Spec-compliant: out-of-range returns nil, not raise (Array#[] is
+    # close but we make negative indices fail too — DOM `item(-1)` is
+    # nil, not Array#[-1]'s last element).
+    def item(index)
+      i = index.to_i
+      return nil if i < 0 || i >= length
+
+      self[i]
+    end
+
+    # Spec signature: `forEach(callback(value, key, listObj))`. The
+    # Ruby `each_with_index` block-arg order is (value, index), which
+    # we re-yield as (value, index, self) for spec parity.
+    def for_each(&block)
+      each_with_index do |value, index|
+        block.call(value, index, self)
+      end
+
+      nil
+    end
+
+    alias forEach for_each
+
+    # NodeList `entries` returns an enumerator of [index, value].
+    def entries
+      each_with_index.map { |value, index| [index, value] }
+    end
+
+    def keys
+      (0...length).to_a
+    end
+
+    # `values` is the iterator of the NodeList itself; we return
+    # `self.to_a` (a plain Array copy) so callers can't mutate
+    # the original list.
+    def values
+      to_a
+    end
+
+    def __js_get__(key)
+      case key
+      when "length"
+        length
+      else
+        if key.is_a?(Integer) || key.to_s.match?(/\A\d+\z/)
+          item(key.to_i)
+        end
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "item"
+        item(args[0])
+      when "forEach"
+        for_each(&args[0])
+      when "entries"
+        entries
+      when "keys"
+        keys
+      when "values"
+        values
+      end
+    end
+  end
+
+  # `LiveNodeList` — like NodeList, but re-evaluates its source on
+  # every access. Returned by APIs whose spec says "live" — e.g.
+  # `Node.childNodes`. The constructor takes a block that yields the
+  # current array of nodes; `length`, `item`, iteration all call it.
+  #
+  # Inherits Array so `list[i]` / `list.each` still work for callers
+  # that don't know about the live semantics, but those work off a
+  # snapshot taken at the moment of the call. The DOM-shape methods
+  # (`length`, `item`, `for_each`) re-query on every call.
+  class LiveNodeList
+    include Enumerable
+
+    def initialize(&block)
+      @compute = block
+    end
+
+    def length
+      @compute.call.length
+    end
+
+    alias size length
+
+    def item(index)
+      i = index.to_i
+      arr = @compute.call
+      return nil if i < 0 || i >= arr.length
+
+      arr[i]
+    end
+
+    def [](index)
+      case index
+      when Integer
+        item(index)
+      else
+        nil
+      end
+    end
+
+    def first
+      @compute.call.first
+    end
+
+    def last
+      @compute.call.last
+    end
+
+    def each(&block)
+      @compute.call.each(&block)
+      self
+    end
+
+    def to_a
+      @compute.call.dup
+    end
+
+    def for_each(&block)
+      @compute.call.each_with_index do |value, index|
+        block.call(value, index, self)
+      end
+
+      nil
+    end
+
+    alias forEach for_each
+
+    def entries
+      @compute.call.each_with_index.map { |v, i| [i, v] }
+    end
+
+    def keys
+      (0...length).to_a
+    end
+
+    def values
+      to_a
+    end
+
+    def empty?
+      @compute.call.empty?
+    end
+
+    def __js_get__(key)
+      case key
+      when "length"
+        length
+      else
+        if key.is_a?(Integer) || key.to_s.match?(/\A\d+\z/)
+          item(key.to_i)
+        end
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "item"
+        item(args[0])
+      when "forEach"
+        for_each(&args[0])
+      when "entries"
+        entries
+      when "keys"
+        keys
+      when "values"
+        values
+      end
+    end
+  end
+
+  # `Node` — common base mixin. All node-like classes (Element,
+  # TextNode, CommentNode, CharacterDataNode, Document, Fragment,
+  # DocumentType, ShadowRoot) include this so `el.is_a?(Dommy::Node)`
+  # works.
+  #
+  # Real classes already define `nodeType` / `nodeName` / `nodeValue`
+  # / `parentNode` / `isConnected` / `cloneNode` independently; this
+  # module is primarily an identity marker. Adding new shared methods
+  # later is straightforward.
+  module Node
+    # Standardized nodeType constants — duplicated from Element so
+    # callers can refer to `Dommy::Node::ELEMENT_NODE` without
+    # depending on a specific subclass.
+    ELEMENT_NODE = 1
+    ATTRIBUTE_NODE = 2
+    TEXT_NODE = 3
+    CDATA_SECTION_NODE = 4
+    PROCESSING_INSTRUCTION_NODE = 7
+    COMMENT_NODE = 8
+    DOCUMENT_NODE = 9
+    DOCUMENT_TYPE_NODE = 10
+    DOCUMENT_FRAGMENT_NODE = 11
+
+    DOCUMENT_POSITION_DISCONNECTED = 0x01
+    DOCUMENT_POSITION_PRECEDING = 0x02
+    DOCUMENT_POSITION_FOLLOWING = 0x04
+    DOCUMENT_POSITION_CONTAINS = 0x08
+    DOCUMENT_POSITION_CONTAINED_BY = 0x10
+    DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20
+  end
+end