dommy 0.8.1 → 0.10.0

data/lib/dommy/range.rb

@@ -111,6 +111,20 @@ module Dommy
       nil
     end
 
+    # `createContextualFragment(html)` — parse an HTML string into a
+    # DocumentFragment using the range's start node as the parsing context
+    # (DOM Parsing & Serialization). Frameworks use it to turn an HTML string
+    # into nodes (Nuxt's DOM hydration / `<slot>` helpers call it via a Range).
+    def create_contextual_fragment(html)
+      context = @document.create_element(contextual_local_name)
+      # WebIDL DOMString coercion: JS null stringifies to "null" (no
+      # [LegacyNullToEmptyString] here), the UNDEFINED sentinel to "undefined".
+      context.inner_html = html.nil? ? "null" : html.to_s # fragment-parses in the context element
+      fragment = @document.create_document_fragment
+      context.child_nodes.to_a.each { |child| fragment.append_child(child) }
+      fragment
+    end
+
     # --- Content extraction ----------------------------------------
 
     def to_s
@@ -138,21 +152,87 @@ module Dommy
       fragment
     end
 
+    # WHATWG Range.deleteContents. Removes the fully-contained nodes (childList
+    # records) and trims the partially-contained boundary CharacterData nodes
+    # (characterData records via `data=`), rather than removing boundary text
+    # nodes whole — so a deletion like `"abc"[1]…"def"[1]` leaves `"a"…"ef"`.
     def delete_contents
-      collect_nodes_in_range.each do |node|
+      return nil if collapsed?
+
+      sc = @start_container
+      so = @start_offset
+      ec = @end_container
+      eo = @end_offset
+
+      # Both boundaries in the same text node: just delete the substring.
+      if sc.equal?(ec) && text_node?(sc)
+        d = sc.data.to_s
+        sc.data = d[0, so].to_s + (d[eo..] || "")
+        return nil
+      end
+
+      to_remove = nodes_to_remove
+      new_node, new_offset = deletion_collapse_point(sc, so, ec, eo)
+
+      # Trim the start boundary text node's tail, remove the contained nodes,
+      # then trim the end boundary text node's head (order matters for records).
+      sc.data = sc.data.to_s[0, so].to_s if text_node?(sc)
+      to_remove.each do |node|
         if node.respond_to?(:__dommy_backend_node__)
-          # Fire a childList removal record (with correct sibling context) on the
-          # node's parent, like any other tree removal.
           @document.remove_node_with_notify(node.__dommy_backend_node__)
         elsif node.respond_to?(:remove)
           node.remove
         end
       end
+      ec.data = (ec.data.to_s[eo..] || "") if text_node?(ec)
 
-      collapse(true)
+      @start_container = @end_container = new_node
+      @start_offset = @end_offset = new_offset
       nil
     end
 
+    # Top-level nodes fully contained in the range (their parent isn't), removed
+    # whole. Deeper contained nodes go with their removed ancestor.
+    def nodes_to_remove
+      ancestor = common_ancestor_container
+      return [] unless ancestor.respond_to?(:child_nodes)
+
+      ancestor.child_nodes.to_a.select { |child| node_fully_contained?(child) }
+    end
+
+    # A node is contained in the range when its start position is at or after the
+    # range start and its end position is at or before the range end.
+    def node_fully_contained?(node)
+      parent = parent_of(node)
+      return false unless parent
+
+      idx = child_index_of(parent, node)
+      compare_points(parent, idx, @start_container, @start_offset) >= 0 &&
+        compare_points(parent, idx + 1, @end_container, @end_offset) <= 0
+    end
+
+    # The (node, offset) the range collapses to after deletion (WHATWG step 5):
+    # the start boundary if it contains the end, else the start's highest
+    # ancestor that doesn't contain the end, positioned just after it.
+    def deletion_collapse_point(sc, so, ec, eo)
+      return [sc, so] if inclusive_ancestor?(sc, ec)
+
+      ref = sc
+      ref = parent_of(ref) while (p = parent_of(ref)) && !inclusive_ancestor?(p, ec)
+      parent = parent_of(ref)
+      [parent, child_index_of(parent, ref) + 1]
+    end
+
+    def inclusive_ancestor?(maybe_ancestor, node)
+      current = node
+      while current
+        return true if current.equal?(maybe_ancestor)
+
+        current = parent_of(current)
+      end
+      false
+    end
+
     # surroundContents(newParent) — wraps the range contents in
     # newParent (which must be an element).
     def surround_contents(new_parent)
@@ -165,16 +245,21 @@ module Dommy
     end
 
     def insert_node(node)
-      # Insert at the range start. For text-node containers we split;
-      # for element containers we insert at child index.
+      # Insert at the range start. For a text container, split it at the offset
+      # (when interior) and insert before the split-off tail — matching the spec,
+      # which produces a childList record for the split plus one for the insert.
       sc = @start_container
       if text_node?(sc)
-        # Splitting is out of spec-perfect scope; insert before/after
-        # the text node based on offset.
         parent = parent_of(sc)
         idx = child_index_of(parent, sc)
-        idx += 1 if @start_offset >= length_of(sc)
-        insert_into_parent_at(parent, idx, node)
+        if @start_offset.zero?
+          insert_into_parent_at(parent, idx, node)
+        elsif @start_offset >= length_of(sc)
+          insert_into_parent_at(parent, idx + 1, node)
+        else
+          tail = sc.split_text(@start_offset)
+          parent.insert_before(node, tail)
+        end
       else
         insert_into_parent_at(sc, @start_offset, node)
       end
@@ -185,7 +270,10 @@ module Dommy
     # --- Ordering / containment ------------------------------------
 
     def compare_boundary_points(how, other)
-      # `how` must be one of the four named constants, else NotSupportedError.
+      # `how` is a WebIDL `unsigned short`: coerce first (NaN/±0/±Infinity → 0,
+      # otherwise truncate toward zero and take modulo 2^16), then require one of
+      # the four named constants, else NotSupportedError.
+      how = to_unsigned_short(how)
       unless [START_TO_START, START_TO_END, END_TO_END, END_TO_START].include?(how)
         raise DOMException::NotSupportedError, "invalid comparison type: #{how}"
       end
@@ -207,8 +295,13 @@ module Dommy
     end
 
     def intersects_node(node)
-      # Range and node intersect iff node's "position relative to range"
-      # is not entirely before or entirely after.
+      # WHATWG Range.intersectsNode: a node in a different tree never intersects;
+      # a node with no parent (a tree root, e.g. the document) always does.
+      return false unless same_root?(node)
+      return true if parent_of(node).nil?
+
+      # Otherwise range and node intersect iff node's position relative to the
+      # range is not entirely before or entirely after it.
       return false if before?(node)
       return false if after?(node)
 
@@ -219,6 +312,8 @@ module Dommy
     # range, 0 if inside, 1 if after. offset is a WebIDL unsigned long (so -1
     # wraps to a huge value > length → IndexSizeError).
     def compare_point(node, offset)
+      raise Bridge::TypeError, "argument is not a Node" unless node.is_a?(Dommy::Node)
+
       off = unsigned_long(offset)
       raise DOMException::WrongDocumentError, "node is in a different tree" unless same_root?(node)
       raise DOMException::InvalidNodeTypeError, "node is a doctype" if doctype?(node)
@@ -288,6 +383,16 @@ module Dommy
         collapsed?
       when "commonAncestorContainer"
         common_ancestor_container
+      when "START_TO_START"
+        START_TO_START
+      when "START_TO_END"
+        START_TO_END
+      when "END_TO_END"
+        END_TO_END
+      when "END_TO_START"
+        END_TO_START
+      else
+        Bridge::ABSENT
       end
     end
 
@@ -296,7 +401,7 @@ module Dommy
       setStart setEnd setStartBefore setStartAfter setEndBefore setEndAfter collapse selectNode
       selectNodeContents toString cloneContents extractContents deleteContents surroundContents
       insertNode compareBoundaryPoints intersectsNode containsNode cloneRange detach
-      comparePoint isPointInRange getBoundingClientRect getClientRects
+      comparePoint isPointInRange getBoundingClientRect getClientRects createContextualFragment
     ]
     def __js_call__(method, args)
       case method
@@ -318,6 +423,11 @@ module Dommy
         select_node(args[0])
       when "selectNodeContents"
         select_node_contents(args[0])
+      when "createContextualFragment"
+        # WebIDL required argument: a bare call (0 args) throws TypeError.
+        raise Bridge::TypeError, "createContextualFragment requires 1 argument, but only 0 present" if args.empty?
+
+        create_contextual_fragment(args[0])
       when "toString"
         to_s
       when "cloneContents"
@@ -353,6 +463,16 @@ module Dommy
 
     private
 
+    # The local name of the element to fragment-parse in: the start node if it
+    # is an element, else its nearest element ancestor; falling back to "body"
+    # (the HTML fragment-parsing context) for a document/fragment/`<html>` start.
+    def contextual_local_name
+      node = @start_container
+      el = node.respond_to?(:node_type) && node.node_type == 1 ? node : (node.respond_to?(:parent_element) ? node.parent_element : nil)
+      name = el&.local_name
+      name.nil? || name.casecmp?("html") ? "body" : name
+    end
+
     def collapse_to_start
       @end_container = @start_container
       @end_offset = @start_offset
@@ -367,13 +487,17 @@ module Dommy
       node.respond_to?(:node_type) && node.node_type == 3
     end
 
+    # WHATWG "length of a node": a DocumentType is 0; a CharacterData node
+    # (Text / CDATASection / ProcessingInstruction / Comment) is its data
+    # length; any other node is its number of children.
     def length_of(node)
-      if text_node?(node)
-        node.data.to_s.length
-      elsif node.respond_to?(:child_nodes)
-        node.child_nodes.length
-      else
+      case node.respond_to?(:node_type) ? node.node_type : nil
+      when 10 # DocumentType
         0
+      when 3, 4, 7, 8 # Text, CDATASection, ProcessingInstruction, Comment
+        node.respond_to?(:data) ? node.data.to_s.length : 0
+      else
+        node.respond_to?(:child_nodes) ? node.child_nodes.length : 0
       end
     end
 
@@ -382,6 +506,35 @@ module Dommy
       value.to_i % (2**32)
     end
 
+    # WebIDL `unsigned short` conversion: ToNumber, then NaN/±0/±Infinity → 0,
+    # otherwise truncate toward zero and take modulo 2^16.
+    def to_unsigned_short(value)
+      num = web_to_number(value)
+      return 0 if num.nan? || num.zero? || num.infinite?
+
+      ((num.negative? ? -1 : 1) * num.abs.floor) % 65536
+    end
+
+    # WebIDL ToNumber for the values that reach a bridged argument.
+    def web_to_number(value)
+      case value
+      when Numeric then value.to_f
+      when nil, false then 0.0
+      when true then 1.0
+      when String
+        stripped = value.strip
+        return 0.0 if stripped.empty?
+
+        begin
+          Float(stripped)
+        rescue ArgumentError
+          Float::NAN
+        end
+      else
+        Float::NAN
+      end
+    end
+
     # Two nodes share a root iff their topmost ancestors are the same node.
     def same_root?(node)
       ancestor_chain(node).last.equal?(ancestor_chain(@start_container).last)
@@ -398,15 +551,15 @@ module Dommy
       children = parent.respond_to?(:child_nodes) ? parent.child_nodes.to_a : []
       if idx >= children.length
         parent.append_child(node) if parent.respond_to?(:append_child)
+      elsif parent.respond_to?(:insert_before)
+        # insert_before extracts a DocumentFragment's children in order and fires
+        # the fragment-removal + target-addition records; `anchor.before` coerces
+        # the fragment to a single node and reverses multi-node order.
+        parent.insert_before(node, children[idx])
+      elsif children[idx].respond_to?(:before)
+        children[idx].before(node)
       else
-        anchor = children[idx]
-        if anchor.respond_to?(:before)
-          anchor.before(node)
-        elsif parent.respond_to?(:insert_before)
-          parent.insert_before(node, anchor)
-        else
-          parent.append_child(node) if parent.respond_to?(:append_child)
-        end
+        parent.append_child(node) if parent.respond_to?(:append_child)
       end
     end
 
@@ -506,14 +659,13 @@ module Dommy
       chain.find { |n| parent_of(n)&.equal?(container) }
     end
 
-    # Case 2a: a_container is an ancestor of b_container. a sits at
-    # offset a_offset; b's branch sits at child index b_idx. If
-    # a_offset > b_idx, a comes after; otherwise a precedes b.
+    # Case 2a: a_container is an ancestor of b_container. b sits *inside* the
+    # child of a_container at index b_idx (so its exact offset is irrelevant):
+    # if that index is before a_offset, a comes after b; otherwise a precedes b
+    # (WHATWG boundary-point position, ancestor case).
     def compare_offset_to_branch(a_offset, a_container, b_branch, ahead:)
       b_idx = child_index_of(a_container, b_branch)
-      return a_offset <=> (b_idx + 1) if a_offset > b_idx
-
-      ahead
+      b_idx < a_offset ? 1 : ahead
     end
 
     # Case 2b: b_container is an ancestor of a_container.
@@ -635,6 +787,8 @@ module Dommy
         is_collapsed
       when "type"
         is_collapsed ? "Caret" : "Range"
+      else
+        Bridge::ABSENT
       end
     end
 

data/lib/dommy/resources.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Dommy
+  # The single interface through which the lightweight test browser resolves
+  # external resources — both `<script src>` loads and `fetch` / XHR. A real
+  # browser routes both through one network layer, so Dommy does too: a
+  # `Resources` adapter answers `#get` / `#request` with a `Response`, and the
+  # same adapter can be installed as the window's fetch handler.
+  #
+  # An adapter returns `nil` from `#request` when it does not serve a URL, so
+  # callers fall through (to the next adapter in a `chain`, or to the stub maps
+  # behind `window.fetch`). Built-in adapters: `static`, `file_system`, `chain`.
+  # `Dommy::Rack::Resources` (in dommy-rack) serves a Rack app.
+  module Resources
+    # A resolved resource. `status_text` is filled by whichever adapter built
+    # it (the Rack adapter uses Rack::Utils; the core adapters leave it blank or
+    # derive a minimal default) so the core stays Rails/Rack-independent.
+    Response = Struct.new(:status, :status_text, :headers, :body, :url, :redirected, keyword_init: true) do
+      def success? = (200..299).cover?(status.to_i)
+    end
+
+    class << self
+      # An in-memory adapter. `map` keys are matched against the request URL as
+      # given AND its path component, so `{ "/app.js" => "..." }` serves both
+      # `/app.js` and `http://host/app.js`. A value is either a body String or a
+      # Hash with "status" / "headers" / "body" / "content_type".
+      def static(map) = Static.new(map)
+
+      # Serve files under `root` for URLs whose path starts with `base_url`.
+      # `file_system(root: "dist", base_url: "/assets")` maps the request path
+      # `/assets/app.js` to the file `dist/app.js`. Missing files return nil.
+      def file_system(root:, base_url: "/") = FileSystem.new(root, base_url)
+
+      # Try each adapter in order; the first non-nil Response wins.
+      def chain(*adapters) = Chain.new(adapters)
+    end
+
+    # Maps a Resources adapter onto the `__fetch_handler__` callable contract
+    # (`call(url, init) -> entry Hash | nil`) consumed by FetchFn / XHR, so the
+    # same Resources resolves window.fetch. A nil Response passes through to the
+    # stub maps.
+    class FetchHandler
+      # `executor` (responds to `submit(job) { |result| }`) and `scheduler` opt
+      # this handler into off-thread network: when both are present and the
+      # adapter supports `request_job`, fetch / XHR run the request on a worker
+      # and resolve through a DeferredResponse. Without them everything stays
+      # synchronous (the deterministic default the tests rely on).
+      def initialize(resources, executor: nil, scheduler: nil)
+        @resources = resources
+        @executor = executor
+        @scheduler = scheduler
+      end
+
+      def call(url, init = nil)
+        init = {} unless init.is_a?(Hash)
+        method = (init["method"] || "GET").to_s.upcase
+        headers = init["headers"].is_a?(Hash) ? init["headers"] : {}
+        body = init["body"]&.to_s
+
+        return call_async(method, url, headers, body) if async?
+
+        response = @resources.request(method: method, url: url.to_s, headers: headers, body: body)
+        response && to_entry(response, url)
+      end
+
+      private
+
+      def async?
+        !@executor.nil? && @resources.respond_to?(:request_job)
+      end
+
+      # The page-thread serve/decline decision still runs synchronously (so an
+      # unserved URL falls through to the stub maps exactly as in the sync path);
+      # only a served request is handed to a worker. The DeferredResponse
+      # completes — on the page thread, via the scheduler inbox — with the same
+      # entry Hash the sync path returns (or nil for a network miss).
+      def call_async(method, url, headers, body)
+        job = @resources.request_job(method: method, url: url.to_s, headers: headers, body: body)
+        return nil unless job
+
+        deferred = Dommy::DeferredResponse.new(@scheduler)
+        @executor.submit(job) do |response|
+          deferred.complete(response && to_entry(response, url))
+        end
+        deferred
+      end
+
+      def to_entry(response, url)
+        {
+          "status" => response.status,
+          "statusText" => response.status_text.to_s,
+          "body" => response.body.to_s,
+          "headers" => response.headers || {},
+          "url" => response.url || url.to_s,
+          "redirected" => response.redirected ? true : false
+        }
+      end
+    end
+
+    # Common helpers for the built-in adapters.
+    module Pathing
+      module_function
+
+      def path_of(url)
+        URI.parse(url.to_s).path
+      rescue URI::InvalidURIError
+        url.to_s
+      end
+    end
+
+    class Static
+      def initialize(map)
+        @map = map || {}
+      end
+
+      def get(url, headers: {}) = request(method: "GET", url: url, headers: headers)
+
+      def request(method:, url:, headers: {}, body: nil)
+        entry = @map[url.to_s] || @map[Pathing.path_of(url)]
+        return nil unless entry
+
+        if entry.is_a?(Hash)
+          ct = entry["content_type"] || entry["contentType"]
+          Response.new(
+            status: (entry["status"] || 200).to_i,
+            status_text: entry["status_text"].to_s,
+            headers: entry["headers"] || (ct ? {"Content-Type" => ct} : {}),
+            body: entry["body"].to_s,
+            url: url.to_s,
+            redirected: false
+          )
+        else
+          Response.new(status: 200, status_text: "OK", headers: {}, body: entry.to_s, url: url.to_s, redirected: false)
+        end
+      end
+    end
+
+    class FileSystem
+      def initialize(root, base_url)
+        @root = ::File.expand_path(root.to_s)
+        @base = base_url.to_s.sub(%r{/\z}, "")
+      end
+
+      def get(url, headers: {}) = request(method: "GET", url: url, headers: headers)
+
+      def request(method:, url:, headers: {}, body: nil)
+        path = Pathing.path_of(url)
+        return nil unless @base.empty? || path.start_with?("#{@base}/") || path == @base
+
+        rel = @base.empty? ? path : path[@base.length..]
+        file = ::File.expand_path(rel.sub(%r{\A/}, ""), @root)
+        # Containment guard: never escape `root`.
+        return nil unless file == @root || file.start_with?("#{@root}/")
+        return nil unless ::File.file?(file)
+
+        Response.new(status: 200, status_text: "OK", headers: {}, body: ::File.read(file), url: url.to_s, redirected: false)
+      end
+    end
+
+    class Chain
+      def initialize(adapters)
+        @adapters = adapters.compact
+      end
+
+      def get(url, headers: {}) = request(method: "GET", url: url, headers: headers)
+
+      def request(method:, url:, headers: {}, body: nil)
+        @adapters.each do |adapter|
+          response = adapter.request(method: method, url: url, headers: headers, body: body)
+          return response if response
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/dommy/rspec/capy_style_matchers.rb

@@ -76,6 +76,14 @@ module Dommy
         HaveNoField.new(name_or_label, **opts)
       end
 
+      def have_role(role, name: nil, level: nil, count: nil, exact: false)
+        HaveRole.new(role, name: name, level: level, count: count, exact: exact)
+      end
+
+      def have_no_role(role, name: nil, level: nil, exact: false)
+        HaveNoRole.new(role, name: name, level: level, exact: exact)
+      end
+
       # ----- Base behavior shared across element-finding matchers -----
 
       # @api private
@@ -351,6 +359,124 @@ module Dommy
       class HaveNoField < HaveField
         include Negated
       end
+
+      # @api private
+      # Matches elements by computed ARIA role (+ optional accessible name /
+      # level), walking the accessibility tree via Interaction::RoleQuery.
+      class HaveRole
+        def initialize(role, name: nil, level: nil, count: nil, exact: false)
+          @role = role
+          @name = name
+          @level = level
+          @count = count
+          @exact = exact
+        end
+
+        def matches?(scope)
+          @matched = Interaction::RoleQuery.match(
+            Internal::ScopeResolution.resolve(scope),
+            role: @role, name: @name, level: @level, exact: @exact
+          )
+          @count ? @matched.size == @count : !@matched.empty?
+        end
+
+        def does_not_match?(scope)
+          matches?(scope)
+          @count ? @matched.size != @count : @matched.empty?
+        end
+
+        def description
+          "have #{describe_target}"
+        end
+
+        def failure_message
+          "expected to find #{describe_target}, found #{@matched.size}"
+        end
+
+        def failure_message_when_negated
+          "expected NOT to find #{describe_target}, found #{@matched.size}"
+        end
+
+        private
+
+        def describe_target
+          parts = ["role #{@role.to_s.inspect}"]
+          parts << "named #{@name.inspect}" if @name
+          parts << "at level #{@level}" if @level
+          parts << "(count: #{@count.inspect})" if @count
+          parts.join(" ")
+        end
+      end
+
+      # @api private
+      class HaveNoRole < HaveRole
+        def matches?(scope)
+          !super
+        end
+
+        def does_not_match?(scope)
+          !matches?(scope)
+        end
+
+        def failure_message
+          "expected NOT to find #{describe_target}, found #{@matched.size}"
+        end
+
+        def failure_message_when_negated
+          "expected to find #{describe_target}, found #{@matched.size}"
+        end
+      end
+
+      # Prepended to every concrete matcher so it sits first in the method
+      # resolution order: it remembers the matched subject and wraps the
+      # matcher's own `failure_message` (via `super`) with any extra context a
+      # host registered through `Dommy::RSpec.failure_context` (e.g. dommy-rails
+      # appends a recent trace for a trace-enabled session). With no context
+      # registered the message is returned unchanged, so existing behavior — and
+      # existing message assertions — are preserved.
+      module FailureContext
+        def matches?(scope)
+          @__dommy_subject = scope
+          super
+        end
+
+        def does_not_match?(scope)
+          @__dommy_subject = scope
+          super
+        end
+
+        def failure_message
+          Dommy::RSpec.__decorate_failure(super, @__dommy_subject)
+        end
+
+        def failure_message_when_negated
+          Dommy::RSpec.__decorate_failure(super, @__dommy_subject)
+        end
+      end
+
+      [HaveSelector, HaveNoSelector, HaveContent, HaveNoContent,
+        HaveLink, HaveNoLink, HaveButton, HaveNoButton,
+        HaveField, HaveNoField, HaveRole, HaveNoRole].each { |matcher| matcher.prepend(FailureContext) }
+    end
+
+    class << self
+      # A `->(subject) { String | nil }` consulted when a matcher fails: its
+      # return value is appended to the failure message. Hosts set this to add
+      # context (dommy-rails registers a recent-trace summary for trace-enabled
+      # sessions). nil (the default) leaves every message untouched.
+      attr_accessor :failure_context
+    end
+
+    # Append the host's failure context to `message` for `subject`, or return
+    # `message` unchanged. Never raises out of a failure path: a misbehaving
+    # context proc must not mask the real assertion failure.
+    def self.__decorate_failure(message, subject)
+      return message unless failure_context && subject
+
+      extra = failure_context.call(subject)
+      extra ? "#{message}\n\n#{extra}" : message
+    rescue StandardError
+      message
     end
   end
 end