dommy 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 217a4ff53f58e6c12e424951b057cc0d3cbab3b898fdb85d5fd69ca7c34cd3c5
-  data.tar.gz: bedaba24772a900d85e62a27729b8e62f8db8a18e0b48360f1717799108432f8
+  metadata.gz: ccbe61a606e042968621f7fa81588634f2cdae566d96cef137bfefdfb6d38dd6
+  data.tar.gz: 4358d9b68082608b7e78971be2d2818fb35200b17bec1819ce21a520b3552d7c
 SHA512:
-  metadata.gz: 3a9687cf21dde61fa2c65cd47ca90f18e4d65da61912ffdbd8366cbf75f1110a96da52c43a27abee498dc9f2a19ffc306a491e14bb6aa4d985f7dd74fec88816
-  data.tar.gz: 201bb5b9217bc0373923f89e36cc968cb55328f249d902acdfa973f9f01179d9912463b5ee9d165c8c5e862fb7ff3f40ed531db9f2ee811432e6f77db8c42faa
+  metadata.gz: a8c9a3b7bbfacb6f58440cbfec8884cc79c8690beda03225b229ca935f1b6d1ce0778c83a9253f2996198e46c8d8b85f9df53ccedb1ffa4e942a5b9841c051e4
+  data.tar.gz: f428a160a4c2f0180e7fa01f8cb1e6ec31dc9855f2bd7b43f1be6abd7a752a6b93926c1e57791a1c8b51a22e62631c997c4fbe8b55ea38fed5748f62cc874033

data/README.md

@@ -1,7 +1,7 @@
 # Dommy
 
-A pure-Ruby DOM polyfill on top of [Nokogiri::HTML5](https://nokogiri.org/) — a Ruby-side analogue to happy-dom / jsdom.
-Dommy exposes browser-like DOM semantics (events, MutationObserver, Custom Elements, Shadow DOM, File API, timers, Storage) so view / component / request specs can verify DOM structure and behavior without spinning up a real browser.
+Dommy is a pure Ruby DOM polyfill built on [Nokogiri::HTML5](https://nokogiri.org/), inspired by happy-dom and jsdom.
+It gives Ruby tests a browser style DOM with events, MutationObserver, Custom Elements, Shadow DOM, the File API, timers, and Storage, without requiring a real browser.
 
 ## Quick start
 
@@ -74,22 +74,24 @@ input.validation_message    #=> "Please fill out this field."
 ### File API (Blob / File / FormData / DataTransfer)
 
 ```ruby
+win = Dommy.parse("<form><input type='file' name='attachment'></form>")
 file = Dommy::File.new(["pdf body"], "doc.pdf", "type" => "application/pdf")
 
 # Seed a file input for tests
-input = dom.query_selector("input[type='file']")
-input.__set_files__([file])
+input = win.document.query_selector("input[type='file']")
+input.__driver_set_files__([file])
 
 # FormData picks it up
-fd = Dommy::FormData.new(dom.query_selector("form"))
+fd = Dommy::FormData.new(win.document.query_selector("form"))
 fd.entries.to_a   #=> [["attachment", #<Dommy::File doc.pdf>]]
 
 # Drag-and-drop simulation
 dt = Dommy::DataTransfer.new(files: [file])
 ev = Dommy::DragEvent.new("drop", "dataTransfer" => dt, "bubbles" => true)
-dropzone.dispatch_event(ev)
+win.document.body.dispatch_event(ev)
 
 # Blob URLs
+blob = Dommy::Blob.new(["blob body"], "type" => "text/plain")
 url = Dommy::URL.create_object_url(blob)   # "blob:dommy/..."
 ```
 
@@ -102,7 +104,7 @@ response = win.__js_call__("fetch", ["/api"]).await
 ```
 
 > [!WARNING]
-> Most Dommy accessors (`Blob#text`, `Response#text`, `localStorage.get_item`) return synchronous Ruby values — not Promises. `.await` is for the JS-bridged async surface.
+> Most Dommy accessors (`Blob#text`, `localStorage.get_item`) return synchronous Ruby values — not Promises. `.await` is only for the JS-bridged async surface (e.g., `fetch()`, `window.__js_call__`). Methods like `Response#text()` are Promise-returning and require `.await`.
 
 ## Test helpers
 
@@ -176,7 +178,7 @@ Supported Capybara-style options: `text:` / `exact:` / `count:` (Integer or Rang
 Implemented:
 
 - Core DOM (Document, Element, Text/Comment/Fragment, NodeList, Attr)
-- 26 specialized HTMLElement subclasses
+- Specialized HTML and SVG element classes
 - events with composedPath / AbortSignal
 - MutationObserver (childList / attributes / characterData / subtree)
 - Custom Elements lifecycle
@@ -186,20 +188,36 @@ Implemented:
 - Promise
 - Location / History / URL
 - Storage
-- fetch (stub)
+- fetch / XMLHttpRequest stubs
+- WebSocket / EventSource / MessageChannel / BroadcastChannel test doubles
+- FileReader / Notification / Geolocation / `matchMedia`
+- `requestIdleCallback`, `structuredClone`, `URLPattern`
+- Web Crypto, Streams, Compression Streams, Worker
+- `performance`, `cookieStore`, Navigator extras
+- Popover API, Fullscreen API, View Transitions API stub
 - Navigator / Clipboard
 - TreeWalker / NodeIterator / NodeFilter
 - File API (Blob / File / FileList / FormData / DataTransfer)
+- IntersectionObserver / ResizeObserver / PerformanceObserver (test-driven `__test_trigger__`)
+- Range / Selection (DOM-level only, no layout)
+- Web Animations API (Animation / KeyframeEffect)
+- Extended events: Touch / Clipboard / Composition / Wheel / Focus / BeforeUnload / Input / Pointer / Progress / Drag
+
+For implementation notes and tradeoffs, see [design.md](./design.md).
 
 > [!IMPORTANT]
 > Out of scope:
 >
-> - requires a layout / CSS engine or media subsystems: real `getBoundingClientRect` / scroll metrics
-> - CSS scoping (`:host`, `::slotted`, computed styles)
+> - layout and CSS-engine behavior
 > - JS evaluation
 > - Canvas / WebGL / media playback
-> - layout-dependent Range / Selection
-> - SVG specialized classes
+> - layout-dependent Range / Selection geometry
+> - SVG-specific value types
+> - animation value interpolation
+
+## Method naming conventions
+
+See [docs/development.md](./docs/development.md) for method-naming conventions and internal protocols.
 
 ## Running the tests
 

data/lib/dommy/animation.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `KeyframeEffect` — wraps a target element + keyframes + timing.
+  # Dommy doesn't interpolate values (no layout / render); the
+  # effect is just a record of what the animation describes.
+  #
+  # Spec: https://drafts.csswg.org/web-animations/#keyframeeffect
+  class KeyframeEffect
+    attr_reader :target, :keyframes
+
+    def initialize(target, keyframes, options = nil)
+      @target = target
+      @keyframes = case keyframes
+      when nil
+        []
+      when Array
+        keyframes
+      else
+        [keyframes]
+      end
+
+      @timing = normalize_timing(options)
+    end
+
+    def get_timing
+      @timing.dup
+    end
+
+    alias getTiming get_timing
+
+    def update_timing(timing)
+      @timing.merge!(timing.transform_keys(&:to_s))
+      nil
+    end
+
+    alias updateTiming update_timing
+
+    def duration_ms
+      d = @timing["duration"]
+      d.is_a?(Numeric) ? d.to_i : 0
+    end
+
+    def __js_get__(key)
+      case key
+      when "target"
+        @target
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "getTiming"
+        get_timing
+      when "updateTiming"
+        update_timing(args[0] || {})
+      end
+    end
+
+    private
+
+    def normalize_timing(input)
+      case input
+      when nil
+        {"duration" => 0}
+      when Numeric
+        {"duration" => input.to_i}
+      when Hash
+        h = input.transform_keys(&:to_s)
+        h["duration"] = (h["duration"] || 0).is_a?(Numeric) ? h["duration"].to_i : 0
+        h
+      else
+        {"duration" => 0}
+      end
+    end
+  end
+
+  # `Animation` — represents a running animation, mirroring the Web
+  # Animations API's lifecycle and event surface. Dommy doesn't
+  # interpolate any property values; the animation transitions
+  # through "idle" → "running" → "finished" by either virtual time
+  # (`scheduler.advance_time`) or by an explicit `finish()` call.
+  #
+  # Spec: https://drafts.csswg.org/web-animations/#animation
+  class Animation
+    include EventTarget
+
+    attr_accessor :id
+    attr_reader :effect, :timeline, :play_state
+
+    def initialize(effect = nil, timeline = nil, window: nil)
+      @effect = effect
+      @timeline = timeline
+      @window = window
+      @play_state = "idle"
+      @playback_rate = 1.0
+      @current_time = nil
+      @start_time = nil
+      @id = ""
+      @finished_promise = nil
+      @ready_promise = nil
+      @scheduled_finish_id = nil
+    end
+
+    def current_time
+      @current_time
+    end
+
+    def current_time=(value)
+      @current_time = value
+    end
+
+    def start_time
+      @start_time
+    end
+
+    def start_time=(value)
+      @start_time = value
+    end
+
+    def playback_rate
+      @playback_rate
+    end
+
+    def playback_rate=(value)
+      @playback_rate = value.to_f
+    end
+
+    # Start (or resume) the animation. Returns self.
+    def play
+      return self if @play_state == "running"
+
+      previous = @play_state
+      @play_state = "running"
+      @start_time ||= @window&.scheduler&.now_ms || 0
+      ensure_ready_resolved
+      schedule_auto_finish if previous != "paused"
+      self
+    end
+
+    def pause
+      cancel_scheduled_finish
+      @play_state = "paused" unless @play_state == "idle"
+      self
+    end
+
+    def cancel
+      cancel_scheduled_finish
+      @play_state = "idle"
+      @current_time = nil
+      reject_finished_with_abort
+      dispatch_event(Event.new("cancel"))
+      self
+    end
+
+    def finish
+      cancel_scheduled_finish
+      @play_state = "finished"
+      @current_time = effect_duration_ms
+      resolve_finished
+      dispatch_event(Event.new("finish"))
+      self
+    end
+
+    def reverse
+      @playback_rate = -@playback_rate
+      play if @play_state == "idle"
+      self
+    end
+
+    # PromiseValue that resolves when the animation finishes.
+    # Rejected (with AbortError-style RuntimeError) on cancel.
+    def finished
+      @finished_promise ||= PromiseValue.new(@window)
+    end
+
+    # PromiseValue that resolves once the animation is ready to play
+    # (immediately in Dommy — there's no render-thread handoff).
+    def ready
+      @ready_promise ||= if @window
+        PromiseValue.resolve(@window, self)
+      else
+        PromiseValue.new(@window)
+      end
+    end
+
+    def __js_get__(key)
+      case key
+      when "playState"
+        @play_state
+      when "playbackRate"
+        @playback_rate
+      when "currentTime"
+        @current_time
+      when "startTime"
+        @start_time
+      when "effect"
+        @effect
+      when "timeline"
+        @timeline
+      when "finished"
+        finished
+      when "ready"
+        ready
+      when "id"
+        @id
+      end
+    end
+
+    def __js_set__(key, value)
+      case key
+      when "currentTime"
+        @current_time = value
+      when "startTime"
+        @start_time = value
+      when "playbackRate"
+        @playback_rate = value.to_f
+      when "id"
+        @id = value.to_s
+      end
+
+      nil
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "play"
+        play
+      when "pause"
+        pause
+      when "cancel"
+        cancel
+      when "finish"
+        finish
+      when "reverse"
+        reverse
+      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
+
+    # Event bubbling stops at Animation — it isn't part of the DOM tree.
+    def __internal_event_parent__
+      nil
+    end
+
+    private
+
+    def effect_duration_ms
+      @effect ? @effect.duration_ms : 0
+    end
+
+    def schedule_auto_finish
+      return unless @window&.scheduler
+      return if effect_duration_ms <= 0
+
+      @scheduled_finish_id = @window.scheduler.set_timeout(
+        proc { finish if @play_state == "running" },
+        effect_duration_ms
+      )
+    end
+
+    def cancel_scheduled_finish
+      return unless @scheduled_finish_id && @window&.scheduler
+
+      @window.scheduler.clear_timeout(@scheduled_finish_id)
+      @scheduled_finish_id = nil
+    end
+
+    def ensure_ready_resolved
+      ready.fulfill(self) if ready.respond_to?(:fulfill)
+    end
+
+    def resolve_finished
+      finished.fulfill(self)
+    end
+
+    def reject_finished_with_abort
+      return unless @finished_promise
+
+      @finished_promise.reject(RuntimeError.new("AbortError: animation cancelled"))
+    end
+  end
+end

data/lib/dommy/attr.rb

@@ -28,7 +28,7 @@ module Dommy
 
     def value
       if @owner
-        @owner.__node__[@name].to_s
+        @owner.__dommy_backend_node__[@name].to_s
       else
         @detached_value
       end
@@ -72,6 +72,12 @@ module Dommy
       nil
     end
 
+    # Methods routed through __js_call__ (keep in sync with its when-arms).
+    JS_METHOD_NAMES = %w[cloneNode].freeze
+    def __js_method_names__
+      JS_METHOD_NAMES
+    end
+
     def __js_call__(method, _args)
       case method
       when "cloneNode"
@@ -81,13 +87,13 @@ module Dommy
 
     # Internal: called by Element when the attr is being transferred
     # to (or detached from) an Element.
-    def __attach__(element)
+    def __internal_attach__(element)
       @owner = element
       @detached_value = ""
       nil
     end
 
-    def __detach__
+    def __internal_detach__
       cached = value
       @owner = nil
       @detached_value = cached
@@ -109,19 +115,19 @@ module Dommy
     end
 
     def length
-      @element.__node__.attribute_nodes.size
+      @element.__dommy_backend_node__.attribute_nodes.size
     end
 
     alias size length
 
     def item(index)
-      name = @element.__node__.attribute_nodes[index.to_i]&.name
+      name = @element.__dommy_backend_node__.attribute_nodes[index.to_i]&.name
       name && Attr.new(name, owner: @element)
     end
 
     def get_named_item(name)
       key = name.to_s.downcase
-      return nil unless @element.__node__.key?(key)
+      return nil unless @element.__dommy_backend_node__.key?(key)
 
       Attr.new(key, owner: @element)
     end
@@ -131,22 +137,22 @@ module Dommy
 
       key = attr.name
       val = attr.value
-      attr.__attach__(@element)
+      attr.__internal_attach__(@element)
       @element.set_attribute(key, val)
       attr
     end
 
     def remove_named_item(name)
       key = name.to_s.downcase
-      return nil unless @element.__node__.key?(key)
+      return nil unless @element.__dommy_backend_node__.key?(key)
 
-      attr = Attr.new(key, owner: nil, value: @element.__node__[key].to_s)
+      attr = Attr.new(key, owner: nil, value: @element.__dommy_backend_node__[key].to_s)
       @element.remove_attribute(key)
       attr
     end
 
     def each(&blk)
-      @element.__node__.attribute_nodes.each do |a|
+      @element.__dommy_backend_node__.attribute_nodes.each do |a|
         yield Attr.new(a.name, owner: @element)
       end
     end
@@ -175,6 +181,12 @@ module Dommy
       end
     end
 
+    # Methods routed through __js_call__ (keep in sync with its when-arms).
+    JS_METHOD_NAMES = %w[item getNamedItem setNamedItem removeNamedItem].freeze
+    def __js_method_names__
+      JS_METHOD_NAMES
+    end
+
     def __js_call__(method, args)
       case method
       when "item"
@@ -194,7 +206,7 @@ module Dommy
     end
 
     def respond_to_missing?(name, include_private = false)
-      @element.__node__.key?(name.to_s.downcase) || super
+      @element.__dommy_backend_node__.key?(name.to_s.downcase) || super
     end
   end
 end

data/lib/dommy/backend/nokogiri_adapter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Dommy
+  module Backend
+    # Nokogiri (libxml2-based) backend. Mature, full XML namespace
+    # support. Default backend.
+    module Nokogiri
+      # Class references for `is_a?` / type-checking from Dommy internals.
+      Element = ::Nokogiri::XML::Element
+      Document = ::Nokogiri::XML::Document
+      Text = ::Nokogiri::XML::Text
+      Comment = ::Nokogiri::XML::Comment
+      DocumentFragment = ::Nokogiri::XML::DocumentFragment
+      Node = ::Nokogiri::XML::Node
+
+      module_function
+
+      def parse(html)
+        ::Nokogiri::HTML5(html.to_s, max_errors: 0)
+      end
+
+      def fragment(html, owner_doc:)
+        # owner_doc is unused by Nokogiri — the fragment carries its
+        # own document. The Parser layer copies nodes into the target.
+        ::Nokogiri::HTML5.fragment(html.to_s, max_errors: 0)
+      end
+
+      def create_element(name, doc)
+        ::Nokogiri::XML::Node.new(name, doc)
+      end
+
+      def create_text(content, doc)
+        ::Nokogiri::XML::Text.new(content, doc)
+      end
+
+      def create_comment(content, doc)
+        ::Nokogiri::XML::Comment.new(doc, content)
+      end
+
+      def namespace_of(node)
+        node.namespace
+      end
+
+      def add_namespace_definition(node, prefix, href)
+        node.add_namespace_definition(prefix, href)
+      end
+    end
+  end
+end

data/lib/dommy/backend/nokolexbor_adapter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "nokolexbor"
+
+module Dommy
+  module Backend
+    # Nokolexbor (Lexbor-based) backend. 3-7× faster CSS selectors,
+    # 6× faster HTML5 parsing. HTML-only — XML namespaces are not
+    # tracked, so SVG detection falls back to ancestor walking.
+    module Nokolexbor
+      # Class references for `is_a?` / type-checking.
+      Element = ::Nokolexbor::Element
+      Document = ::Nokolexbor::Document
+      Text = ::Nokolexbor::Text
+      Comment = ::Nokolexbor::Comment
+      DocumentFragment = ::Nokolexbor::DocumentFragment
+      Node = ::Nokolexbor::Node
+
+      # Fake "namespace" wrapper returned for nodes inside <svg> subtrees.
+      # Provides the same `href` API that Nokogiri's Namespace object has,
+      # so calling code can treat them uniformly.
+      SvgNamespace = Struct.new(:href) do
+        def initialize
+          super("http://www.w3.org/2000/svg")
+        end
+      end
+
+      SVG_NAMESPACE = SvgNamespace.new.freeze
+
+      module_function
+
+      def parse(html)
+        ::Nokolexbor.parse(html.to_s)
+      end
+
+      def fragment(html, owner_doc:)
+        ::Nokolexbor::DocumentFragment.parse(html.to_s)
+      end
+
+      def create_element(name, doc)
+        ::Nokolexbor::Node.new(name, doc)
+      end
+
+      def create_text(content, doc)
+        ::Nokolexbor::Text.new(content, doc)
+      end
+
+      def create_comment(content, doc)
+        # Nokolexbor's argument order is (content, doc).
+        ::Nokolexbor::Comment.new(content, doc)
+      end
+
+      # Nokolexbor doesn't track XML namespaces. We synthesize one for
+      # SVG by walking ancestors — necessary so `element_class_for`
+      # routes SVG tags to their specialized classes.
+      def namespace_of(node)
+        return nil unless node.respond_to?(:name)
+
+        in_svg_subtree?(node) ? SVG_NAMESPACE : nil
+      end
+
+      def add_namespace_definition(_node, _prefix, _href)
+        # No-op: Nokolexbor doesn't support XML namespaces.
+      end
+
+      # Internal helper — visible to allow testing.
+      def in_svg_subtree?(node)
+        return true if node.name.to_s.downcase == "svg"
+
+        current = node.parent
+        while current
+          return true if current.respond_to?(:name) && current.name.to_s.downcase == "svg"
+          current = current.respond_to?(:parent) ? current.parent : nil
+        end
+
+        false
+      end
+    end
+  end
+end