dommy 0.8.0 → 0.9.0

data/lib/dommy/js/custom_element_bridge.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Bridges JS-defined custom elements to Dommy's custom element pipeline.
+    # `customElements.define(name, JSClass)` on the JS side calls in here, which
+    # registers a Dommy::HTMLElement subclass for `name` whose lifecycle
+    # reactions (connected/disconnected/adopted/attributeChanged) route back to
+    # the JS instance through the bridge. The JS class's constructor itself runs
+    # on the JS side via the construction-stack upgrade in host_runtime.js.
+    #
+    # Named distinctly from Dommy::CustomElementRegistry (the DOM
+    # window.customElements registry); this is the JS<->Dommy wiring, not the
+    # registry itself.
+    class CustomElementBridge
+      attr_writer :window
+
+      def initialize(bridge)
+        @bridge = bridge
+        @window = nil
+      end
+
+      def define(name, observed)
+        return unless @window.respond_to?(:custom_elements)
+
+        @window.custom_elements.define(name, build_class(name, observed))
+        nil
+      end
+
+      # customElements.upgrade(root): delegate to Dommy's registry so a subtree
+      # attached without firing reactions gets its registered elements upgraded.
+      def upgrade(root)
+        return unless @window.respond_to?(:custom_elements)
+
+        @window.custom_elements.upgrade(root)
+        nil
+      end
+
+      private
+
+      # A Dommy custom element class for `name` whose reactions forward to the JS
+      # instance. A fresh subclass per tag carries the bridge / name / observed
+      # set as class-level attributes; the reaction methods are defined once on
+      # the base (BridgedCustomElement), reading them via `self.class` — so no
+      # per-registration method definition is needed.
+      def build_class(name, observed)
+        klass = Class.new(BridgedCustomElement)
+        klass.js_bridge = @bridge
+        klass.js_name = name
+        klass.js_observed = observed
+        klass
+      end
+    end
+
+    # Base for a JS-defined custom element. Each registered tag is a subclass
+    # carrying its bridge / tag name / observed attributes; the lifecycle
+    # reactions (defined once here) forward to the JS instance through the
+    # bridge. `__js_custom_element_name__` marks the node so the bridge upgrades
+    # it on first crossing (see HostBridge interface info).
+    class BridgedCustomElement < Dommy::HTMLElement
+      class << self
+        attr_accessor :js_bridge, :js_name, :js_observed
+
+        def observed_attributes
+          js_observed
+        end
+      end
+
+      def __js_custom_element_name__
+        self.class.js_name
+      end
+
+      def connected_callback
+        self.class.js_bridge.invoke_lifecycle(self, "connectedCallback", [])
+      end
+
+      def disconnected_callback
+        self.class.js_bridge.invoke_lifecycle(self, "disconnectedCallback", [])
+      end
+
+      def adopted_callback
+        self.class.js_bridge.invoke_lifecycle(self, "adoptedCallback", [])
+      end
+
+      def attribute_changed_callback(attr, old_value, new_value)
+        self.class.js_bridge.invoke_lifecycle(self, "attributeChangedCallback", [attr, old_value, new_value])
+      end
+    end
+  end
+end

data/lib/dommy/js/dom_interfaces.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Derives WebIDL interface metadata for a Dommy DOM object: the most-derived
+    # interface name and the single-inheritance chain up to the root
+    # (EventTarget for nodes). This mirrors the JS prototype chain the bridge
+    # builds so `instanceof` / Object.prototype.toString resolve correctly.
+    #
+    # Engine-agnostic, and the single home for DOM interface hierarchy knowledge:
+    # BASE_CHAINS (seeded eagerly on the JS side) must stay consistent with what
+    # #chain_for derives from real objects.
+    module DomInterfaces
+      # Dommy class basename -> WebIDL interface name, where they diverge.
+      # Anything not listed uses the class basename verbatim (HTMLDivElement, …).
+      NAME_OVERRIDES = {
+        "TextNode" => "Text",
+        "CommentNode" => "Comment",
+        "CharacterDataNode" => "CharacterData",
+        "Fragment" => "DocumentFragment",
+        "ClassList" => "DOMTokenList",
+        "DatasetMap" => "DOMStringMap",
+        "StyleDeclaration" => "CSSStyleDeclaration",
+        "LiveNodeList" => "NodeList",
+        "StandaloneEventTarget" => "EventTarget"
+      }.freeze
+
+      # Concrete HTML element interfaces. A browser exposes every one of these as
+      # a global constructor whether or not an instance exists, so a framework's
+      # bare `instanceof HTMLInputElement` feature check resolves regardless of
+      # page content (idiomorph, Turbo's morph engine, probes `instanceof
+      # HTMLInputElement`/`HTMLTextAreaElement` during focus restoration even when
+      # the page has no such element). Each is a direct HTMLElement subclass
+      # except the two media leaves, appended with their chains below. Mirrors the
+      # `class HTMLxxxElement < HTMLElement` set in the dommy gem's html_elements.
+      HTML_LEAF_INTERFACES = %w[
+        HTMLAnchorElement HTMLAreaElement HTMLBaseElement HTMLBodyElement
+        HTMLBRElement HTMLButtonElement HTMLCanvasElement HTMLDataElement HTMLDetailsElement
+        HTMLDialogElement HTMLDivElement HTMLEmbedElement HTMLFieldsetElement
+        HTMLFormElement HTMLHeadElement HTMLHeadingElement HTMLHRElement
+        HTMLHtmlElement HTMLIFrameElement HTMLImageElement HTMLInputElement
+        HTMLLabelElement HTMLLegendElement HTMLLIElement HTMLLinkElement
+        HTMLMapElement HTMLMetaElement HTMLMeterElement HTMLModElement
+        HTMLObjectElement HTMLOListElement HTMLOptGroupElement HTMLOptionElement
+        HTMLOutputElement HTMLParagraphElement HTMLPictureElement HTMLPreElement
+        HTMLProgressElement HTMLQuoteElement HTMLScriptElement HTMLSelectElement
+        HTMLSlotElement HTMLSourceElement HTMLSpanElement HTMLStyleElement
+        HTMLTableCaptionElement HTMLTableCellElement HTMLTableElement
+        HTMLTableRowElement HTMLTableSectionElement HTMLTemplateElement
+        HTMLTextAreaElement HTMLTimeElement HTMLTitleElement HTMLTrackElement
+        HTMLUListElement
+      ].freeze
+
+      # Base interface chains seeded eagerly on the JS side so `instanceof Node`
+      # / `typeof HTMLElement` resolve before an instance of that exact type has
+      # crossed. Concrete leaves (HTMLButtonElement, …) are built lazily from
+      # #chain_for when an instance crosses. Keep consistent with #chain_for.
+      BASE_CHAINS = [
+        %w[Node EventTarget],
+        %w[Element Node EventTarget],
+        %w[HTMLElement Element Node EventTarget],
+        %w[SVGElement Element Node EventTarget],
+        %w[CharacterData Node EventTarget],
+        %w[Text CharacterData Node EventTarget],
+        %w[Comment CharacterData Node EventTarget],
+        %w[Document Node EventTarget],
+        %w[DocumentFragment Node EventTarget],
+        # ShadowRoot is a DocumentFragment subclass; seeded so bare `node
+        # instanceof ShadowRoot` (Alpine.js walks the tree with this) resolves.
+        %w[ShadowRoot DocumentFragment Node EventTarget],
+        %w[DocumentType Node EventTarget],
+        %w[Attr Node EventTarget],
+        %w[Event],
+        %w[CustomEvent Event],
+        %w[MessageEvent Event],
+        %w[PopStateEvent Event],
+        %w[HashChangeEvent Event],
+        %w[CloseEvent Event],
+        %w[MouseEvent Event],
+        %w[KeyboardEvent Event],
+        %w[PromiseRejectionEvent Event],
+        %w[ErrorEvent Event],
+        %w[DOMException],
+        # Window-exposed constructors that frameworks call bare (new X(...)).
+        # Seeding them creates the global; construction routes to the window.
+        %w[MutationObserver], %w[IntersectionObserver], %w[ResizeObserver],
+        %w[PerformanceObserver], %w[AbortController], %w[AbortSignal EventTarget],
+        %w[FormData], %w[URL], %w[URLSearchParams], %w[Headers], %w[Request], %w[Response],
+        %w[Blob], %w[File], %w[FileList], %w[FileReader], %w[XMLHttpRequest],
+        %w[TextEncoder], %w[TextDecoder], %w[DOMParser], %w[XMLSerializer],
+        %w[MessageChannel], %w[BroadcastChannel], %w[WebSocket], %w[EventSource],
+        %w[Notification], %w[Worker], %w[DataTransfer],
+        %w[ReadableStream], %w[WritableStream], %w[TransformStream],
+        %w[Range],
+        # CSSOM stylesheet interfaces. Seeded so `style instanceof CSSStyleSheet`
+        # resolves: Lit's css-tag runs that check while deciding whether to use
+        # constructable stylesheets; with the interface present but
+        # `adoptedStyleSheets` unsupported it falls back to injecting a <style>
+        # element, which Dommy handles.
+        %w[CSSStyleSheet StyleSheet], %w[StyleSheet],
+        # Collection interfaces, seeded so `result instanceof NodeList` /
+        # `instanceof HTMLCollection` resolve (querySelectorAll, children, …).
+        %w[NodeList], %w[HTMLCollection],
+        # Traversal: NodeFilter exposes only [Constant]s (NodeFilter.SHOW_ELEMENT,
+        # .FILTER_ACCEPT, …); TreeWalker/NodeIterator are instances.
+        %w[NodeFilter], %w[TreeWalker], %w[NodeIterator],
+        # Concrete HTML element interfaces (see HTML_LEAF_INTERFACES) + the media
+        # subtree, so bare `instanceof HTMLInputElement` always resolves.
+        *HTML_LEAF_INTERFACES.map { |n| [n, "HTMLElement", "Element", "Node", "EventTarget"] },
+        # createElementNS with an unrecognized HTML-namespace local name yields an
+        # HTMLUnknownElement; seed it so a bare `instanceof HTMLUnknownElement`
+        # resolves even before such an element crosses.
+        %w[HTMLUnknownElement HTMLElement Element Node EventTarget],
+        %w[HTMLMediaElement HTMLElement Element Node EventTarget],
+        %w[HTMLAudioElement HTMLMediaElement HTMLElement Element Node EventTarget],
+        %w[HTMLVideoElement HTMLMediaElement HTMLElement Element Node EventTarget]
+      ].freeze
+
+      module_function
+
+      # { "name" => most-derived interface, "chain" => [...] } for a host object.
+      def info(obj)
+        chain = chain_for(obj)
+        {"name" => chain.first, "chain" => chain}
+      end
+
+      # Walk the Dommy class superclass chain (HTMLDivElement < HTMLElement <
+      # Element), then append the module-provided base interfaces (Node ->
+      # EventTarget) for nodes, since Dommy models Node as a mixin rather than a
+      # superclass. Stops at the first foreign superclass (Object, or
+      # StandardError for DOMException) so non-DOM ancestors stay out.
+      def chain_for(obj)
+        # WHATWG models DOMException as a single interface distinguished by its
+        # `name` property — there are no per-name subclasses. Collapse Dommy's
+        # convenience subclasses (AbortError < DOMException) to the one interface
+        # so a DOMException crossing as a value (e.g. `signal.reason`) reports
+        # `constructor === DOMException`, which assert_throws_dom checks.
+        return ["DOMException"] if defined?(Dommy::DOMException) && obj.is_a?(Dommy::DOMException)
+
+        names = []
+        klass = obj.class
+        while klass && klass.name&.start_with?("Dommy::")
+          name = name_for(klass)
+          names << name if name && !names.include?(name)
+          klass = klass.superclass
+        end
+        if defined?(Dommy::Node) && obj.is_a?(Dommy::Node)
+          names << "Node" unless names.include?("Node")
+          names << "EventTarget" unless names.include?("EventTarget")
+        end
+        names
+      end
+
+      def name_for(klass)
+        base = klass.name&.split("::")&.last
+        return nil unless base
+
+        NAME_OVERRIDES.fetch(base, base)
+      end
+    end
+  end
+end

data/lib/dommy/js/handle_table.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    # Maps JS-facing integer handles to live Ruby objects. Engine-agnostic.
+    #
+    # Handles are monotonic — never reused — so a handle can never refer to two
+    # different objects over the table's lifetime. That invariant is what makes
+    # GC-driven #release race-free: a finalizer releasing handle N can't clobber
+    # a different object that happened to get the same id.
+    #
+    # The same Ruby object reuses its handle while still registered (keyed by
+    # object_id), so it maps to a single JS proxy (stable identity). A registry
+    # entry also keeps the object reachable while JS holds a proxy for it.
+    class HandleTable
+      def initialize
+        @by_handle = {}      # handle (Integer) -> object
+        @handle_by_oid = {}  # object_id -> handle (for identity reuse)
+        @next_handle = 0
+      end
+
+      def register(obj)
+        oid = obj.object_id
+        existing = @handle_by_oid[oid]
+        return existing if existing && @by_handle[existing].equal?(obj)
+
+        handle = (@next_handle += 1)
+        @by_handle[handle] = obj
+        @handle_by_oid[oid] = handle
+        handle
+      end
+
+      def fetch(handle)
+        @by_handle.fetch(handle.to_i)
+      end
+
+      # Tolerant lookup: nil when the handle is unknown (its object was released
+      # by GC, or a framework passed an invalid/never-allocated handle). Used for
+      # call ARGUMENTS, where a reference to a vanished object is simply absent —
+      # unlike a receiver handle, where a miss is a real error (#fetch).
+      def lookup(handle)
+        @by_handle[handle.to_i]
+      end
+
+      # Forget a handle (called when its JS proxy is garbage-collected). Only
+      # trims the mapping; the object itself lives on via its other references.
+      def release(handle)
+        obj = @by_handle.delete(handle.to_i)
+        return unless obj
+
+        oid = obj.object_id
+        @handle_by_oid.delete(oid) if @handle_by_oid[oid] == handle.to_i
+      end
+
+      def size
+        @by_handle.size
+      end
+    end
+  end
+end