dommy 0.6.0 → 0.8.0

data/lib/dommy/event.rb

@@ -11,11 +11,13 @@ module Dommy
       return nil if type.nil? || cb.nil?
 
       list = listeners_for(type.to_s)
-      # Per spec, the same listener (by identity) registered on the
-      # same type is silently deduplicated.
-      return nil if list.any? { |entry| entry.listener.equal?(cb) }
+      entry = Listener.new(cb, options)
+      # Per spec, a listener is deduplicated by (type, callback, capture) — so
+      # the same function may be registered once as a capture and once as a
+      # bubble listener.
+      return nil if list.any? { |e| e.listener.equal?(cb) && e.capture? == entry.capture? }
 
-      list << Listener.new(cb, options)
+      list << entry
 
       # `{ signal: AbortSignal }` — when the signal aborts, auto-
       # remove the listener. Per spec, if the signal is already aborted
@@ -23,7 +25,7 @@ module Dommy
       signal = options.is_a?(Hash) ? (options["signal"] || options[:signal]) : nil
       if signal.respond_to?(:__js_get__)
         if signal.__js_get__("aborted")
-          remove_event_listener(type, cb)
+          remove_event_listener(type, cb, options)
         else
           target = self
           signal.__js_call__(
@@ -31,7 +33,7 @@ module Dommy
             [
               "abort",
               proc {
-                target.remove_event_listener(type, cb)
+                target.remove_event_listener(type, cb, options)
               }
             ]
           )
@@ -41,10 +43,16 @@ module Dommy
       nil
     end
 
-    def remove_event_listener(type, listener)
+    def remove_event_listener(type, listener, options = nil)
       return nil if type.nil? || listener.nil?
 
-      listeners_for(type.to_s).reject! { |entry| entry.listener.equal?(listener) }
+      # Per spec, a listener is identified by (type, callback, capture) — so
+      # removing must match the capture flag, not just the callback (a function
+      # registered as both a capture and a bubble listener is two listeners).
+      capture = EventTarget.capture_flag(options)
+      listeners_for(type.to_s).reject! do |entry|
+        entry.listener.equal?(listener) && entry.capture? == capture
+      end
       nil
     end
 
@@ -54,37 +62,89 @@ module Dommy
       # Per spec, dispatchEvent must receive an Event instance.
       raise TypeError, "dispatchEvent requires an Event, got #{event.class}" unless event.is_a?(Event)
 
-      event.__prepare_for_dispatch__(self)
-      path = if event.bubbles?
-        event.__js_get__("composed") ? composed_bubble_path(event) : event_bubble_path
-      else
-        [self]
-      end
+      event.__internal_prepare_for_dispatch__(self)
+      event.__internal_set_dispatch_flag__(true)
+
+      # The full propagation path: the target plus its ancestors (root last).
+      # Capturing always traverses the ancestors regardless of `bubbles`.
+      path = event.__js_get__("composed") ? composed_bubble_path(event) : event_bubble_path
+      event.__internal_record_path__(path) if event.respond_to?(:__internal_record_path__)
+      ancestors = path[1..] || []
+
+      catch(:stop_propagation) do
+        # Capturing phase: root → … → parent, capture listeners only.
+        event.__internal_set_event_phase__(Event::CAPTURING_PHASE)
+        ancestors.reverse_each do |node|
+          deliver_at(node, event, :capture)
+        end
 
-      event.__record_path__(path) if event.respond_to?(:__record_path__)
-      path.each do |target|
-        event.__set_current_target__(target)
-        target.__deliver_event__(event)
-        break if event.propagation_stopped?
+        # At the target: both capture and bubble listeners.
+        event.__internal_set_event_phase__(Event::AT_TARGET)
+        deliver_at(self, event, :both)
+
+        # Bubbling phase: parent → … → root, bubble listeners only (only when
+        # the event bubbles).
+        if event.bubbles?
+          event.__internal_set_event_phase__(Event::BUBBLING_PHASE)
+          ancestors.each do |node|
+            deliver_at(node, event, :bubble)
+          end
+        end
       end
 
+      # After dispatch, currentTarget reverts to null and eventPhase to NONE, and
+      # the propagation flags are unset so the event can be dispatched again.
+      event.__internal_set_current_target__(nil)
+      event.__internal_set_event_phase__(Event::NONE)
+      event.__internal_clear_propagation_flags__
+      event.__internal_set_dispatch_flag__(false)
+
       !event.default_prevented?
     end
 
-    def __deliver_event__(event)
+    # Deliver `event` to one node's listeners for the current phase, then honor
+    # stopPropagation (throws to end the whole walk after this node finishes).
+    def deliver_at(node, event, phase)
+      # Honor a stop-propagation flag set before reaching this node (including
+      # one set before dispatch began) — the spec checks it before invoking a
+      # node's listeners, not only after.
+      throw :stop_propagation if event.propagation_stopped?
+
+      event.__internal_set_current_target__(node)
+      node.__internal_deliver_event__(event, phase)
+      throw :stop_propagation if event.propagation_stopped?
+    end
+
+    # `phase` is :capture (capture listeners), :bubble (non-capture), or :both
+    # (at the target). stopImmediatePropagation ends delivery within this node.
+    def __internal_deliver_event__(event, phase = :both)
       listeners = listeners_for(event.type).dup
       listeners.each do |entry|
-        invoke_listener(entry.listener, event)
+        next unless phase == :both || (phase == :capture ? entry.capture? : !entry.capture?)
+
+        # Spec: a `once` listener is removed BEFORE its callback runs, so a nested
+        # dispatch from within the callback can't invoke it a second time.
         if entry.once?
-          listeners_for(event.type).reject! { |candidate| candidate.listener.equal?(entry.listener) }
+          listeners_for(event.type).reject! do |candidate|
+            candidate.listener.equal?(entry.listener) && candidate.capture? == entry.capture?
+          end
         end
 
+        CallableInvoker.invoke_listener(entry.listener, event)
+
         break if event.immediate_propagation_stopped?
       end
 
       nil
     end
 
+    # The next target up the propagation path. The default (no parent) suits
+    # EventTargets that aren't tree nodes (AbortSignal, XHR, …); Element /
+    # Document / ShadowRoot override it to walk the node tree.
+    def __internal_event_parent__
+      nil
+    end
+
     private
 
     Listener = Struct.new(:listener, :options) do
@@ -96,6 +156,37 @@ module Dommy
           false
         end
       end
+
+      # useCapture: a boolean third argument, or `{capture: …}` in the options
+      # dictionary. A capture listener fires in the capturing phase; a non-capture
+      # listener in the bubbling phase (both at the target).
+      def capture?
+        EventTarget.capture_flag(options)
+      end
+    end
+
+    # The capture flag for an addEventListener/removeEventListener options
+    # argument, using JS — not Ruby — truthiness: a boolean useCapture, or the
+    # `capture` member of an options dictionary, where 0 / "" / NaN / null /
+    # undefined are falsy (in Ruby 0 and "" are truthy, so a naive `!!` is wrong).
+    def self.capture_flag(options)
+      raw =
+        if options.is_a?(Hash)
+          options.key?("capture") ? options["capture"] : options[:capture]
+        else
+          options
+        end
+      js_truthy?(raw)
+    end
+
+    # JS ToBoolean: false for false/null/undefined, +0/-0, NaN, and "".
+    def self.js_truthy?(value)
+      return false if value.nil? || value == false
+      return false if defined?(Bridge::UNDEFINED) && value.equal?(Bridge::UNDEFINED)
+      return false if value.is_a?(Numeric) && (value.zero? || (value.respond_to?(:nan?) && value.nan?))
+      return false if value == ""
+
+      true
     end
 
     def listeners_for(type)
@@ -106,7 +197,7 @@ module Dommy
     def event_bubble_path
       path = [self]
       current = self
-      while (current = current.send(:__event_parent__))
+      while (current = current.__send__(:__internal_event_parent__))
         path << current
       end
 
@@ -116,12 +207,12 @@ module Dommy
     # Build the propagation path with optional shadow-boundary
     # crossing. When the in-flight event has `composed: true`, the
     # walk continues from a ShadowRoot to its host; otherwise it
-    # stops at the shadow boundary (nil from `__event_parent__`).
+    # stops at the shadow boundary (nil from `__internal_event_parent__`).
     def composed_bubble_path(event)
       path = [self]
       current = self
       loop do
-        nxt = current.send(:__event_parent__)
+        nxt = current.__send__(:__internal_event_parent__)
         if nxt.nil? && event.respond_to?(:__js_get__) && event.__js_get__("composed")
           # Try to cross a shadow boundary
           if current.is_a?(ShadowRoot)
@@ -148,42 +239,27 @@ module Dommy
     private
 
     def enclosing_shadow_root_of(target)
-      return nil unless target.respond_to?(:__node__)
+      return nil unless target.respond_to?(:__dommy_backend_node__)
 
       doc = target.instance_variable_get(:@document)
-      return nil unless doc && doc.respond_to?(:__shadow_root_containing__)
+      return nil unless doc && doc.respond_to?(:__internal_shadow_root_containing__)
 
-      doc.__shadow_root_containing__(target.__node__)
+      doc.__internal_shadow_root_containing__(target.__dommy_backend_node__)
     end
 
-    public
-
-    def invoke_listener(listener, event)
-      # DOM spec: a listener can be (a) a function, or (b) an object
-      # with a `handleEvent` method. Both Ruby and JS-bridged callables
-      # are supported.
-      if listener.respond_to?(:handle_event)
-        listener.handle_event(event)
-      elsif listener.respond_to?(:call) && !listener.is_a?(Module)
-        listener.call(event)
-      elsif listener.respond_to?(:__js_call__)
-        # Prefer handleEvent if the bridge object advertises it; fall
-        # back to call. We can't introspect on the JS side, so we just
-        # try call (the common case for JS.callback {}).
-        listener.__js_call__("call", [event])
-      end
-    end
   end
 
   class StandaloneEventTarget
     include EventTarget
 
+    include Bridge::Methods
+    js_methods %w[addEventListener removeEventListener dispatchEvent]
     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])
+        remove_event_listener(args[0], args[1], args[2])
       when "dispatchEvent"
         dispatch_event(args[0])
       else
@@ -191,12 +267,17 @@ module Dommy
       end
     end
 
-    def __event_parent__
+    def __internal_event_parent__
       nil
     end
   end
 
   class Event
+    NONE = 0
+    CAPTURING_PHASE = 1
+    AT_TARGET = 2
+    BUBBLING_PHASE = 3
+
     def initialize(type, init = nil)
       @type = type.to_s
       @bubbles = !!read_init(init, "bubbles")
@@ -207,11 +288,20 @@ module Dommy
       @immediate_propagation_stopped = false
       @target = nil
       @current_target = nil
+      @event_phase = NONE
       @composed_path = []
       # `timeStamp` is the high-resolution timestamp at construction
       # in ms (browser uses performance.now). We use monotonic time
       # for determinism across spec runs.
       @time_stamp = (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0)
+      @trusted = false
+    end
+
+    # Mark this event as UA-generated (`isTrusted === true`). Used by the host
+    # for events it fires itself (e.g. AbortSignal's "abort").
+    def __internal_mark_trusted__
+      @trusted = true
+      self
     end
 
     attr_reader :type
@@ -232,14 +322,29 @@ module Dommy
       @immediate_propagation_stopped
     end
 
-    def __prepare_for_dispatch__(target)
+    def __internal_prepare_for_dispatch__(target)
       @target ||= target
     end
 
-    def __set_current_target__(target)
+    # End-of-dispatch cleanup: the dispatch algorithm unsets the stop-propagation
+    # and stop-immediate-propagation flags (but NOT the canceled flag), so the
+    # same event object can be dispatched again. A stopPropagation() issued
+    # before the next dispatch is still honored — only the post-dispatch state is
+    # cleared here.
+    def __internal_clear_propagation_flags__
+      @propagation_stopped = false
+      @immediate_propagation_stopped = false
+      nil
+    end
+
+    def __internal_set_current_target__(target)
       @current_target = target
     end
 
+    def __internal_set_event_phase__(phase)
+      @event_phase = phase
+    end
+
     def __js_get__(key)
       case key
       when "type"
@@ -252,7 +357,15 @@ module Dommy
         @composed
       when "defaultPrevented"
         @default_prevented
-      when "target"
+      when "returnValue"
+        # Legacy alias: false once the default has been prevented, else true.
+        !@default_prevented
+      when "isTrusted"
+        # Script-created events are untrusted; a UA-fired event (e.g. an
+        # AbortSignal's "abort") is marked trusted via __internal_mark_trusted__.
+        @trusted == true
+      when "target", "srcElement"
+        # srcElement is a legacy alias of target — null (not undefined) when unset.
         @target
       when "currentTarget"
         @current_target
@@ -262,6 +375,12 @@ module Dommy
         @propagation_stopped
       when "eventPhase"
         event_phase
+      else
+        # An unknown property reads back as JS `undefined`, not `null` — e.g. a
+        # non-dictionary member passed to the constructor (`new Event("x", {sweet:
+        # 1}).sweet`) is not reflected on the event. Genuinely-null DOM attributes
+        # (target/currentTarget/…) are explicit cases above and still return nil.
+        Bridge::UNDEFINED
       end
     end
 
@@ -271,11 +390,19 @@ module Dommy
         # Setting to truthy stops propagation; spec quirk that
         # `cancelBubble = false` does NOT un-stop (browser observation).
         @propagation_stopped = true if value
+      when "returnValue"
+        # Legacy alias: returnValue = false cancels the event (like
+        # preventDefault); a truthy value does not un-cancel.
+        @default_prevented = true if !value && @cancelable
+      else
+        return Bridge::UNHANDLED
       end
 
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[preventDefault stopPropagation stopImmediatePropagation composedPath initEvent]
     def __js_call__(method, args)
       case method
       when "preventDefault"
@@ -291,14 +418,26 @@ module Dommy
       when "composedPath"
         @composed_path.dup
       when "initEvent"
+        # WebIDL: the `type` argument is mandatory.
+        raise Bridge::TypeError, "initEvent requires a type argument" if args.empty?
+
         init_event(args[0], args[1], args[2])
       end
     end
 
+    # Set while the event is being dispatched, so initEvent() can short-circuit.
+    def __internal_set_dispatch_flag__(flag)
+      @dispatch_flag = flag
+      nil
+    end
+
     # Deprecated `Event#initEvent(type, bubbles, cancelable)` — older
     # browsers used `document.createEvent("Event").initEvent(...)`.
     # Resets internal flags as a side effect.
     def init_event(type, bubbles = false, cancelable = false)
+      # Spec: initEvent is a no-op while the event is being dispatched.
+      return nil if @dispatch_flag
+
       @type = type.to_s
       @bubbles = !!bubbles
       @cancelable = !!cancelable
@@ -314,7 +453,7 @@ module Dommy
     # Per spec, `load` events do not propagate to the Window when
     # composed paths are computed (resource-finished signal stays at
     # the target).
-    def __record_path__(targets)
+    def __internal_record_path__(targets)
       @composed_path = if @type == "load"
         targets.reject { |t| t.is_a?(Window) }
       else
@@ -325,18 +464,9 @@ module Dommy
     private
 
     def event_phase
-      # 0 = NONE (default), 2 = AT_TARGET, 3 = BUBBLING_PHASE. We don't
-      # implement capturing (phase 1) by design.
-      return 0 if @current_target.nil?
-      return 2 if @current_target.equal?(@target)
-
-      3
+      @event_phase
     end
 
-    public
-
-    private
-
     def read_init(init, key)
       case init
       when Hash
@@ -360,6 +490,45 @@ module Dommy
 
       super
     end
+
+    js_methods %w[initCustomEvent]
+    def __js_call__(method, args)
+      case method
+      when "initCustomEvent"
+        # Deprecated initCustomEvent(type, bubbles=false, cancelable=false,
+        # detail=null). Like initEvent, the type is mandatory and the whole call
+        # is a no-op while the event is being dispatched.
+        raise Bridge::TypeError, "initCustomEvent requires a type argument" if args.empty?
+
+        unless @dispatch_flag
+          init_event(args[0], args[1], args[2])
+          @detail = args[3]
+        end
+        nil
+      else
+        super
+      end
+    end
+  end
+
+  # PopStateEvent — fired on history back/forward. Exposes the history entry's
+  # serialized state via `event.state` (the spec property; framework routers like
+  # Turbo read `event.state.turbo` to recognise their own navigations and restore
+  # the cached page). A plain `Event` subclass per spec — NOT a CustomEvent, so it
+  # has no `detail` and `instanceof CustomEvent` is false.
+  class PopStateEvent < Event
+    attr_reader :state
+
+    def initialize(type, init = nil)
+      super
+      @state = read_init(init, "state")
+    end
+
+    def __js_get__(key)
+      return @state if key == "state"
+
+      super
+    end
   end
 
   class MouseEvent < Event
@@ -640,6 +809,8 @@ module Dommy
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[item]
     def __js_call__(method, args)
       case method
       when "item"
@@ -821,9 +992,9 @@ module Dommy
 
     # Spec: `AbortSignal.abort(reason?)` returns a fresh, pre-aborted
     # signal. Convenient for APIs that need an already-cancelled token.
-    def self.abort(reason = nil)
+    def self.abort(*reason)
       signal = new
-      signal.__mark_aborted__(reason)
+      signal.__internal_mark_aborted__(*reason)
       signal
     end
 
@@ -836,9 +1007,9 @@ module Dommy
       signal = new
       reason = DOMException::TimeoutError.new("operation timed out")
       if scheduler
-        scheduler.set_timeout(proc { signal.__mark_aborted__(reason) }, ms.to_i)
+        scheduler.set_timeout(proc { signal.__internal_mark_aborted__(reason) }, ms.to_i)
       else
-        signal.__schedule_thread_timeout__(ms.to_i, reason)
+        signal.__internal_schedule_thread_timeout__(ms.to_i, reason)
       end
 
       signal
@@ -853,12 +1024,12 @@ module Dommy
       list = Array(signals).select { |s| s.is_a?(AbortSignal) }
       already = list.find(&:aborted?)
       if already
-        composite.__mark_aborted__(already.reason)
+        composite.__internal_mark_aborted__(already.reason)
         return composite
       end
 
       list.each do |sig|
-        sig.add_event_listener("abort", proc { composite.__mark_aborted__(sig.reason) })
+        sig.add_event_listener("abort", proc { composite.__internal_mark_aborted__(sig.reason) })
       end
 
       composite
@@ -871,11 +1042,11 @@ module Dommy
 
     # Background-thread timeout used by `AbortSignal.timeout` when no
     # scheduler is provided. Kept package-private; tests can also
-    # drive the abort manually via `__mark_aborted__`.
-    def __schedule_thread_timeout__(ms, reason)
+    # drive the abort manually via `__internal_mark_aborted__`.
+    def __internal_schedule_thread_timeout__(ms, reason)
       Thread.new do
         sleep(ms.to_f / 1000.0)
-        __mark_aborted__(reason)
+        __internal_mark_aborted__(reason)
       end
 
       nil
@@ -893,8 +1064,12 @@ module Dommy
     # consumer code that polls before doing async work.
     def throw_if_aborted
       return unless @aborted
+      # An Exception reason (the default AbortError, or an explicit DOMException)
+      # is raised so the bridge tags it as a real JS error; any other reason — a
+      # string, number, or opaque JSValue — is thrown verbatim, identity kept.
+      raise @reason if @reason.is_a?(Exception)
 
-      raise @reason.is_a?(Exception) ? @reason : RuntimeError.new(@reason.to_s)
+      raise Bridge::ThrowValue.new(@reason)
     end
 
     alias throwIfAborted throw_if_aborted
@@ -904,20 +1079,35 @@ module Dommy
       when "aborted"
         @aborted
       when "reason"
-        @reason
+        # A non-aborted signal's reason is `undefined` (not null); once aborted
+        # it is the abort reason (an explicit value or the default AbortError).
+        @aborted ? @reason : Bridge::UNDEFINED
+      when "onabort"
+        @onabort_handler
       end
     end
 
-    def __js_set__(_key, _value)
+    # `signal.onabort = fn` is an event-handler IDL attribute: it registers a
+    # single "abort" listener (replacing any previous one); null/undefined clears
+    # it. (Setting it after the signal is already aborted never fires.)
+    def __js_set__(key, value)
+      return Bridge::UNHANDLED unless key == "onabort"
+
+      remove_event_listener("abort", @onabort_handler) if @onabort_handler
+      cleared = value.nil? || (defined?(Bridge::UNDEFINED) && value.equal?(Bridge::UNDEFINED))
+      @onabort_handler = cleared ? nil : value
+      add_event_listener("abort", @onabort_handler) if @onabort_handler
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[addEventListener removeEventListener dispatchEvent throwIfAborted]
     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])
+        remove_event_listener(args[0], args[1], args[2])
       when "dispatchEvent"
         dispatch_event(args[0])
       when "throwIfAborted"
@@ -925,12 +1115,18 @@ module Dommy
       end
     end
 
-    def __mark_aborted__(reason = nil)
+    # Sentinel meaning "no reason argument was supplied" — distinct from an
+    # explicit `null` reason (`abort(null)` keeps reason null, but `abort()` /
+    # `abort(undefined)` default to a fresh AbortError).
+    NO_REASON = Object.new
+
+    def __internal_mark_aborted__(reason = NO_REASON)
       return if @aborted
 
       @aborted = true
-      @reason = reason
-      dispatch_event(Event.new("abort", "bubbles" => false, "cancelable" => false))
+      no_reason = reason.equal?(NO_REASON) || (defined?(Bridge::UNDEFINED) && reason.equal?(Bridge::UNDEFINED))
+      @reason = no_reason ? DOMException::AbortError.new("signal is aborted without reason") : reason
+      dispatch_event(Event.new("abort", "bubbles" => false, "cancelable" => false).__internal_mark_trusted__)
     end
   end
 
@@ -946,13 +1142,17 @@ module Dommy
     end
 
     def __js_set__(_key, _value)
-      nil
+      Bridge::UNHANDLED
     end
 
+    include Bridge::Methods
+    js_methods %w[abort]
     def __js_call__(method, args)
       case method
       when "abort"
-        @signal.__mark_aborted__(args[0])
+        # `abort()` (no arg) defaults the reason; `abort(reason)` — even
+        # `abort(null)` — keeps the explicit reason.
+        args.empty? ? @signal.__internal_mark_aborted__ : @signal.__internal_mark_aborted__(args[0])
       end
     end
   end