dommy 0.5.0

data/lib/dommy/scheduler.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Dommy
+  # Deterministic host-side scheduler for timers, rAF, and microtasks.
+  # Time advances only when the host explicitly calls `advance_time`.
+  class Scheduler
+    Timer = Struct.new(:id, :kind, :callback, :due_at, :interval_ms, :active)
+
+    FRAME_MS = 16
+
+    def initialize
+      @now_ms = 0
+      @next_id = 1
+      @timers = {}
+      @microtasks = []
+    end
+
+    attr_reader :now_ms
+
+    def set_timeout(callback, delay_ms)
+      register_timer(:timeout, callback, delay_ms.to_i, nil)
+    end
+
+    def clear_timeout(id)
+      cancel_timer(id)
+    end
+
+    def set_interval(callback, interval_ms)
+      ms = [interval_ms.to_i, 0].max
+      register_timer(:interval, callback, ms, ms)
+    end
+
+    def clear_interval(id)
+      cancel_timer(id)
+    end
+
+    def request_animation_frame(callback)
+      frames = ((@now_ms / FRAME_MS) + 1) * FRAME_MS
+      id = next_id
+      @timers[id] = Timer.new(id, :raf, callback, frames, nil, true)
+      id
+    end
+
+    def cancel_animation_frame(id)
+      cancel_timer(id)
+    end
+
+    def queue_microtask(callback)
+      @microtasks << callback
+      nil
+    end
+
+    def drain_microtasks
+      until @microtasks.empty?
+        callback = @microtasks.shift
+        invoke_callback(callback, [@now_ms])
+      end
+
+      nil
+    end
+
+    def advance_time(delta_ms)
+      target = @now_ms + [delta_ms.to_i, 0].max
+      while next_due_timer_at && next_due_timer_at <= target
+        @now_ms = next_due_timer_at
+        run_due_timers
+        drain_microtasks
+      end
+
+      @now_ms = target
+      drain_microtasks
+      nil
+    end
+
+    def drain_timers(advance: 0)
+      advance_time(advance)
+    end
+
+    # Public accessor for eval-time auto-drain: keep advancing the
+    # clock until no timers remain (or a safety budget runs out).
+    def next_due_timer_at
+      @timers.values.select(&:active).map(&:due_at).min
+    end
+
+    private
+
+    def next_id
+      id = @next_id
+      @next_id += 1
+      id
+    end
+
+    def register_timer(kind, callback, delay_ms, interval_ms)
+      id = next_id
+      due_at = @now_ms + [delay_ms, 0].max
+      @timers[id] = Timer.new(id, kind, callback, due_at, interval_ms, true)
+      id
+    end
+
+    def cancel_timer(id)
+      timer = @timers[id.to_i]
+      timer.active = false if timer
+      @timers.delete(id.to_i)
+      nil
+    end
+
+    def run_due_timers
+      due = @timers.values.select { |timer| timer.active && timer.due_at <= @now_ms }
+      due.sort_by!(&:id)
+      due.each do |timer|
+        next unless timer.active
+
+        case timer.kind
+        when :raf
+          @timers.delete(timer.id)
+          invoke_callback(timer.callback, [@now_ms.to_f])
+        when :interval
+          invoke_callback(timer.callback, [])
+          timer.due_at = @now_ms + timer.interval_ms if timer.active
+        else
+          @timers.delete(timer.id)
+          invoke_callback(timer.callback, [])
+        end
+      end
+    end
+
+    def invoke_callback(callback, args)
+      if callback.respond_to?(:__js_call__)
+        callback.__js_call__("call", args)
+      elsif callback.respond_to?(:call)
+        callback.call(*args)
+      end
+    end
+  end
+end

data/lib/dommy/shadow_root.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `ShadowRoot` — a DocumentFragment-shaped subtree attached to a
+  # host Element via `attachShadow`. Lives in its own Nokogiri
+  # fragment that's invisible to the outer document's tree walks
+  # (querySelector, getElementById, children, etc.), which is the
+  # core "encapsulation" the spec promises.
+  #
+  # Tree manipulation works the same as a normal Element/Fragment;
+  # the boundary is enforced only on outer queries and event
+  # composition. CSS scoping (`:host`, `::slotted`) is out of scope.
+  class ShadowRoot
+    include EventTarget
+    include Node
+
+    attr_reader :__node__, :host, :mode, :delegates_focus, :slot_assignment, :document
+
+    def initialize(host, mode:, delegates_focus: false, slot_assignment: "named")
+      @host = host
+      @mode = mode.to_s
+      @delegates_focus = !!delegates_focus
+      @slot_assignment = slot_assignment.to_s
+      @document = host.document
+      @__node__ = @document.nokogiri_doc.fragment("")
+      @document.__register_shadow_fragment__(@__node__, self)
+    end
+
+    # ---- Public Ruby API (ParentNode + DocumentFragment mixin) ----
+
+    def inner_html
+      @__node__.children.map(&:to_html).join
+    end
+
+    def inner_html=(html)
+      removed = @__node__.children.to_a
+      removed.each(&:unlink)
+      fragment = Parser.fragment(html.to_s, owner_doc: @document.nokogiri_doc)
+      added = fragment.children.to_a
+      added.each { |n| @__node__.add_child(n) }
+      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: added, removed_nodes: removed)
+      nil
+    end
+
+    def text_content
+      @__node__.text
+    end
+
+    def text_content=(value)
+      @__node__.children.each(&:unlink)
+      @__node__.add_child(Nokogiri::XML::Text.new(value.to_s, @document.nokogiri_doc))
+    end
+
+    def children
+      @__node__.element_children.map { |n| @document.wrap_node(n) }.compact
+    end
+
+    def child_nodes
+      @__node__.children.map { |n| @document.wrap_node(n) }.compact
+    end
+
+    def child_element_count
+      @__node__.element_children.size
+    end
+
+    def first_child
+      @document.wrap_node(@__node__.children.first)
+    end
+
+    def last_child
+      @document.wrap_node(@__node__.children.last)
+    end
+
+    def first_element_child
+      @document.wrap_node(@__node__.element_children.first)
+    end
+
+    def last_element_child
+      @document.wrap_node(@__node__.element_children.last)
+    end
+
+    def append_child(child)
+      nodes = detach_dom_nodes(child)
+      nodes.each { |n| @__node__.add_child(n) }
+      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
+      child
+    end
+
+    def append(*args)
+      nodes = args.flat_map { |a| detach_dom_nodes(a) }
+      nodes.each { |n| @__node__.add_child(n) }
+      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
+      nil
+    end
+
+    def prepend(*args)
+      nodes = args.flat_map { |a| detach_dom_nodes(a) }
+      anchor = @__node__.children.first
+      if anchor
+        nodes.reverse_each { |n| anchor.add_previous_sibling(n) }
+      else
+        nodes.each { |n| @__node__.add_child(n) }
+      end
+
+      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
+      nil
+    end
+
+    def replace_children(*args)
+      removed = @__node__.children.to_a
+      removed.each(&:unlink)
+      nodes = args.flat_map { |a| detach_dom_nodes(a) }
+      nodes.each { |n| @__node__.add_child(n) }
+      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: removed)
+      nil
+    end
+
+    def query_selector(selector)
+      return nil if selector.nil? || selector.to_s.empty?
+
+      @document.wrap_node(@__node__.at_css(selector.to_s))
+    end
+
+    def query_selector_all(selector)
+      return NodeList.new if selector.nil? || selector.to_s.empty?
+
+      NodeList.new(@__node__.css(selector.to_s).map { |n| @document.wrap_node(n) }.compact)
+    end
+
+    def get_element_by_id(id)
+      return nil if id.nil?
+
+      @document.wrap_node(@__node__.at_css("##{id}"))
+    end
+
+    # `getRootNode()` returns the ShadowRoot itself (closed-shadow
+    # semantics; `composed: true` callers go through the Event path).
+    def get_root_node(_options = nil)
+      self
+    end
+
+    def contains?(other)
+      return false unless other.respond_to?(:__node__)
+
+      other_node = other.__node__
+      return true if other_node == @__node__
+
+      Internal::NodeTraversal.ancestor_of?(@__node__, other_node)
+    end
+
+    # `[]` accessor mirrors the bracket convention used elsewhere.
+    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 "host"
+        @host
+      when "mode"
+        @mode
+      when "delegatesFocus"
+        @delegates_focus
+      when "slotAssignment"
+        @slot_assignment
+      when "innerHTML"
+        inner_html
+      when "textContent"
+        text_content
+      when "children"
+        children
+      when "childNodes"
+        child_nodes
+      when "childElementCount"
+        child_element_count
+      when "firstChild"
+        first_child
+      when "lastChild"
+        last_child
+      when "firstElementChild"
+        first_element_child
+      when "lastElementChild"
+        last_element_child
+      when "nodeType"
+        11
+      end
+    end
+
+    def __js_set__(key, value)
+      case key
+      when "innerHTML"
+        self.inner_html = value
+      when "textContent"
+        self.text_content = value
+      end
+
+      nil
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "querySelector"
+        query_selector(args[0])
+      when "querySelectorAll"
+        query_selector_all(args[0])
+      when "getElementById"
+        get_element_by_id(args[0])
+      when "append"
+        append(*args)
+      when "prepend"
+        prepend(*args)
+      when "replaceChildren"
+        replace_children(*args)
+      when "appendChild"
+        append_child(args[0])
+      when "getRootNode"
+        get_root_node(args[0])
+      when "contains"
+        contains?(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
+
+    # Event bubbling stops at the ShadowRoot unless event has
+    # `composed: true`. The host is the bubble-path successor when
+    # composition crosses the boundary (handled in Event dispatch).
+    def __event_parent__
+      nil
+    end
+
+    private
+
+    def detach_dom_nodes(value)
+      case value
+      when String
+        [Nokogiri::XML::Text.new(value, @document.nokogiri_doc)]
+      else
+        node = value.respond_to?(:__node__) ? value.__node__ : nil
+        return [] unless node
+
+        node.unlink if node.parent
+        [node]
+      end
+    end
+  end
+end

data/lib/dommy/storage.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Dommy
+  # Hash-backed `Storage` polyfill for `localStorage` /
+  # `sessionStorage`. Mirrors the Web Storage API:
+  # `getItem(key)`, `setItem(key, value)`, `removeItem(key)`,
+  # `clear()`, `key(index)`, `length`. Values are coerced to String
+  # to match browser semantics (browser stores everything as String).
+  #
+  # No persistence across Window instances — each fresh Window gets
+  # an empty Storage. Tests that depend on cross-instance behaviour
+  # (none currently) would need explicit hydration.
+  class Storage
+    include Enumerable
+
+    def initialize
+      @store = {}
+    end
+
+    # Ruby-idiomatic facade matching `Object.keys(storage)` /
+    # `Object.values(storage)` / `Object.entries(storage)` semantics
+    # that user code reaches for in browser JS.
+
+    def keys
+      @store.keys
+    end
+
+    def values
+      @store.values
+    end
+
+    def entries
+      @store.to_a
+    end
+
+    def to_h
+      @store.dup
+    end
+
+    def each(&blk)
+      @store.each(&blk)
+    end
+
+    def length
+      @store.size
+    end
+
+    alias size length
+
+    def get_item(key)
+      @store[key.to_s]
+    end
+
+    def set_item(key, value)
+      @store[key.to_s] = value.to_s
+      nil
+    end
+
+    def remove_item(key)
+      @store.delete(key.to_s)
+      nil
+    end
+
+    def clear
+      @store.clear
+      nil
+    end
+
+    def key(index)
+      @store.keys[index.to_i]
+    end
+
+    def [](key)
+      @store[key.to_s]
+    end
+
+    def []=(key, value)
+      @store[key.to_s] = value.to_s
+    end
+
+    def __js_get__(key)
+      case key
+      when "length"
+        @store.size
+      else
+        @store[key.to_s]
+      end
+    end
+
+    def __js_set__(key, value)
+      @store[key.to_s] = value.to_s
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "getItem"
+        @store[args[0].to_s]
+      when "setItem"
+        @store[args[0].to_s] = args[1].to_s
+        nil
+      when "removeItem"
+        @store.delete(args[0].to_s)
+        nil
+      when "clear"
+        @store.clear
+        nil
+      when "key"
+        @store.keys[args[0].to_i]
+      end
+    end
+  end
+end

data/lib/dommy/test_helpers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Dommy
+  # Lightweight helpers for using Dommy from RSpec / Minitest test suites.
+  #
+  # @example RSpec
+  #   require "dommy/test_helpers"
+  #
+  #   RSpec.configure do |c|
+  #     c.include Dommy::TestHelpers
+  #   end
+  #
+  #   RSpec.describe MyComponent do
+  #     it "renders the heading" do
+  #       dom = parse_html(render(MyComponent.new))
+  #       expect(dom.query_selector("h1").text_content).to eq("Welcome")
+  #     end
+  #   end
+  #
+  # @example Minitest
+  #   require "dommy/test_helpers"
+  #
+  #   class MyComponentTest < Minitest::Test
+  #     include Dommy::TestHelpers
+  #
+  #     def test_renders_the_heading
+  #       dom = parse_html(render(MyComponent.new))
+  #       assert_equal "Welcome", dom.query_selector("h1").text_content
+  #     end
+  #   end
+  module TestHelpers
+    # Parse an HTML string into a fresh Document and return it.
+    #
+    # When the input starts with `<!doctype` or `<html>`, it is parsed as
+    # a full HTML document (preserving <head>, <title>, etc.). Otherwise
+    # the input is treated as a body fragment and inserted into a fresh
+    # document's <body>.
+    #
+    # @param html [String] HTML to parse (full document or body fragment)
+    # @return [Dommy::Document] a fresh Document with the parsed content
+    def parse_html(html = "")
+      Dommy.parse(html).document
+    end
+
+    # Build a fresh Window with the given body HTML.
+    # When a block is given, yields the window first; the same window
+    # is returned in both cases so callers can choose their style.
+    #
+    # @param body_html [String] HTML to insert inside <body>
+    # @yieldparam window [Dommy::Window]
+    # @return [Dommy::Window] the new Window
+    def make_window(body_html = "")
+      window = Dommy::Window.new
+      window.document.body.inner_html = body_html.to_s
+      yield window if block_given?
+      window
+    end
+
+    # Drain pending microtasks on the window's scheduler.
+    # Use this after a mutation if you need MutationObserver callbacks
+    # (scheduled as microtasks) to fire before your assertions.
+    #
+    # @param window [Dommy::Window]
+    def flush_microtasks(window)
+      window.scheduler.drain_microtasks
+    end
+
+    # Advance the window's virtual clock. Timers that come due and
+    # any queued microtasks are run as part of the advance.
+    # Use this to test code that schedules work with setTimeout / setInterval.
+    #
+    # @param window [Dommy::Window]
+    # @param ms [Integer] milliseconds to advance
+    def advance_time(window, ms)
+      window.scheduler.advance_time(ms)
+    end
+  end
+end