dommy 0.5.0

data/lib/dommy/observer.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "internal/observer_matcher"
+
+module Dommy
+  # MutationRecord — produced for childList, attributes, or
+  # characterData mutations and delivered to the observer callback.
+  # Mirrors the browser MutationRecord interface; `oldValue` is only
+  # populated when the observer asked for it via `attributeOldValue`
+  # / `characterDataOldValue`.
+  class MutationRecord
+    def initialize(
+      type:,
+      target:,
+      added_nodes: [],
+      removed_nodes: [],
+      previous_sibling: nil,
+      next_sibling: nil,
+      attribute_name: nil,
+      attribute_namespace: nil,
+      old_value: nil
+    )
+      @type = type
+      @target = target
+      @added_nodes = added_nodes
+      @removed_nodes = removed_nodes
+      @previous_sibling = previous_sibling
+      @next_sibling = next_sibling
+      @attribute_name = attribute_name
+      @attribute_namespace = attribute_namespace
+      @old_value = old_value
+    end
+
+    attr_reader(
+      :type,
+      :target,
+      :added_nodes,
+      :removed_nodes,
+      :previous_sibling,
+      :next_sibling,
+      :attribute_name,
+      :attribute_namespace,
+      :old_value
+    )
+
+    def __js_get__(key)
+      case key
+      when "type"
+        @type
+      when "target"
+        @target
+      when "addedNodes"
+        @added_nodes
+      when "removedNodes"
+        @removed_nodes
+      when "previousSibling"
+        @previous_sibling
+      when "nextSibling"
+        @next_sibling
+      when "attributeName"
+        @attribute_name
+      when "attributeNamespace"
+        @attribute_namespace
+      when "oldValue"
+        @old_value
+      end
+    end
+  end
+
+  class MutationObserver
+    def initialize(window, callback)
+      @window = window
+      @document = window.document
+      @callback = callback
+      @observed = []
+      @records = []
+      @scheduled = false
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "observe"
+        observe(args[0], args[1])
+      when "disconnect"
+        disconnect
+      when "takeRecords"
+        take_records
+      end
+    end
+
+    # Matches a wrapped target against this observer's scope.
+    # Called by MutationCoordinator.
+    def matches_wrapped?(target_wrapped)
+      find_matching_entry(target_wrapped) != nil
+    end
+
+    # Find the observer entry that matches target_wrapped.
+    # Returns the entry with options (attributes, attributeFilter, etc.)
+    # or nil if target doesn't match any observed scope.
+    def find_matching_entry(target_wrapped)
+      matcher = Internal::ObserverMatcher.new
+      @observed.find do |entry|
+        observed_wrapped = entry[:target]
+        next false unless observed_wrapped
+
+        if observed_wrapped.is_a?(Document)
+          matcher.matches_document?(target_wrapped, subtree: entry[:subtree])
+        else
+          matcher.matches?(observed_wrapped, target_wrapped, subtree: entry[:subtree])
+        end
+      end
+    end
+
+    def enqueue(record)
+      @records << record
+      return nil if @scheduled
+
+      @scheduled = true
+      @window.scheduler.queue_microtask(proc { flush })
+      nil
+    end
+
+    # Public: introspection used by linkedom-style tests that peek at
+    # pending records without draining (`observer.records[0]`).
+    def records
+      @records.dup
+    end
+
+    private
+
+    def observe(target, options)
+      opts = options.is_a?(Hash) ? options : {}
+      attribute_filter = opts["attributeFilter"] || opts[:attributeFilter]
+      attribute_filter = attribute_filter.map { |s| s.to_s.downcase } if attribute_filter.is_a?(Array)
+      # `attributes: true` is implied if attributeFilter / attributeOldValue
+      # is supplied; `characterData: true` is implied if
+      # characterDataOldValue is supplied. Matches the spec's option
+      # normalization in MutationObserverInit.
+      attrs_implied = !attribute_filter.nil? || truthy_option(opts, "attributeOldValue")
+      char_implied = truthy_option(opts, "characterDataOldValue")
+      attributes_on = truthy_option(opts, "attributes") || attrs_implied
+      child_list_on = truthy_option(opts, "childList")
+      character_data_on = truthy_option(opts, "characterData") || char_implied
+
+      # Per spec, observe() must request at least one of childList,
+      # attributes, or characterData; otherwise TypeError.
+      unless child_list_on || attributes_on || character_data_on
+        raise TypeError, "MutationObserver.observe: at least one of childList, attributes, characterData must be true"
+      end
+
+      @observed <<
+        {
+          target: target,
+          child_list: child_list_on,
+          subtree: truthy_option(opts, "subtree"),
+          attributes: attributes_on,
+          attribute_filter: attribute_filter,
+          attribute_old_value: truthy_option(opts, "attributeOldValue"),
+          character_data: character_data_on,
+          character_data_old_value: truthy_option(opts, "characterDataOldValue")
+        }
+      @document.register_observer(self)
+      nil
+    end
+
+    def disconnect
+      @records.clear
+      @scheduled = false
+      @observed.clear
+      @document.unregister_observer(self)
+      nil
+    end
+
+    def take_records
+      out = @records.dup
+      @records.clear
+      @scheduled = false
+      out
+    end
+
+    def flush
+      @scheduled = false
+      return if @records.empty?
+
+      records = @records.dup
+      @records.clear
+      if @callback.respond_to?(:__js_call__)
+        @callback.__js_call__("call", [records])
+      elsif @callback.respond_to?(:call)
+        @callback.call(records)
+      end
+    end
+
+    def truthy_option(hash, key)
+      value = hash[key] || hash[key.to_sym]
+      value == true || value.to_s == "true"
+    end
+  end
+end

data/lib/dommy/parser.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Dommy
+  # Thin wrapper around Nokogiri's HTML5 fragment parser. Pinned to
+  # `max_errors: 0` for silent recovery on malformed HTML (matching
+  # browser behavior).
+  #
+  # Known quirks: `<table>`-only fragments wrap children in an
+  # implicit `<tbody>`; `<select>` reparents non-option children
+  # outside itself.
+  #
+  # `owner_doc` is critical: when a node parsed via a detached
+  # fragment gets `add_child`'d into a Document with a different
+  # Nokogiri owner, libxml2 silently **copies** the node (new
+  # object_id) instead of moving it. That breaks identity-dependent
+  # caches (e.g. `Document#wrap_node` and any reconciler that keys
+  # off node identity). Always pass the destination document.
+  module Parser
+    def self.fragment(html, owner_doc: nil)
+      if owner_doc
+        owner_doc.fragment(html.to_s)
+      else
+        Nokogiri::HTML5.fragment(html.to_s, max_errors: 0)
+      end
+    end
+  end
+end

data/lib/dommy/promise.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Dommy
+  class ErrorValue
+    def initialize(message = nil, name: "Error")
+      @message = message.to_s
+      @name = name
+    end
+
+    def __js_get__(key)
+      case key
+      when "message"
+        @message
+      when "name"
+        @name
+      else
+        nil
+      end
+    end
+
+    def to_s
+      return @name if @message.empty?
+
+      "#{@name}: #{@message}"
+    end
+  end
+
+  # Note: `PromiseConstructor` and `PromiseSettler` live in
+  # `Dommy::Bridge::*` — they're bridge-adapter classes for the
+  # `JS.global[:Promise]` view, not part of the public DOM surface.
+
+  class PromiseValue
+    Handler = Struct.new(:on_fulfilled, :on_rejected, :child)
+
+    def self.resolve(window, value)
+      promise = new(window)
+      promise.fulfill(value)
+      promise
+    end
+
+    def self.reject(window, reason)
+      promise = new(window)
+      promise.reject(reason)
+      promise
+    end
+
+    def initialize(window)
+      @window = window
+      @state = :pending
+      @value = nil
+      @handlers = []
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "then"
+        attach_then(args[0], args[1])
+      when "catch"
+        attach_then(nil, args[0])
+      else
+        nil
+      end
+    end
+
+    def fulfill(value)
+      settle(:fulfilled, value)
+    end
+
+    def reject(reason)
+      settle(:rejected, reason)
+    end
+
+    # Synchronously unwrap the promise's settled value, or raise its
+    # rejection. Dommy's scheduler is deterministic, so "wait" is
+    # spelled "drain queued microtasks then read the state."
+    #
+    # This is the bridge between dommy's async APIs (fetch, etc.) and
+    # Ruby tests that want to write straight-line code:
+    #
+    #   response = win.__js_call__("fetch", [url]).await
+    #   text     = response.text
+    #
+    # Raises `RuntimeError` if the promise is still pending after a
+    # microtask drain — that's a sign that real-time work (e.g. a
+    # `setTimeout`) needs to advance via `advance_time` first.
+    def await
+      @window&.scheduler&.drain_microtasks
+
+      case @state
+      when :fulfilled
+        @value
+      when :rejected
+        raise unwrap_rejection(@value)
+      else
+        raise "Promise#await: still pending after microtask drain"
+      end
+    end
+
+    private
+
+    def unwrap_rejection(value)
+      case value
+      when Exception
+        value
+      when ErrorValue
+        RuntimeError.new(value.to_s)
+      else
+        RuntimeError.new(value.to_s)
+      end
+    end
+
+    def attach_then(on_fulfilled, on_rejected)
+      child = self.class.new(@window)
+      @handlers << Handler.new(on_fulfilled, on_rejected, child)
+      schedule_flush if settled?
+      child
+    end
+
+    def settle(state, value)
+      return self if settled?
+
+      if value.is_a?(PromiseValue)
+        return adopt(value)
+      end
+
+      @state = state
+      @value = value
+      schedule_flush
+      self
+    end
+
+    def adopt(other)
+      other.__js_call__(
+        "then",
+        [
+          proc { |resolved| fulfill(resolved) },
+          proc { |reason| reject(reason) }
+        ]
+      )
+      self
+    end
+
+    def settled?
+      @state != :pending
+    end
+
+    def schedule_flush
+      @window.scheduler.queue_microtask(proc { flush_handlers })
+      nil
+    end
+
+    def flush_handlers
+      return unless settled?
+      return if @handlers.empty?
+
+      handlers = @handlers.dup
+      @handlers.clear
+      handlers.each do |handler|
+        run_handler(handler)
+      end
+    end
+
+    def run_handler(handler)
+      callback = @state == :fulfilled ? handler.on_fulfilled : handler.on_rejected
+      if callback.nil?
+        propagate(handler.child)
+        return
+      end
+
+      result = invoke_callback(callback, @value)
+      if result.is_a?(PromiseValue)
+        result.__js_call__(
+          "then",
+          [
+            proc { |resolved| handler.child.fulfill(resolved) },
+            proc { |reason| handler.child.reject(reason) }
+          ]
+        )
+      else
+        handler.child.fulfill(result)
+      end
+
+    rescue StandardError => e
+      handler.child.reject(ErrorValue.new(e.message, name: e.class.to_s))
+    end
+
+    def propagate(child)
+      @state == :fulfilled ? child.fulfill(@value) : child.reject(@value)
+    end
+
+    def invoke_callback(callback, value)
+      if callback.respond_to?(:__js_call__)
+        callback.__js_call__("call", [value])
+      else
+        callback.call(value)
+      end
+    end
+  end
+end

data/lib/dommy/router.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Dommy
+  # `window.location` polyfill. The Window owns one Location and one
+  # History instance, and they share the same underlying state. Hash
+  # / pushState / replaceState all flow through `__set_url__`.
+  class Location
+    def initialize(window, origin: "http://localhost", pathname: "/", search: "", hash: "")
+      @window = window
+      @origin = origin
+      @pathname = pathname
+      @search = search
+      @hash = hash
+    end
+
+    def __js_get__(key)
+      case key
+      when "origin"
+        @origin
+      when "pathname"
+        @pathname
+      when "search"
+        @search
+      when "hash"
+        @hash
+      when "href"
+        href
+      when "host"
+        URI(@origin).host || ""
+      when "hostname"
+        URI(@origin).host || ""
+      when "protocol"
+        URI(@origin).scheme ? "#{URI(@origin).scheme}:" : ""
+      when "port"
+        (URI(@origin).port || 80).to_s
+      end
+    end
+
+    def __js_set__(key, value)
+      case key
+      when "href"
+        __set_url__(value.to_s)
+      when "hash"
+        new_hash = value.to_s
+        new_hash = "##{new_hash}" unless new_hash.empty? || new_hash.start_with?("#")
+        previous = @hash
+        @hash = new_hash
+        @window.fire_hashchange(previous, @hash) if previous != @hash
+      when "pathname"
+        @pathname = value.to_s
+      when "search"
+        s = value.to_s
+        @search = s.empty? || s.start_with?("?") ? s : "?#{s}"
+      when "host"
+        # `host` is "hostname[:port]" — split and update origin.
+        update_origin_host(value.to_s)
+      when "hostname"
+        update_origin_hostname(value.to_s)
+      when "port"
+        update_origin_port(value.to_s)
+      when "protocol"
+        update_origin_protocol(value.to_s)
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "assign", "replace"
+        __set_url__(args[0].to_s)
+      when "reload"
+        nil
+      when "toString"
+        href
+      end
+    end
+
+    def href
+      "#{@origin}#{@pathname}#{@search}#{@hash}"
+    end
+
+    # Internal — accepts an absolute or relative URL string and
+    # updates pathname / search / hash. Called by History pushState /
+    # replaceState and by `location.href = ...`.
+    def __set_url__(raw)
+      previous_hash = @hash
+      if raw.start_with?("#")
+        @hash = raw
+      else
+        uri = URI.join(@origin + @pathname + @search + @hash, raw) rescue URI(raw)
+        @pathname = uri.path.to_s == "" ? "/" : uri.path
+        @search = uri.query ? "?#{uri.query}" : ""
+        @hash = uri.fragment ? "##{uri.fragment}" : ""
+      end
+
+      @window.fire_hashchange(previous_hash, @hash) if previous_hash != @hash
+    end
+
+    private
+
+    def origin_parts
+      uri = URI(@origin)
+      {scheme: uri.scheme, host: uri.host, port: uri.port}
+    rescue URI::InvalidURIError, ArgumentError
+      {scheme: "http", host: "localhost", port: 80}
+    end
+
+    def rebuild_origin(scheme:, host:, port:)
+      default_port = (scheme == "https" ? 443 : 80)
+      port_segment = (port && port != default_port) ? ":#{port}" : ""
+      @origin = "#{scheme}://#{host}#{port_segment}"
+    end
+
+    def update_origin_host(value)
+      hostname, port = value.split(":", 2)
+      parts = origin_parts
+      rebuild_origin(scheme: parts[:scheme], host: hostname, port: port&.to_i || parts[:port])
+    end
+
+    def update_origin_hostname(value)
+      parts = origin_parts
+      rebuild_origin(scheme: parts[:scheme], host: value, port: parts[:port])
+    end
+
+    def update_origin_port(value)
+      parts = origin_parts
+      rebuild_origin(scheme: parts[:scheme], host: parts[:host], port: value.to_i)
+    end
+
+    def update_origin_protocol(value)
+      parts = origin_parts
+      scheme = value.to_s.sub(/:\z/, "")
+      rebuild_origin(scheme: scheme, host: parts[:host], port: parts[:port])
+    end
+  end
+
+  # `window.history` polyfill. Stack-based; back/forward move the
+  # cursor. pushState appends; replaceState mutates the current entry.
+  # Each entry is `{ state:, url: }`. Popstate fires when back /
+  # forward triggers a different cursor (not on pushState per spec).
+  class History
+    def initialize(window, location)
+      @window = window
+      @location = location
+      # Initial entry mirrors the live Location. Bookmark URL is
+      # resynthesized lazily from Location each time we read it.
+      @stack = [{state: nil, url: nil}]
+      @cursor = 0
+      @scroll_restoration = "auto"
+    end
+
+    def __js_get__(key)
+      case key
+      when "length"
+        @stack.size
+      when "state"
+        @stack[@cursor][:state]
+      when "scrollRestoration"
+        @scroll_restoration
+      end
+    end
+
+    def __js_set__(key, value)
+      case key
+      when "scrollRestoration"
+        # Per spec, only "auto" and "manual" are accepted. Invalid
+        # values silently retain the current value.
+        v = value.to_s
+        @scroll_restoration = v if %w[auto manual].include?(v)
+      end
+
+      nil
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "pushState"
+        push(args[0], args[2])
+      when "replaceState"
+        replace(args[0], args[2])
+      when "back"
+        go(-1)
+      when "forward"
+        go(1)
+      when "go"
+        go((args[0] || 0).to_i)
+      end
+    end
+
+    private
+
+    def push(state, url)
+      @stack = @stack[0..@cursor]
+      @location.__set_url__(url.to_s) if url
+      @stack << {state: state, url: nil}
+      @cursor = @stack.size - 1
+    end
+
+    def replace(state, url)
+      @location.__set_url__(url.to_s) if url
+      @stack[@cursor] = {state: state, url: nil}
+    end
+
+    def go(delta)
+      target = @cursor + delta
+      return if target < 0 || target >= @stack.size
+
+      @cursor = target
+      @window.fire_popstate(@stack[@cursor][:state])
+    end
+  end
+
+  # `URL` constructor — Ruby `URI` wrap. Browser URL API surface:
+  # `[:origin]`, `[:pathname]`, `[:search]`, `[:hash]`, `[:href]`.
+  # Supports the two-arg form `new URL(raw, base)`.
+  class Url
+    def initialize(raw, base = nil)
+      uri = if base && !base.empty?
+        URI.join(base, raw)
+      else
+        URI(raw.to_s)
+      end
+
+      @origin = origin_of(uri)
+      @pathname = uri.path.to_s == "" ? "/" : uri.path
+      @search = uri.query ? "?#{uri.query}" : ""
+      @hash = uri.fragment ? "##{uri.fragment}" : ""
+      @href = uri.to_s
+    rescue URI::InvalidURIError, ArgumentError
+      @origin = ""
+      @pathname = ""
+      @search = ""
+      @hash = ""
+      @href = raw.to_s
+    end
+
+    def __js_get__(key)
+      case key
+      when "origin"
+        @origin
+      when "pathname"
+        @pathname
+      when "search"
+        @search
+      when "hash"
+        @hash
+      when "href"
+        @href
+      when "toString"
+        @href
+      end
+    end
+
+    def __js_set__(_key, _value)
+      nil
+    end
+
+    def __js_call__(method, _args)
+      method == "toString" ? @href : nil
+    end
+
+    private
+
+    def origin_of(uri)
+      scheme = uri.scheme
+      host = uri.host
+      return "" unless scheme && host
+
+      port = uri.port
+      default = (scheme == "https" ? 443 : 80)
+      port == default ? "#{scheme}://#{host}" : "#{scheme}://#{host}:#{port}"
+    end
+  end
+end