dommy 0.7.0 → 0.8.0

data/lib/dommy/internal/parent_node.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    # Shared ParentNode tree-mutation surface for Element, Fragment, and
+    # ShadowRoot. Includers must expose `@__node__` (the backing Nokogiri
+    # node) and `@document` (the owning Dommy::Document).
+    #
+    # All child-list mutations funnel through `notify_child_list`, which
+    # forwards to MutationCoordinator#notify_child_list_mutation. That
+    # coordinator already no-ops on empty added/removed sets and on an
+    # unwrappable target, so callers may invoke it unconditionally.
+    module ParentNode
+      # `appendChild(child)` — detach the node(s) from any current parent
+      # and append to the end of this node's child list.
+      def append_child(child)
+        check_insertion!(child)
+        nodes = detach_dom_nodes(child)
+        nodes.each { |n| @__node__.add_child(n) }
+        notify_child_list(added: nodes)
+        child
+      end
+
+      # ParentNode#append — mixed Node/String args appended in order.
+      def append(*args)
+        nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
+        nodes.each { |n| @__node__.add_child(n) }
+        notify_child_list(added: nodes)
+        nil
+      end
+
+      # ParentNode#prepend — insert before the current first child.
+      def prepend(*args)
+        nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
+        anchor = @__node__.children.first
+        if anchor
+          nodes.reverse_each { |n| anchor.add_previous_sibling(n) }
+        else
+          nodes.each { |n| @__node__.add_child(n) }
+        end
+        notify_child_list(added: nodes)
+        nil
+      end
+
+      # ParentNode#replaceChildren — remove all existing children, then
+      # append the new set. One mutation record carries both sides.
+      def replace_children(*args)
+        removed = @__node__.children.to_a
+        removed.each(&:unlink)
+        nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
+        nodes.each { |n| @__node__.add_child(n) }
+        notify_child_list(added: nodes, removed: removed)
+        nil
+      end
+
+      private
+
+      # Centralized MutationObserver childList notification. Defaults the
+      # target to this node; beforebegin/afterend/replaceWith/outerHTML
+      # callers pass the parent explicitly. The coordinator filters out
+      # empty added/removed sets, so this is always safe to call.
+      def notify_child_list(added: [], removed: [], target: @__node__)
+        @document.notify_child_list_mutation(
+          target_node: target,
+          added_nodes: added,
+          removed_nodes: removed
+        )
+      end
+
+      # Coerce an append/prepend/replaceChildren argument into raw Nokogiri
+      # node(s), detached from any current parent:
+      #   - Element / TextNode / CommentNode → its backing node (unlinked)
+      #   - Fragment                          → its extracted children
+      #   - String                            → a fresh text node
+      #   - anything else with a backing node → that node (unlinked)
+      #
+      # The class constants resolve at call time, so the mixin only needs to
+      # be defined before the including class bodies run.
+      def detach_dom_nodes(value)
+        case value
+        when Element, TextNode, CommentNode
+          [detach_with_notify(value.__dommy_backend_node__)]
+        when Fragment
+          value.extract_children
+        when String
+          [@document.create_text_node(value).__dommy_backend_node__]
+        else
+          node = value.respond_to?(:__dommy_backend_node__) ? value.__dommy_backend_node__ : nil
+          return [] unless node
+
+          [detach_with_notify(node)]
+        end
+      end
+
+      # Detach a node from its current parent, queuing a childList removal
+      # record on that old parent first (WHATWG "remove" runs before the
+      # subsequent insert, so moving a node yields a removal record + an addition
+      # record). Returns the raw node, ready to be re-linked.
+      def detach_with_notify(node)
+        old_parent = node.parent
+        return node unless old_parent
+
+        # Capture the position (as wrapped nodes — the coordinator records
+        # explicit siblings verbatim) before unlinking.
+        prev_sib = node.previous_sibling && @document.wrap_node(node.previous_sibling)
+        next_sib = node.next_sibling && @document.wrap_node(node.next_sibling)
+        node.unlink
+        @document.notify_child_list_mutation(
+          target_node: old_parent,
+          added_nodes: [],
+          removed_nodes: [node],
+          previous_sibling: prev_sib,
+          next_sibling: next_sib
+        )
+        node
+      end
+
+      # Hierarchy guard hook. Default no-op (Fragment / ShadowRoot stay
+      # permissive, matching current behavior). Element overrides this to
+      # call its `check_hierarchy!`.
+      def check_insertion!(_child)
+        nil
+      end
+    end
+  end
+end

data/lib/dommy/internal/reflected_attributes.rb

@@ -2,23 +2,113 @@
 
 module Dommy
   module Internal
-    # IDL-attribute reflection helpers for `HTMLElement` and `SVGElement`
-    # subclasses. Each helper delegates to the host element's standard
-    # attribute API (`get_attribute` / `set_attribute` / `has_attribute?`
-    # / `remove_attribute`), so case-sensitivity is naturally inherited
-    # from the host element's namespace — HTML lowercases, SVG keeps
-    # the spec name (`viewBox`).
+    # IDL-attribute reflection for `HTMLElement` and `SVGElement` subclasses.
     #
-    # Two reflection styles:
+    # Two layers:
     #
-    # - **String**: the property mirrors the attribute value verbatim.
-    #   Missing → `""` (not nil), so subclasses don't need defensive
-    #   `.to_s`.
+    # 1. **Instance helpers** (`reflected_string` / `set_reflected_string` /
+    #    `reflected_boolean` / `set_reflected_boolean`) delegate to the host
+    #    element's standard attribute API (`get_attribute` / `set_attribute` /
+    #    `has_attribute?` / `remove_attribute`), so case-sensitivity is
+    #    inherited from the host's namespace — HTML lowercases, SVG keeps the
+    #    spec name (`viewBox`).
     #
-    # - **Boolean**: the property is true iff the attribute is present
-    #   (value ignored). Setting to true writes an empty string; setting
-    #   to false removes the attribute.
+    #    - **String**: property mirrors the attribute value. Missing → `""`.
+    #    - **Boolean**: property is true iff the attribute is present. Setting
+    #      true writes `""`; setting false removes the attribute.
+    #
+    # 2. **A class-level DSL** (`reflect_string` / `reflect_boolean`) that
+    #    declares reflected attributes once and generates BOTH the snake_case
+    #    getter/setter pair AND a `js_key => ruby_name` registry entry. A shared
+    #    `__js_get__` / `__js_set__` consults that registry, so bridge property
+    #    access needs no hand-written `case` arm. This keeps the Ruby accessor,
+    #    the JS getter, and the JS setter from drifting apart (the same class of
+    #    bug the `js_methods` macro prevents for `__js_call__`).
+    #
+    #        reflect_string :cx, :cy, :r
+    #        reflect_string view_box: "viewBox", class_name: { attr: "class" }
+    #        reflect_boolean :disabled, :required
+    #
+    #    Identifier defaults (override via a String or Hash value):
+    #      - js_key (camelCase IDL name) = camelize(ruby_name)
+    #      - attr   (content attribute)  = camelize(ruby_name)
+    #      - String value overrides attr only:  text_anchor: "text-anchor"
+    #      - Hash value overrides either:       tabindex: { js: "tabIndex" }
     module ReflectedAttributes
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def reflect_string(*names, **mapped)
+          _reflect(:string, names, mapped)
+        end
+
+        def reflect_boolean(*names, **mapped)
+          _reflect(:boolean, names, mapped)
+        end
+
+        # Merged `js_key => ruby_name` map across the class ancestry (memoized).
+        # Recomputed lazily; `_reflect` invalidates the cache when called.
+        def reflected_property_map
+          @__reflected_map__ ||= begin
+            inherited = superclass.respond_to?(:reflected_property_map) ? superclass.reflected_property_map : {}
+            inherited.merge(@__reflected_props__ || {})
+          end
+        end
+
+        private
+
+        def _reflect(type, names, mapped)
+          @__reflected_props__ ||= {}
+          @__reflected_map__ = nil # invalidate memoized merge
+
+          getter = type == :boolean ? :reflected_boolean : :reflected_string
+          setter = type == :boolean ? :set_reflected_boolean : :set_reflected_string
+
+          (names.map { |n| [n, nil] } + mapped.to_a).each do |ruby_name, override|
+            attr, js = _resolve_identifiers(ruby_name, override)
+            define_method(ruby_name) { __send__(getter, attr) }
+            define_method(:"#{ruby_name}=") { |value| __send__(setter, attr, value) }
+            @__reflected_props__[js] = ruby_name
+          end
+        end
+
+        def _resolve_identifiers(ruby_name, override)
+          default = _camelize(ruby_name)
+          case override
+          when nil
+            [default, default]
+          when String
+            [override, default]
+          when Hash
+            [override[:attr] || default, override[:js] || default]
+          else
+            raise ArgumentError, "reflect_*: unsupported mapping for #{ruby_name.inspect}: #{override.inspect}"
+          end
+        end
+
+        def _camelize(name)
+          name.to_s.gsub(/_([a-z0-9])/) { ::Regexp.last_match(1).upcase }
+        end
+      end
+
+      # Bridge property read: route reflected keys to their accessor (which a
+      # subclass may have overridden with coercion), else up the super chain.
+      def __js_get__(key)
+        prop = self.class.reflected_property_map[key]
+        return __send__(prop) if prop
+
+        super
+      end
+
+      def __js_set__(key, value)
+        prop = self.class.reflected_property_map[key]
+        return __send__(:"#{prop}=", value) if prop
+
+        super
+      end
+
       private
 
       def reflected_string(name)