dommy 0.8.0 → 0.9.0

data/lib/dommy/html_elements.rb

@@ -15,6 +15,19 @@ module Dommy
     def case_sensitive_attribute_names?
       false
     end
+
+    private
+
+    # HTML "rules for parsing integers": optional leading ASCII whitespace, an
+    # optional sign, then ASCII digits (trailing junk allowed). Returns the
+    # integer, or nil when the value is absent or doesn't begin with a valid
+    # integer — callers supply the reflected attribute's default.
+    def parse_html_integer(value)
+      return nil if value.nil?
+
+      match = value.to_s.sub(/\A[ \t\n\f\r]+/, "").match(/\A[-+]?\d+/)
+      match ? match[0].to_i : nil
+    end
   end
 
   # `<a>` — exposes URL-component getters/setters via the `href`
@@ -302,6 +315,105 @@ module Dommy
 
     def checked=(v)
       @__checked = !!v
+      # A radio becoming checked unchecks the rest of its radio button group.
+      uncheck_radio_group if @__checked && type == "radio"
+      # Checkedness is property state (no attribute mutation fires), yet it
+      # is selector-observable via :checked — invalidate computed styles.
+      @document&.__internal_bump_style_generation__
+    end
+
+    # `indeterminate` is pure property state (no content attribute), default
+    # false. Selector-observable via :indeterminate, so bump style generation.
+    def indeterminate
+      @__indeterminate || false
+    end
+
+    def indeterminate=(v)
+      @__indeterminate = !!v
+      @document&.__internal_bump_style_generation__
+    end
+
+    # --- Click activation behavior (checkbox / radio) -------------------
+
+    # HTML pre-click activation: a checkbox toggles; a radio becomes checked
+    # (which unchecks its group). Returns the state needed to undo this if the
+    # click is canceled, or nil for inputs with no activation behavior.
+    def pre_click_activation_state
+      # Only a mutable (enabled) checkbox/radio has activation behavior.
+      return nil if disabled
+
+      case type
+      when "checkbox"
+        old = checked
+        old_indeterminate = indeterminate
+        # Pre-click activation clears indeterminate, then toggles checkedness.
+        self.indeterminate = false
+        self.checked = !old
+        { kind: :checkbox, old_checked: old, old_indeterminate: old_indeterminate }
+      when "radio"
+        old_checked = checked
+        previously_checked = old_checked ? nil : currently_checked_in_radio_group
+        self.checked = true
+        { kind: :radio, old_checked: old_checked, previously_checked: previously_checked }
+      end
+    end
+
+    # Not canceled: fire `input` then `change` (HTML "input activation
+    # behavior"). Both are UA-generated, so trusted and non-cancelable.
+    def run_post_click_activation(_state)
+      dispatch_event(Event.new("input", "bubbles" => true).__internal_mark_trusted__)
+      dispatch_event(Event.new("change", "bubbles" => true).__internal_mark_trusted__)
+    end
+
+    # Canceled (default prevented): restore the pre-click checkedness. For a
+    # radio, also re-check whichever member was checked before.
+    def restore_pre_click_activation(state)
+      case state[:kind]
+      when :checkbox
+        self.checked = state[:old_checked]
+        self.indeterminate = state[:old_indeterminate]
+      when :radio
+        self.checked = state[:old_checked]
+        prev = state[:previously_checked]
+        prev.checked = true if prev && !prev.equal?(self)
+      end
+    end
+
+    # The currently-checked radio in this element's group (or nil).
+    def currently_checked_in_radio_group
+      radio_group_members.find { |radio| radio.checked && !radio.equal?(self) }
+    end
+
+    # Uncheck every other radio in this element's group.
+    def uncheck_radio_group
+      radio_group_members.each do |radio|
+        next if radio.equal?(self)
+
+        radio.__internal_set_checked_silently__(false)
+      end
+    end
+
+    # Set checkedness without re-running the group cascade (used while
+    # unchecking peers).
+    def __internal_set_checked_silently__(value)
+      @__checked = !!value
+      @document&.__internal_bump_style_generation__
+    end
+
+    # The radio button group: radios sharing this element's non-empty name and
+    # form owner (or, with no form, no form either). Orphan-tree grouping for
+    # detached radios is not modeled.
+    def radio_group_members
+      group_name = get_attribute("name").to_s
+      return [self] if group_name.empty?
+
+      owner_form = form
+      scope = owner_form || @document
+      return [self] unless scope.respond_to?(:query_selector_all)
+
+      scope.query_selector_all("input[type='radio']").to_a.select do |radio|
+        radio.get_attribute("name").to_s == group_name && radio.form.equal?(owner_form)
+      end
     end
 
     def labels
@@ -386,6 +498,8 @@ module Dommy
         value
       when "checked"
         checked
+      when "indeterminate"
+        indeterminate
       when "readonly", "readOnly"
         readonly
       when "labels"
@@ -413,6 +527,8 @@ module Dommy
         self.value = value
       when "checked"
         self.checked = value
+      when "indeterminate"
+        self.indeterminate = value
       when "readonly", "readOnly"
         self.readonly = value
       else
@@ -623,25 +739,111 @@ module Dommy
         super
       end
     end
+
+    # The classic-script source to execute now that this element is connected,
+    # or nil if it must not run: a `src` script (no network here), a non-classic
+    # type (module/JSON/etc.), an empty body, or one that already ran. The
+    # "already started" flag (set on first call) makes execution happen at most
+    # once, even if the node is re-inserted. The host eval is wired by the JS
+    # bridge via Document#script_runner.
+    # Module scripts are excluded — they need module scope / import resolution
+    # the classic eval path can't provide (left to a future module loader).
+    CLASSIC_SCRIPT_TYPES = ["", "text/javascript", "application/javascript",
+                            "application/ecmascript", "text/ecmascript"].freeze
+
+    # Set the HTML "already started" flag without running anything. The fragment
+    # parsing algorithm (innerHTML / insertAdjacentHTML / outerHTML / DOMParser)
+    # flags its scripts this way so they never execute on insertion.
+    def __internal_mark_script_already_started__
+      @__script_started = true
+      nil
+    end
+
+    def __internal_take_pending_script__
+      return nil if @__script_started
+      return nil unless src.to_s.empty?
+      return nil unless CLASSIC_SCRIPT_TYPES.include?(type.to_s.strip.downcase)
+
+      body = text_content.to_s
+      return nil if body.strip.empty?
+
+      @__script_started = true
+      body
+    end
+
+    # The classic-script `src` to fetch and execute now, or nil if it must not
+    # run: an inline script (no src), a non-classic type (module/JSON/etc.), or
+    # one that already ran. The external counterpart of
+    # #__internal_take_pending_script__ — it sets the same "already started"
+    # flag so the host fetches/executes the external body at most once, even if
+    # the node is re-inserted. The fetch itself is the host's job (Dommy has no
+    # network); this only decides eligibility and returns the URL.
+    def __internal_take_pending_src__
+      return nil if @__script_started
+
+      s = src.to_s
+      return nil if s.empty?
+      return nil unless CLASSIC_SCRIPT_TYPES.include?(type.to_s.strip.downcase)
+
+      @__script_started = true
+      s
+    end
+
+    # A `type="module"` script to evaluate now, or nil if it must not run (a
+    # non-module type, an empty inline body, or one that already ran). Returns
+    # `[:inline, body]` or `[:external, src]`; the host evaluates it as an ES
+    # module (resolving its imports). Sets the same "already started" flag so a
+    # module runs at most once.
+    def __internal_take_pending_module__
+      return nil if @__script_started
+      return nil unless type.to_s.strip.downcase == "module"
+
+      s = src.to_s
+      if s.empty?
+        body = text_content.to_s
+        return nil if body.strip.empty?
+
+        @__script_started = true
+        [:inline, body]
+      else
+        @__script_started = true
+        [:external, s]
+      end
+    end
   end
 
   # `<link>` — primarily for stylesheets, icons, preload, manifests.
   class HTMLLinkElement < HTMLElement
     reflect_string :href, :rel, :type, :media, :sizes, :hreflang, :integrity, as_attr: { attr: "as", js: "as" }, crossorigin: { js: "crossOrigin" }, referrer_policy: "referrerpolicy"
     # `link.sheet` — non-nil only when this link is a stylesheet
-    # (`rel` contains "stylesheet"). The sheet itself is a stub:
-    # Dommy doesn't fetch or parse CSS, but consumers can still
-    # `insertRule` / `deleteRule` against the in-memory sheet.
+    # (`rel` contains "stylesheet"). Dommy fetches nothing itself, so the
+    # sheet starts empty; a host environment supplies the CSS via
+    # `set_stylesheet_text`. Once filled it participates in the cascade and
+    # `insertRule` / `deleteRule` work against it like any CSSOM sheet.
     def sheet
-      return nil unless rel.split(/\s+/).any? { |t| t.casecmp("stylesheet").zero? }
+      return nil unless stylesheet_rel?
 
-      @__sheet ||= CSSStyleSheet.new(
-        owner_node: self,
-        href: href,
-        media: media,
-        title: @__node__["title"].to_s,
-        type: (type.empty? ? "text/css" : type)
-      )
+      @__sheet ||= build_link_sheet
+    end
+
+    # Host hook (e.g. dommy-rack resolving `<link href>` from a response):
+    # supply the CSS this link points at. Re-seeds the sheet — splitting the
+    # text into CSSRules — and invalidates the document's computed styles so
+    # the next getComputedStyle / visible? sees the new rules.
+    def set_stylesheet_text(css)
+      return nil unless stylesheet_rel?
+
+      @__sheet = build_link_sheet(css.to_s)
+      doc = owner_document
+      doc.__internal_bump_style_generation__ if doc.respond_to?(:__internal_bump_style_generation__)
+      @__sheet
+    end
+
+    # The sheet the cascade should read, or nil when this link isn't a
+    # stylesheet or no one instantiated/filled its sheet yet. (Unlike
+    # `sheet`, this never instantiates — an untouched link costs nothing.)
+    def __internal_stylesheet_for_cascade__
+      @__sheet if @__sheet && stylesheet_rel?
     end
 
     def __js_get__(key)
@@ -655,6 +857,23 @@ module Dommy
         super
       end
     end
+
+    private
+
+    def stylesheet_rel?
+      rel.split(/\s+/).any? { |token| token.casecmp("stylesheet").zero? }
+    end
+
+    def build_link_sheet(source_text = nil)
+      CSSStyleSheet.new(
+        owner_node: self,
+        href: href,
+        media: media,
+        title: @__node__["title"].to_s,
+        type: (type.empty? ? "text/css" : type),
+        source_text: source_text
+      )
+    end
   end
 
   # `ValidityState` — computes constraint-validation flags from the
@@ -862,6 +1081,8 @@ module Dommy
         custom_error
       when "valid"
         valid
+      else
+        Bridge::ABSENT
       end
     end
 
@@ -1743,20 +1964,27 @@ module Dommy
     end
   end
 
-  # `<details>` — `open` reflected boolean. Toggling it fires a
-  # `toggle` event (non-bubbling per spec).
+  # `<details>` — `open` reflected boolean. Whenever the open state changes —
+  # via the `open` property, setAttribute/removeAttribute, or toggleAttribute —
+  # a non-bubbling `toggle` event fires (per spec). Routing the dispatch through
+  # the attribute mutators (not just the property setter) is what makes
+  # `details.toggleAttribute("open")` fire toggle, which Stimulus's `:open`
+  # action option relies on.
   class HTMLDetailsElement < HTMLElement
     def open
       reflected_boolean("open")
     end
 
     def open=(v)
-      was = open
       set_reflected_boolean("open", v)
-      now = open
-      return if was == now
+    end
+
+    def set_attribute(name, value)
+      with_toggle_on_open_change { super }
+    end
 
-      dispatch_event(Event.new("toggle", "bubbles" => false, "cancelable" => false))
+    def remove_attribute(name)
+      with_toggle_on_open_change { super }
     end
 
     def __js_get__(key)
@@ -1770,6 +1998,15 @@ module Dommy
         super
       end
     end
+
+    private
+
+    def with_toggle_on_open_change
+      was = open
+      result = yield
+      dispatch_event(Event.new("toggle", "bubbles" => false, "cancelable" => false)) if open != was
+      result
+    end
   end
 
   # `<meter>` — gauge with `value` / `min` / `max` (default 0/0/1)
@@ -2726,8 +2963,9 @@ module Dommy
   class HTMLOListElement < HTMLElement
     reflect_string :type
     reflect_boolean :reversed
+    # `start` reflects the content attribute as a long with default 1.
     def start
-      (@__node__["start"] || "1").to_i
+      parse_html_integer(@__node__["start"]) || 1
     end
 
     def start=(v)
@@ -2757,8 +2995,9 @@ module Dommy
   end
 
   class HTMLLIElement < HTMLElement
+    # `value` reflects the content attribute as a long with default 0.
     def value
-      @__node__["value"]&.to_i
+      parse_html_integer(@__node__["value"]) || 0
     end
 
     def value=(v)
@@ -2925,18 +3164,33 @@ module Dommy
       @__disabled = !!v
     end
 
-    # `style.sheet` — always non-nil for `<style>` (in browsers the
-    # text content is parsed; we hand back an empty sheet stub that
-    # consumers can manipulate via insertRule/deleteRule).
+    # `style.sheet` — always non-nil for `<style>`. Memoized per text
+    # content (CSSOM: repeated reads return the same object), seeded
+    # with the element's CSS text so insertRule/deleteRule order against
+    # it. Rewriting the element's text discards the sheet and any rules
+    # inserted via CSSOM — browsers re-parse into a fresh sheet too.
     def sheet
-      @__sheet ||= CSSStyleSheet.new(
+      text = text_content.to_s
+      return @__sheet if @__sheet && @__sheet_text == text
+
+      @__sheet_text = text
+      @__sheet = CSSStyleSheet.new(
         owner_node: self,
         media: media,
         title: @__node__["title"].to_s,
-        type: (type.empty? ? "text/css" : type)
+        type: (type.empty? ? "text/css" : type),
+        source_text: text
       )
     end
 
+    # The memoized sheet, or nil when none was created yet or the
+    # element's text changed since (stale sheet). Lets the cascade read
+    # CSSOM state only for sheets someone actually touched, without
+    # instantiating sheet objects for every `<style>` in the document.
+    def __internal_instantiated_sheet__
+      @__sheet if @__sheet && @__sheet_text == text_content.to_s
+    end
+
     def __js_get__(key)
       case key
       when "disabled"
@@ -3016,7 +3270,14 @@ module Dommy
 
   class HTMLHtmlElement < HTMLElement
   end
+end
+
+# HTMLCanvasElement is a HTMLElement subclass kept in its own file (the canvas
+# 2D-context stub is sizeable); required here so the element map below resolves
+# the constant. Its runtime-only references (Blob, …) load with the rest.
+require_relative "html_canvas_element"
 
+module Dommy
   # Look up the subclass for a given HTML tag. Document#wrap_node
   # consults this map; defaults to plain Element.
   HTML_ELEMENT_CLASSES = {
@@ -3025,6 +3286,7 @@ module Dommy
     "input" => HTMLInputElement,
     "button" => HTMLButtonElement,
     "img" => HTMLImageElement,
+    "canvas" => HTMLCanvasElement,
     "script" => HTMLScriptElement,
     "link" => HTMLLinkElement,
     "select" => HTMLSelectElement,
@@ -3090,12 +3352,27 @@ module Dommy
   }.freeze
 
   SVG_NAMESPACE_URI = "http://www.w3.org/2000/svg"
+  HTML_NAMESPACE_URI = "http://www.w3.org/1999/xhtml"
+
+  # The interface for an HTML-namespace element whose local name maps to no
+  # specialized interface (e.g. createElementNS with an upper-case or otherwise
+  # unrecognized name). Still an HTMLElement, so `instanceof HTMLElement` holds.
+  class HTMLUnknownElement < HTMLElement
+  end
 
+  # Map a (local name, namespace) pair to its DOM interface class. HTML-namespace
+  # names match case-SENSITIVELY (createElement lower-cases first, but
+  # createElementNS preserves case, so "SPAN" is unknown); any namespace other
+  # than HTML/SVG — including the null namespace — gets the generic Element.
   def self.element_class_for(tag_name, namespace_uri = nil)
-    if namespace_uri == SVG_NAMESPACE_URI
-      SVG_ELEMENT_CLASSES[tag_name.to_s.downcase] || SVGElement
+    name = tag_name.to_s
+    case namespace_uri
+    when SVG_NAMESPACE_URI
+      SVG_ELEMENT_CLASSES[name.downcase] || SVGElement
+    when HTML_NAMESPACE_URI
+      HTML_ELEMENT_CLASSES[name] || HTMLUnknownElement
     else
-      HTML_ELEMENT_CLASSES[tag_name.to_s.downcase] || Element
+      Element
     end
   end
 end

data/lib/dommy/interaction/debug.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Interaction
+    # A read-only debugging view over a DOM scope (a document or any element),
+    # built on DomSummary. `Dommy::Rack::Session` and `Dommy::Browser` expose it
+    # as `#debug` (scoped to the current `within`), but it wraps a plain node so
+    # it works on any document too — e.g. `Dommy::Interaction::Debug.new(dom)`
+    # in a request/view spec.
+    #
+    #   browser.debug.dom_summary   # readable forms/links/buttons/fields
+    #   browser.debug.buttons       # structured [{label:, type:, selector:}]
+    class Debug
+      def initialize(scope)
+        @scope = scope
+      end
+
+      # A readable, sectioned summary of the visible controls.
+      def dom_summary = DomSummary.to_text(@scope)
+
+      def forms = DomSummary.forms(@scope)
+      def links = DomSummary.links(@scope)
+      def buttons = DomSummary.buttons(@scope)
+      def fields = DomSummary.fields(@scope)
+
+      # The scope's collapsed visible text content.
+      def visible_text = DomSummary.text(@scope)
+
+      # The accessibility tree / Playwright-compatible ARIA snapshot of the
+      # current scope.
+      def aria_tree = Internal::AccessibilityTree.build(@scope)
+      def aria_snapshot = Internal::AriaSnapshot.serialize(aria_tree)
+    end
+  end
+end

data/lib/dommy/interaction/dom_summary.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Interaction
+    # Summarizes the user-facing controls of a DOM scope (a document or any
+    # element with `query_selector_all`): the buttons, fields, links, and forms
+    # a person would see. Engine-independent and scope-general — it backs the
+    # finder's "available …" failure messages, the `Debug` facade, and failure
+    # artifacts, and can be called directly on any document (e.g. a request
+    # spec's `dom`).
+    #
+    #   Dommy::Interaction::DomSummary.buttons(document)
+    #   #=> [{label: "Save", type: "submit", selector: "button[type=submit]"}]
+    #   puts Dommy::Interaction::DomSummary.to_text(document)
+    module DomSummary
+      module_function
+
+      # Submit-capable and plain buttons, as {label:, type:, selector:}.
+      def buttons(scope)
+        return [] unless scope
+
+        scope.query_selector_all("button, input[type='submit'], input[type='image'], input[type='button'], input[type='reset']").map do |el|
+          {label: button_label(el), type: presence(el.get_attribute("type")), selector: selector_for(el)}
+        end
+      end
+
+      # Form fields, as {label:, name:, id:, type:, selector:}.
+      def fields(scope)
+        return [] unless scope
+
+        scope.query_selector_all("input, textarea, select").reject { |el| hidden_input?(el) }.map do |el|
+          {label: field_label(el, scope), name: presence(el.get_attribute("name")),
+           id: presence(el.get_attribute("id")), type: field_type(el), selector: selector_for(el)}
+        end
+      end
+
+      # Links with an href, as {text:, href:}.
+      def links(scope)
+        return [] unless scope
+
+        scope.query_selector_all("a[href]").map do |el|
+          {text: squish(el.text_content), href: el.get_attribute("href").to_s}
+        end
+      end
+
+      # Forms, as {action:, method:, fields: [names]}.
+      def forms(scope)
+        return [] unless scope
+
+        scope.query_selector_all("form").map do |form|
+          {action: presence(form.get_attribute("action")), method: form_method(form),
+           fields: fields(form).map { |f| f[:name] }.compact}
+        end
+      end
+
+      # One-line descriptors for failure messages: `"Save" button[type=submit]`.
+      def button_labels(scope) = buttons(scope).map { |b| "#{quote(b[:label])} #{b[:selector]}".strip }
+      def field_labels(scope) = fields(scope).map { |f| "#{quote(f[:label] || f[:name])} #{f[:selector]}".strip }
+      def link_labels(scope) = links(scope).map { |l| "#{quote(l[:text])} -> #{l[:href]}" }
+
+      # A readable, sectioned summary of the scope's controls (used by the
+      # `Debug` facade and failure artifacts).
+      def to_text(scope)
+        sections = {
+          "Forms" => forms(scope).map { |f| "#{(f[:method] || "get").upcase} #{f[:action] || "(self)"} [#{f[:fields].join(", ")}]" },
+          "Links" => link_labels(scope),
+          "Buttons" => button_labels(scope),
+          "Fields" => field_labels(scope)
+        }
+        sections.reject { |_, rows| rows.empty? }
+          .map { |name, rows| "#{name}:\n#{rows.map { |r| "  #{r}" }.join("\n")}" }
+          .join("\n")
+      end
+
+      # --- label / descriptor helpers ---
+
+      def button_label(el)
+        if el.tag_name == "INPUT"
+          presence(el.get_attribute("value")) || presence(el.get_attribute("alt")) || ""
+        else
+          squish(el.text_content)
+        end
+      end
+
+      # Prefer an associated <label>, then aria-label, placeholder, name, id.
+      def field_label(el, scope)
+        label_caption(el, scope) || presence(el.get_attribute("aria-label")) ||
+          presence(el.get_attribute("placeholder")) || presence(el.get_attribute("name")) ||
+          presence(el.get_attribute("id"))
+      end
+
+      def label_caption(el, scope)
+        id = presence(el.get_attribute("id"))
+        wrapping = el.respond_to?(:closest) ? el.closest("label") : nil
+        label = (id && scope.query_selector_all("label").find { |l| l.get_attribute("for") == id }) || wrapping
+        label ? presence(squish(label.text_content)) : nil
+      end
+
+      def field_type(el)
+        return el.tag_name.downcase unless el.tag_name == "INPUT"
+
+        presence(el.get_attribute("type")) || "text"
+      end
+
+      def selector_for(el)
+        tag = el.tag_name.downcase
+        type = presence(el.get_attribute("type"))
+        name = presence(el.get_attribute("name"))
+        descriptor = tag
+        descriptor += "[type=#{type}]" if type
+        descriptor += "[name=#{name}]" if name
+        descriptor
+      end
+
+      # Collapsed visible text of a scope. A Document has no text_content of its
+      # own, so read its <body>.
+      def text(scope)
+        return "" unless scope
+
+        node = scope.respond_to?(:body) ? scope.body : scope
+        squish(node&.text_content)
+      end
+
+      def hidden_input?(el) = el.tag_name == "INPUT" && el.get_attribute("type") == "hidden"
+      def form_method(form) = presence(form.get_attribute("method"))&.downcase
+      def squish(text) = text.to_s.gsub(/\s+/, " ").strip
+      def presence(value) = (value.nil? || value.to_s.empty?) ? nil : value
+      def quote(value) = value.to_s.inspect
+    end
+  end
+end