dommy 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 217a4ff53f58e6c12e424951b057cc0d3cbab3b898fdb85d5fd69ca7c34cd3c5
+  data.tar.gz: bedaba24772a900d85e62a27729b8e62f8db8a18e0b48360f1717799108432f8
+SHA512:
+  metadata.gz: 3a9687cf21dde61fa2c65cd47ca90f18e4d65da61912ffdbd8366cbf75f1110a96da52c43a27abee498dc9f2a19ffc306a491e14bb6aa4d985f7dd74fec88816
+  data.tar.gz: 201bb5b9217bc0373923f89e36cc968cb55328f249d902acdfa973f9f01179d9912463b5ee9d165c8c5e862fb7ff3f40ed531db9f2ee811432e6f77db8c42faa

data/README.md

@@ -0,0 +1,213 @@
+# 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.
+
+## Quick start
+
+```ruby
+require "dommy"
+
+win = Dommy.parse("<div id='root'><button class='primary'>Click me</button></div>")
+btn = win.document.query_selector(".primary")
+
+clicks = 0
+btn.on("click") { clicks += 1 }
+btn.click
+clicks   #=> 1
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "dommy"
+```
+
+## Highlights
+
+### DOM operations
+
+```ruby
+doc = win.document
+li = doc.create_element("li")
+li.text_content = "added"
+doc.body.append_child(li)
+doc.query_selector_all("li").length   #=> 1
+```
+
+### Custom Elements + lifecycle callbacks
+
+```ruby
+class MyButton < Dommy::HTMLElement
+  def self.observed_attributes = ["data-state"]
+  def connected_callback
+  end
+  def attribute_changed_callback(name, old, new)
+  end
+end
+
+win.custom_elements.define("my-button", MyButton)
+```
+
+### Shadow DOM
+
+```ruby
+host = win.document.create_element("my-card")
+sr   = host.attach_shadow(mode: "open")
+sr.inner_html = "<slot></slot>"
+
+# Outer queries can't reach inside the shadow tree
+win.document.query_selector("p")   # light DOM only
+```
+
+### Form validation
+
+```ruby
+input = win.document.create_element("input")
+input.type = "email"
+input.set_attribute("required", "")
+input.check_validity        #=> false
+input.validation_message    #=> "Please fill out this field."
+```
+
+### File API (Blob / File / FormData / DataTransfer)
+
+```ruby
+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])
+
+# FormData picks it up
+fd = Dommy::FormData.new(dom.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)
+
+# Blob URLs
+url = Dommy::URL.create_object_url(blob)   # "blob:dommy/..."
+```
+
+### Async / Promise#await
+
+Dommy's async surfaces (fetch, custom JS promises) return `PromiseValue`. Use `.await` from Ruby to unwrap synchronously:
+
+```ruby
+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.
+
+## Test helpers
+
+Dommy ships test-side modules you can `include` into RSpec / Minitest. Matchers accept a `Dommy::Document` / element or a raw HTML string (auto-parsed), matching Capybara's `expect(rendered).to ...` ergonomics.
+
+### Minitest
+
+```ruby
+require "dommy/minitest"
+
+class UserCardTest < Minitest::Test
+  include Dommy::TestHelpers
+  include Dommy::Minitest::Assertions
+
+  def test_renders
+    dom = parse_html(render(UserCardComponent.new(name: "Alice")))
+    assert_dom_contains(dom, "h2", text: "Alice")
+    assert_dom_contains(dom, "li", count: 3)
+  end
+end
+```
+
+Assertions: `assert_dom_contains`, `assert_dom_contains_text`, `assert_dom_has_attribute`, `assert_dom_has_class`, `assert_dom_html_equal` (each with a `refute_` counterpart).
+
+### RSpec — two matcher flavors
+
+`require "dommy/rspec"` to get both flavors:
+
+#### 1. `Dommy::RSpec::Matchers`
+
+`_dom_` infix names, coexist with Capybara and `rails-dom-testing`:
+
+```ruby
+expect(rendered).to contain_dom("h2", text: "Alice")
+expect(button).to have_dom_attribute("type", "submit")
+expect(button).to have_dom_class("primary")
+```
+
+#### 2. `Dommy::RSpec::CapyStyleMatchers`
+
+Capybara-compatible names for drop-in replacement in view / component / request specs:
+
+```ruby
+expect(rendered).to have_selector("h1", text: "Products")
+expect(rendered).to have_link("Sign up", href: "/signup")
+expect(rendered).to have_button("Submit")
+expect(rendered).to have_no_selector(".hidden")
+```
+
+Use a `type:` split to keep real-browser Capybara on feature specs while letting Dommy run the rest:
+
+```ruby
+RSpec.configure do |c|
+  c.include Capybara::DSL,                   type: :feature
+  c.include Capybara::RSpecMatchers,         type: :feature
+
+  %i[view component request controller helper].each do |t|
+    c.include Dommy::TestHelpers,             type: t
+    c.include Dommy::RSpec::CapyStyleMatchers, type: t
+  end
+end
+```
+
+Supported Capybara-style options: `text:` / `exact:` / `count:` (Integer or Range) / `visible:` / `href:` / `with:` / `type:`. `wait:` is accepted and ignored (Dommy is synchronous).
+
+> [!CAUTION]
+> `:visible` is HTML-level only. Dommy has no CSS engine, so `display: none` set via a CSS class is **not** detected. Detection covers the `hidden` attribute, `<input type=hidden>`, non-rendering ancestors (`head`/`script`/`style`/`template`), and inline `style="display: none"` / `visibility: hidden`. If you toggle visibility through a CSS class, assert on the class instead (`have_dom_class("hidden")`) or keep that spec on Capybara + a real browser.
+
+## What's in scope
+
+Implemented:
+
+- Core DOM (Document, Element, Text/Comment/Fragment, NodeList, Attr)
+- 26 specialized HTMLElement subclasses
+- events with composedPath / AbortSignal
+- MutationObserver (childList / attributes / characterData / subtree)
+- Custom Elements lifecycle
+- Shadow DOM (open/closed, slots, event composition)
+- form validation
+- Scheduler (timers + microtasks with `advance_time`)
+- Promise
+- Location / History / URL
+- Storage
+- fetch (stub)
+- Navigator / Clipboard
+- TreeWalker / NodeIterator / NodeFilter
+- File API (Blob / File / FileList / FormData / DataTransfer)
+
+> [!IMPORTANT]
+> Out of scope:
+>
+> - requires a layout / CSS engine or media subsystems: real `getBoundingClientRect` / scroll metrics
+> - CSS scoping (`:host`, `::slotted`, computed styles)
+> - JS evaluation
+> - Canvas / WebGL / media playback
+> - layout-dependent Range / Selection
+> - SVG specialized classes
+
+## Running the tests
+
+```sh
+$ bundle install
+$ bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/dommy/attr.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `Attr` — wraps an HTML attribute as a Node-like object. In real
+  # DOM each attribute on an element is an Attr; `el.getAttributeNode`
+  # returns the instance, `attr.value = "x"` mutates the element's
+  # attribute, `attr.ownerElement` points back to the element.
+  #
+  # We represent two states:
+  #   - "owned" — the Attr is attached to an Element. value reads/writes
+  #     go through the element's Nokogiri attribute slot.
+  #   - "detached" — created via `document.createAttribute(name)` but
+  #     not yet attached. Value is stored locally; `setAttributeNode`
+  #     transfers it to an element.
+  class Attr
+    attr_reader :name
+
+    def initialize(name, owner: nil, value: "")
+      @name = name.to_s.downcase
+      @owner = owner
+      @detached_value = value.to_s
+    end
+
+    # The Element this attr is on, or nil if detached.
+    def owner_element
+      @owner
+    end
+
+    def value
+      if @owner
+        @owner.__node__[@name].to_s
+      else
+        @detached_value
+      end
+    end
+
+    def value=(new_value)
+      if @owner
+        @owner.set_attribute(@name, new_value.to_s)
+      else
+        @detached_value = new_value.to_s
+      end
+    end
+
+    def __js_get__(key)
+      case key
+      when "name"
+        @name
+      when "value"
+        value
+      when "nodeName"
+        @name
+      when "nodeValue"
+        value
+      when "ownerElement"
+        @owner
+      when "localName"
+        @name
+      when "namespaceURI"
+        nil
+      when "nodeType"
+        2
+      end
+    end
+
+    def __js_set__(key, val)
+      case key
+      when "value", "nodeValue"
+        self.value = val
+      end
+
+      nil
+    end
+
+    def __js_call__(method, _args)
+      case method
+      when "cloneNode"
+        Attr.new(@name, owner: nil, value: value)
+      end
+    end
+
+    # Internal: called by Element when the attr is being transferred
+    # to (or detached from) an Element.
+    def __attach__(element)
+      @owner = element
+      @detached_value = ""
+      nil
+    end
+
+    def __detach__
+      cached = value
+      @owner = nil
+      @detached_value = cached
+      nil
+    end
+  end
+
+  # `Element.attributes` returns this. Iterable, `.length`, `.item(i)`,
+  # `.getNamedItem(name)`, `.removeNamedItem(name)`, `.setNamedItem(attr)`,
+  # plus property-style access (`attributes.id`, `attributes.class`).
+  #
+  # NamedNodeMap is *live* — it re-reads the element's Nokogiri
+  # attributes on every access so DOM mutations are reflected.
+  class NamedNodeMap
+    include Enumerable
+
+    def initialize(element)
+      @element = element
+    end
+
+    def length
+      @element.__node__.attribute_nodes.size
+    end
+
+    alias size length
+
+    def item(index)
+      name = @element.__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)
+
+      Attr.new(key, owner: @element)
+    end
+
+    def set_named_item(attr)
+      return nil unless attr.is_a?(Attr)
+
+      key = attr.name
+      val = attr.value
+      attr.__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)
+
+      attr = Attr.new(key, owner: nil, value: @element.__node__[key].to_s)
+      @element.remove_attribute(key)
+      attr
+    end
+
+    def each(&blk)
+      @element.__node__.attribute_nodes.each do |a|
+        yield Attr.new(a.name, owner: @element)
+      end
+    end
+
+    # Property-style access — `el.attributes.id`, `el.attributes["class"]`.
+    def [](key)
+      case key
+      when Integer
+        item(key)
+      else
+        get_named_item(key)
+      end
+    end
+
+    def __js_get__(key)
+      case key
+      when "length"
+        length
+      else
+        # Numeric key = item(i); string key = named item
+        if key.is_a?(Integer) || key.to_s.match?(/\A\d+\z/)
+          item(key.to_i)
+        else
+          get_named_item(key)
+        end
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "item"
+        item(args[0])
+      when "getNamedItem"
+        get_named_item(args[0])
+      when "setNamedItem"
+        set_named_item(args[0])
+      when "removeNamedItem"
+        remove_named_item(args[0])
+      end
+    end
+
+    def method_missing(name, *args)
+      attr = get_named_item(name)
+      attr || super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @element.__node__.key?(name.to_s.downcase) || super
+    end
+  end
+end

data/lib/dommy/blob.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Dommy
+  # `Blob` — opaque binary chunk with a MIME type, mirroring the
+  # File API's `Blob` interface. Used by File, FormData, and any
+  # code that needs to round-trip bytes through the DOM (e.g. a
+  # `<input type="file">` test scenario).
+  #
+  # Spec: https://w3c.github.io/FileAPI/#blob-section
+  class Blob
+    attr_reader :size, :type
+
+    # Construct a Blob from a list of parts. Each part can be:
+    #   - String (treated as binary bytes)
+    #   - Blob / File (their bytes are concatenated)
+    #   - Array<Integer> (byte values, like ArrayBuffer)
+    #   - anything else: coerced via to_s
+    #
+    # `options["type"]` sets the MIME type (lowercased per spec).
+    def initialize(parts = [], options = {})
+      parts = [parts] unless parts.is_a?(Array)
+      @data = collect_bytes(parts)
+      @size = @data.bytesize
+      raw_type = options["type"] || options[:type] || ""
+      @type = raw_type.to_s.downcase
+    end
+
+    # Return a new Blob over a byte range of this one.
+    # Negative indices are treated as offsets from the end (per spec).
+    def slice(start = 0, last = @size, content_type = "")
+      s = clamp_index(start.to_i, @size)
+      e = clamp_index(last.to_i, @size)
+      e = s if e < s
+      Blob.new([@data.byteslice(s, e - s) || ""], "type" => content_type.to_s)
+    end
+
+    # Read the bytes as UTF-8 text. The DOM spec returns a Promise,
+    # but Dommy is synchronous, so callers can use the result directly.
+    def text
+      @data.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # Read the bytes as an Array<Integer>. The DOM spec returns a
+    # Promise<ArrayBuffer>; Dommy is synchronous.
+    def array_buffer
+      @data.bytes
+    end
+
+    # Raw binary bytes (Ruby ASCII-8BIT string). Used by FormData /
+    # fetch when serializing multipart bodies.
+    def __bytes__
+      @data
+    end
+
+    def __js_get__(key)
+      case key
+      when "size"
+        @size
+      when "type"
+        @type
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "slice"
+        slice(args[0] || 0, args[1] || @size, args[2] || "")
+      when "text"
+        text
+      when "arrayBuffer"
+        array_buffer
+      end
+    end
+
+    private
+
+    def collect_bytes(parts)
+      buf = String.new(encoding: Encoding::ASCII_8BIT)
+      parts.each do |part|
+        case part
+        when Blob
+          buf << part.__bytes__
+        when String
+          buf << part.dup.force_encoding(Encoding::ASCII_8BIT)
+        when Array
+          buf << part.pack("C*")
+        else
+          buf << part.to_s.dup.force_encoding(Encoding::ASCII_8BIT)
+        end
+      end
+
+      buf
+    end
+
+    def clamp_index(idx, length)
+      idx = length + idx if idx.negative?
+      idx.clamp(0, length)
+    end
+  end
+
+  # `File` — Blob with a filename and an optional last-modified
+  # timestamp. Returned from `<input type="file">` / drag-and-drop,
+  # and accepted by FormData.
+  #
+  # Spec: https://w3c.github.io/FileAPI/#file-section
+  class File < Blob
+    attr_reader :name, :last_modified
+
+    def initialize(parts, name, options = {})
+      super(parts, options)
+      @name = name.to_s
+      raw_lm = options["lastModified"] || options[:lastModified]
+      @last_modified = (raw_lm || (Time.now.to_f * 1000)).to_i
+    end
+
+    def __js_get__(key)
+      case key
+      when "name"
+        @name
+      when "lastModified"
+        @last_modified
+      else
+        super
+      end
+    end
+  end
+
+  # `FileList` — immutable, ordered collection of File objects.
+  # Returned by `<input type="file">#files` and DataTransfer#files.
+  #
+  # Spec: https://w3c.github.io/FileAPI/#filelist-section
+  class FileList
+    include Enumerable
+
+    def initialize(files = [])
+      @files = files.to_a.freeze
+    end
+
+    def length
+      @files.length
+    end
+
+    alias size length
+
+    def item(index)
+      @files[index.to_i]
+    end
+
+    def [](index)
+      item(index)
+    end
+
+    def each(&block)
+      @files.each(&block)
+      self
+    end
+
+    def empty?
+      @files.empty?
+    end
+
+    def to_a
+      @files.dup
+    end
+
+    def __js_get__(key)
+      case key
+      when "length"
+        length
+      else
+        item(key.to_i) if key.is_a?(Integer) || key.to_s.match?(/\A-?\d+\z/)
+      end
+    end
+
+    def __js_call__(method, args)
+      case method
+      when "item"
+        item(args[0])
+      end
+    end
+  end
+end