vident 1.0.0 → 1.0.2

data/lib/vident2/internals/resolver.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "draft"
+
+module Vident2
+  module Internals
+    # @api private
+    # Resolves Declarations + instance state into a Draft of typed
+    # Stimulus::* values. The implied controller seeds first (unless
+    # `no_stimulus_controller`); prop and root_element_attributes paths
+    # both APPEND.
+    #
+    # Two entry points:
+    #   `call`               — pure; returns a new Draft. Use `:static` or `:all`.
+    #   `resolve_procs_into` — mutates an existing Draft. Called at render
+    #                          time so DSL procs can reach `helpers` /
+    #                          `view_context` (not wired at `after_initialize`).
+    #
+    # Phases: `:static` skips anything with a `when_proc` or top-level Proc
+    # in args; `:procs` processes only those; `:all` does everything.
+    #
+    # Procs nested inside a Hash descriptor (`action(method: -> { ... })`)
+    # escape the gate — unsupported shape; use the fluent builder or a
+    # top-level Proc.
+    module Resolver
+      module_function
+
+      def call(declarations, instance, phase: :all)
+        raise ArgumentError, "use resolve_procs_into for phase: :procs" if phase == :procs
+
+        draft = Draft.new
+        implied = build_implied_controller(instance)
+
+        seed_implied_controller(draft, instance)
+        resolve_declarations(draft, declarations, instance, implied, phase: phase)
+        absorb_stimulus_props(draft, instance, implied, phase: phase)
+        absorb_root_element_attributes(draft, instance, implied, phase: phase)
+
+        draft
+      end
+
+      # Caller owns idempotence (Component uses `@__vident2_procs_resolved`).
+      def resolve_procs_into(draft, declarations, instance)
+        implied = build_implied_controller(instance)
+        resolve_declarations(draft, declarations, instance, implied, phase: :procs)
+        absorb_stimulus_props(draft, instance, implied, phase: :procs)
+        absorb_root_element_attributes(draft, instance, implied, phase: :procs)
+        draft
+      end
+
+      def build_implied_controller(instance)
+        path = instance.class.stimulus_identifier_path
+        name = instance.class.stimulus_identifier
+        ::Vident2::Stimulus::Controller.new(path: path, name: name)
+      end
+
+      def seed_implied_controller(draft, instance)
+        return unless instance.class.stimulus_controller?
+        draft.add_controllers(build_implied_controller(instance))
+      end
+
+      def resolve_declarations(draft, declarations, instance, implied, phase:)
+        resolve_positional(draft, :controllers, declarations.controllers, instance, phase: phase) do |args, meta, _inst|
+          ::Vident2::Stimulus::Controller.parse(*args, implied: implied, **meta_for_controller(meta))
+        end
+
+        resolve_positional(draft, :actions, declarations.actions, instance, phase: phase) do |args, _meta, _inst|
+          parse_single(::Vident2::Stimulus::Action, args, implied: implied, component_id: instance_id(instance))
+        end
+
+        resolve_positional(draft, :targets, declarations.targets, instance, phase: phase) do |args, _meta, _inst|
+          parse_single(::Vident2::Stimulus::Target, args, implied: implied, component_id: instance_id(instance))
+        end
+
+        resolve_keyed(draft, :outlets, declarations.outlets, instance, phase: phase) do |key, args, _meta|
+          parsed_args = [key_for_parse(key), *args]
+          parse_single(::Vident2::Stimulus::Outlet, parsed_args, implied: implied, component_id: instance_id(instance))
+        end
+
+        resolve_keyed_values(draft, declarations, instance, implied, phase: phase)
+        resolve_keyed_scalars(draft, :params, declarations.params, instance, implied, ::Vident2::Stimulus::Param, phase: phase)
+        resolve_keyed_scalars(draft, :class_maps, declarations.class_maps, instance, implied, ::Vident2::Stimulus::ClassMap, phase: phase)
+      end
+
+      def resolve_positional(draft, kind, entries, instance, phase:)
+        entries.each do |decl|
+          next unless phase_matches?(decl, phase)
+          next if gated_out?(decl.when_proc, instance)
+          args = resolve_args(decl.args, instance)
+          next if args.nil?
+          args = splat_single_array(args)
+          parsed = yield(args, decl.meta, instance)
+          draft.public_send(:"add_#{kind}", parsed) if parsed
+        end
+      end
+
+      # If `args` is a single Array element, unwrap it — positional kinds
+      # treat Array values as the singular parser's arg tuple.
+      def splat_single_array(args)
+        (args.size == 1 && args[0].is_a?(Array)) ? args[0] : args
+      end
+
+      def resolve_keyed(draft, kind, entries, instance, phase:)
+        entries.each do |(key, decl)|
+          next unless phase_matches?(decl, phase)
+          next if gated_out?(decl.when_proc, instance)
+          args = resolve_args(decl.args, instance)
+          next if args.nil?
+          parsed = yield(key, args, decl.meta)
+          draft.public_send(:"add_#{kind}", parsed) if parsed
+        end
+      end
+
+      def resolve_keyed_values(draft, declarations, instance, implied, phase:)
+        declarations.values.each do |(key, decl)|
+          next unless phase_matches?(decl, phase)
+          next if gated_out?(decl.when_proc, instance)
+
+          if decl.meta[:from_prop]
+            raw = read_prop(instance, key)
+            next if raw.nil?
+            draft.add_values(::Vident2::Stimulus::Value.parse(key, raw, implied: implied))
+            next
+          end
+
+          raw = resolve_value_meta(decl, instance)
+          next if raw.nil?
+          draft.add_values(::Vident2::Stimulus::Value.parse(key, raw, implied: implied))
+        end
+
+        # values_from_props is a plain Symbol list (no Declarations, so
+        # phase_matches? doesn't apply). Ivar reads only; run once.
+        return if phase == :procs
+        declarations.values_from_props.each do |name|
+          raw = read_prop(instance, name)
+          next if raw.nil?
+          draft.add_values(::Vident2::Stimulus::Value.parse(name, raw, implied: implied))
+        end
+      end
+
+      def resolve_keyed_scalars(draft, kind, entries, instance, implied, value_class, phase:)
+        entries.each do |(key, decl)|
+          next unless phase_matches?(decl, phase)
+          next if gated_out?(decl.when_proc, instance)
+          raw = resolve_value_meta(decl, instance)
+          next if raw.nil?
+          draft.public_send(:"add_#{kind}", value_class.parse(key, raw, implied: implied))
+        end
+      end
+
+      # Declaration-level phase gate. Nested Procs inside Hash args
+      # aren't inspected — see module docstring.
+      def phase_matches?(decl, phase)
+        return true if phase == :all
+        has_proc = decl.when_proc || decl.args.any? { |a| a.is_a?(Proc) }
+        (phase == :procs) ? has_proc : !has_proc
+      end
+
+      def absorb_stimulus_props(draft, instance, implied, phase:)
+        absorb_input(draft, :controllers, instance_ivar(instance, :@stimulus_controllers), instance, implied, phase: phase)
+        absorb_input(draft, :actions,     instance_ivar(instance, :@stimulus_actions),     instance, implied, phase: phase)
+        absorb_input(draft, :targets,     instance_ivar(instance, :@stimulus_targets),     instance, implied, phase: phase)
+        absorb_input(draft, :outlets,     instance_ivar(instance, :@stimulus_outlets),     instance, implied, phase: phase)
+        absorb_input(draft, :values,      instance_ivar(instance, :@stimulus_values),      instance, implied, phase: phase)
+        absorb_input(draft, :params,      instance_ivar(instance, :@stimulus_params),      instance, implied, phase: phase)
+        absorb_input(draft, :class_maps,  instance_ivar(instance, :@stimulus_classes),     instance, implied, phase: phase)
+      end
+
+      def absorb_root_element_attributes(draft, instance, implied, phase:)
+        return unless instance.respond_to?(:resolved_root_element_attributes, true)
+        attrs = instance.send(:resolved_root_element_attributes)
+        return unless attrs.is_a?(Hash) && !attrs.empty?
+
+        absorb_input(draft, :controllers, attrs[:stimulus_controllers], instance, implied, phase: phase)
+        absorb_input(draft, :actions,     attrs[:stimulus_actions],     instance, implied, phase: phase)
+        absorb_input(draft, :targets,     attrs[:stimulus_targets],     instance, implied, phase: phase)
+        absorb_input(draft, :outlets,     attrs[:stimulus_outlets],     instance, implied, phase: phase)
+        absorb_input(draft, :values,      attrs[:stimulus_values],      instance, implied, phase: phase)
+        absorb_input(draft, :params,      attrs[:stimulus_params],      instance, implied, phase: phase)
+        absorb_input(draft, :class_maps,  attrs[:stimulus_classes],     instance, implied, phase: phase)
+      end
+
+      # Fold a prop / root_element_attributes value into the Draft.
+      # Each Hash value / Array element may be a Proc; phase-gated.
+      def absorb_input(draft, kind, input, instance, implied, phase:)
+        return if input.nil?
+
+        kind_meta = Registry.fetch(kind)
+        case input
+        when Hash
+          input.each do |key, raw|
+            is_proc = raw.is_a?(Proc)
+            next unless phase_allows?(is_proc, phase)
+            absorbed = is_proc ? instance.instance_exec(&raw) : raw
+            next if absorbed.nil?
+            if kind_meta.keyed
+              parsed = kind_meta.value_class.parse(key, absorbed, implied: implied, component_id: instance_id(instance))
+              draft.public_send(:"add_#{kind}", parsed)
+            else
+              parsed = parse_entry(kind_meta, [key, absorbed], implied: implied, component_id: instance_id(instance))
+              draft.public_send(:"add_#{kind}", parsed) if parsed
+            end
+          end
+        when Array
+          input.each do |entry|
+            is_proc = entry.is_a?(Proc)
+            next unless phase_allows?(is_proc, phase)
+            parsed = absorb_one(kind_meta, entry, instance, implied)
+            draft.public_send(:"add_#{kind}", parsed) if parsed
+          end
+        else
+          is_proc = input.is_a?(Proc)
+          return unless phase_allows?(is_proc, phase)
+          parsed = absorb_one(kind_meta, input, instance, implied)
+          draft.public_send(:"add_#{kind}", parsed) if parsed
+        end
+      end
+
+      # Element-level gate (raw boolean; parallels Declaration-level `phase_matches?`).
+      def phase_allows?(is_proc, phase)
+        case phase
+        when :all    then true
+        when :static then !is_proc
+        when :procs  then is_proc
+        end
+      end
+
+      def absorb_one(kind_meta, entry, instance, implied)
+        entry = instance.instance_exec(&entry) if entry.is_a?(Proc)
+        return nil if entry.nil?
+        return entry if entry.is_a?(kind_meta.value_class)
+
+        parse_entry(kind_meta, entry, implied: implied, component_id: instance_id(instance))
+      end
+
+      def parse_entry(kind_meta, entry, implied:, component_id:)
+        case entry
+        when Hash
+          if kind_meta.keyed
+            first_key, first_val = entry.first
+            kind_meta.value_class.parse(first_key, first_val, implied: implied, component_id: component_id)
+          else
+            kind_meta.value_class.parse(entry, implied: implied, component_id: component_id)
+          end
+        when Array
+          kind_meta.value_class.parse(*entry, implied: implied, component_id: component_id)
+        else
+          kind_meta.value_class.parse(entry, implied: implied, component_id: component_id)
+        end
+      end
+
+      # Evaluate proc args in the instance binding. Only nil drops —
+      # false / blank strings / empty collections reach the parser.
+      def resolve_args(args, instance)
+        resolved = args.map { |arg| arg.is_a?(Proc) ? instance.instance_exec(&arg) : arg }
+        return nil if resolved.any?(&:nil?)
+        resolved
+      end
+
+      # Values accept the raw in args (proc or literal) or meta (`static:`).
+      def resolve_value_meta(decl, instance)
+        return decl.meta[:static] if decl.meta.key?(:static)
+        return nil if decl.args.empty?
+
+        raw = decl.args.first
+        raw = instance.instance_exec(&raw) if raw.is_a?(Proc)
+        raw
+      end
+
+      def gated_out?(when_proc, instance)
+        return false unless when_proc
+        !instance.instance_exec(&when_proc)
+      end
+
+      def parse_single(value_class, args, implied:, component_id:)
+        value_class.parse(*args, implied: implied, component_id: component_id)
+      end
+
+      def key_for_parse(key) = key
+
+      # Controller parse takes `as:` as a kwarg, not a positional.
+      def meta_for_controller(meta) = meta.slice(:as)
+
+      def instance_ivar(instance, name)
+        return nil unless instance.instance_variable_defined?(name)
+        instance.instance_variable_get(name)
+      end
+
+      # Raw ivar — calling `#id` would trigger auto-generation, and
+      # outlet auto-selectors include the `#<id>` prefix only when the
+      # user explicitly set one.
+      def instance_id(instance)
+        return nil unless instance.instance_variable_defined?(:@id)
+        raw = instance.instance_variable_get(:@id)
+        raw.presence
+      end
+
+      def read_prop(instance, name)
+        ivar = :"@#{name}"
+        return nil unless instance.instance_variable_defined?(ivar)
+        instance.instance_variable_get(ivar)
+      end
+    end
+  end
+end

data/lib/vident2/internals/target_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+
+module Vident2
+  module Internals
+    # @api private
+    # Fluent chain returned by `target(...)` inside a `stimulus do` block.
+    # The only current chain method is `.when` (conditional inclusion);
+    # the target itself has no other DSL-facing knobs.
+    #
+    #   target(:row).when { @rows.any? }
+    class TargetBuilder
+      def initialize(*args)
+        @args = args
+        @when_proc = nil
+      end
+
+      def when(callable = nil, &block)
+        @when_proc = block || callable
+        self
+      end
+
+      def to_declaration
+        Declaration.new(args: @args.freeze, when_proc: @when_proc, meta: {}.freeze)
+      end
+    end
+  end
+end

data/lib/vident2/phlex/html.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vident2
+  module Phlex
+    class HTML < ::Phlex::HTML
+      include ::Vident2::Component
+
+      STANDARD_ELEMENTS = %i[
+        a abbr address article aside b bdi bdo blockquote body button caption
+        cite code colgroup data datalist dd del details dfn dialog div dl dt
+        em fieldset figcaption figure footer form g h1 h2 h3 h4 h5 h6 head
+        header hgroup html i iframe ins kbd label legend li main map mark
+        menuitem meter nav noscript object ol optgroup option output p path
+        picture pre progress q rp rt ruby s samp script section select slot
+        small span strong style sub summary sup svg table tbody td template_tag
+        textarea tfoot th thead time title tr u ul video wbr
+      ].freeze
+      VOID_ELEMENTS = %i[area br embed hr img input link meta param source track col].freeze
+      VALID_TAGS = Set[*(STANDARD_ELEMENTS + VOID_ELEMENTS)].freeze
+
+      class << self
+        # Capture the subclass's defining `.rb` path at class-definition
+        # time so Caching#cache_component_modified_time can read its mtime.
+        # Walks caller_locations to skip the `inherited` frame itself.
+        def inherited(subclass)
+          loc = caller_locations(1, 10).reject { |l| l.label == "inherited" }[0]
+          subclass.component_source_file_path = loc&.path
+          super
+        end
+
+        attr_accessor :component_source_file_path
+
+        def cache_component_modified_time
+          path = component_source_file_path
+          raise StandardError, "No component source file exists #{path}" unless path && ::File.exist?(path)
+          ::File.mtime(path).to_i.to_s
+        end
+      end
+
+      # Phlex lifecycle hook: resolve stimulus DSL procs now that
+      # `view_context` / `helpers` are wired. Procs declared in the DSL
+      # stayed unresolved at `after_initialize`; this is where they run.
+      def before_template
+        resolve_stimulus_attributes_at_render_time
+        super
+      end
+
+      # Block-capture-first so children initialising inside the block can
+      # mutate THIS instance's Draft (outlet-host pattern). After the
+      # block returns, we seal the Draft and emit the tag.
+      def root_element(**overrides, &block)
+        tag_type = root_element_tag_type
+        check_valid_html_tag!(tag_type)
+        if block
+          content = capture(self, &block).html_safe
+          options = build_root_element_attributes(overrides)
+          send(tag_type, **options) { content }
+        else
+          options = build_root_element_attributes(overrides)
+          send(tag_type, **options)
+        end
+      end
+
+      private
+
+      def check_valid_html_tag!(tag_name)
+        return if VALID_TAGS.include?(tag_name)
+        raise ArgumentError,
+          "Unsupported HTML tag name #{tag_name}. Valid tags are: #{VALID_TAGS.to_a.join(", ")}"
+      end
+
+      # Phlex tag DSL emits open-close pairs for non-void tags and
+      # self-closing for void tags automatically, so we just forward.
+      def generate_child_element(tag_name, stimulus_data_attributes, options, &block)
+        check_valid_html_tag!(tag_name)
+        options[:data] ||= {}
+        options[:data].merge!(stimulus_data_attributes)
+        send(tag_name, **options, &block)
+      end
+    end
+  end
+end

data/lib/vident2/phlex.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "phlex"
+require "vident2/phlex/html"
+
+module Vident2
+  module Phlex
+  end
+end

data/lib/vident2/stimulus/action.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "controller"
+
+module Vident2
+  module Stimulus
+    # `data-action` fragment: single action descriptor like
+    # `"click->admin--users#handleClick"`.
+    #
+    # Fields folded in from v1's `StimulusAction::Descriptor` — there's no
+    # separate Descriptor class in V2; Hash DSL input parses directly into
+    # an `Action`.
+    class Action < ::Literal::Data
+      # Stimulus action options (`:once`, `:prevent`, etc.). Keep in sync
+      # with https://stimulus.hotwired.dev/reference/actions#options.
+      VALID_OPTIONS = %i[once prevent stop passive !passive capture self].freeze
+
+      prop :controller, Controller
+      prop :method_name, String
+      prop :event, _Nilable(String), default: nil
+      prop :modifiers, _Array(Symbol), default: -> { [] }
+      prop :keyboard, _Nilable(String), default: nil
+      prop :window, _Boolean, default: false
+
+      # `.parse(*args, implied:)` grammar mirrors v1 `StimulusAction#parse_arguments`:
+      #   (Symbol)                        -> :method on implied controller, no event
+      #   (String)                        -> pre-qualified "event->ctrl#method" / "ctrl#method"
+      #   (Hash)                          -> keyword descriptor (method:/event:/...)
+      #   (Symbol, Symbol)                -> (event, method) on implied
+      #   (String, Symbol)                -> (controller_path, method) — no event
+      #   (Symbol, String, Symbol)        -> (event, controller_path, method)
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Hash => h]
+          from_descriptor(h, implied: implied)
+        in [Symbol => method_sym]
+          new(
+            controller: implied,
+            method_name: Naming.js_name(method_sym),
+            event: nil
+          )
+        in [String => s]
+          parse_qualified_string(s)
+        in [Symbol => event, Symbol => method_sym]
+          new(
+            controller: implied,
+            method_name: Naming.js_name(method_sym),
+            event: event.to_s
+          )
+        in [String => ctrl_path, Symbol => method_sym]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            method_name: Naming.js_name(method_sym),
+            event: nil
+          )
+        in [Symbol => event, String => ctrl_path, Symbol => method_sym]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            method_name: Naming.js_name(method_sym),
+            event: event.to_s
+          )
+        else
+          raise ::Vident2::ParseError, "Action.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      # Serialised descriptor, e.g. `"click.esc:prevent@window->foo--bar#handle"`.
+      def to_s
+        head =
+          if event
+            ev = event.to_s
+            ev = "#{ev}.#{keyboard}" if keyboard
+            ev = "#{ev}#{modifiers.map { |o| ":#{o}" }.join}" if modifiers.any?
+            ev = "#{ev}@window" if window
+            "#{ev}->"
+          else
+            ""
+          end
+        "#{head}#{controller.name}##{method_name}"
+      end
+
+      def to_data_pair = [:action, to_s]
+
+      def to_h = {action: to_s}
+      alias_method :to_hash, :to_h
+
+      # Actions space-join under a single `:action` key, preserving order.
+      def self.to_data_hash(actions)
+        return {} if actions.empty?
+        {action: actions.map(&:to_s).join(" ")}
+      end
+
+      # `.parse({event:, method:, controller:, options:, keyboard:, window:})`
+      # Keyword-descriptor entry point, used by the DSL Hash form.
+      def self.from_descriptor(h, implied:)
+        invalid_options = Array(h[:options]) - VALID_OPTIONS
+        unless invalid_options.empty?
+          raise ::Vident2::ParseError,
+            "Action.parse: invalid option(s) #{invalid_options.inspect}. Valid: #{VALID_OPTIONS.inspect}"
+        end
+
+        method_raw = h.fetch(:method)
+        method_name = method_raw.is_a?(Symbol) ? Naming.js_name(method_raw) : method_raw.to_s
+        controller = h[:controller] ? Controller.parse(h[:controller], implied: implied) : implied
+        new(
+          controller: controller,
+          method_name: method_name,
+          event: h[:event]&.to_s,
+          modifiers: Array(h[:options]),
+          keyboard: h[:keyboard],
+          window: h.fetch(:window, false)
+        )
+      end
+
+      # Pre-qualified string form, e.g. `"click->admin/users#show"` or
+      # `"admin--users#show"`. Pass-through: the controller segment is NOT
+      # re-stimulized. Flagged for deprecation.
+      def self.parse_qualified_string(s)
+        if s.include?("->")
+          event_part, ctrl_method = s.split("->", 2)
+          ctrl, method = ctrl_method.split("#", 2)
+          new(
+            controller: Controller.new(path: ctrl, name: ctrl),
+            method_name: method,
+            event: event_part
+          )
+        else
+          ctrl, method = s.split("#", 2)
+          new(
+            controller: Controller.new(path: ctrl, name: ctrl),
+            method_name: method,
+            event: nil
+          )
+        end
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/class_map.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "controller"
+
+module Vident2
+  module Stimulus
+    # `data-<ctrl>-<name>-class` fragment — a named CSS class set readable
+    # on the JS side as `this.<name>Class`. Renamed from v1's
+    # `StimulusClass` (which collided with Ruby's `Class` — uncomfortable
+    # to type in user code).
+    #
+    # `css` holds the final serialised string form (space-joined); the
+    # parser normalises String / Array-of-String / Array-of-anything inputs
+    # down to one shape so the Draft/Plan doesn't have to care.
+    class ClassMap < ::Literal::Data
+      prop :controller, Controller
+      prop :name, String
+      prop :css, String
+
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => name_sym, css_input]
+          new(
+            controller: implied,
+            name: name_sym.to_s.dasherize,
+            css: normalize_css(css_input)
+          )
+        in [String => ctrl_path, Symbol => name_sym, css_input]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: name_sym.to_s.dasherize,
+            css: normalize_css(css_input)
+          )
+        else
+          raise ::Vident2::ParseError, "ClassMap.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def self.normalize_css(input)
+        case input
+        when String
+          input.split(/\s+/).reject(&:empty?).join(" ")
+        when Array
+          input.map(&:to_s).reject(&:empty?).join(" ")
+        else
+          raise ::Vident2::ParseError, "ClassMap.parse: css must be a String or Array, got #{input.class}"
+        end
+      end
+
+      def to_s = css
+
+      def data_attribute_key = :"#{controller.name}-#{name}-class"
+
+      def to_data_pair = [data_attribute_key, css]
+
+      def to_h = {data_attribute_key => css}
+      alias_method :to_hash, :to_h
+
+      def self.to_data_hash(maps)
+        maps.each_with_object({}) do |m, acc|
+          key, str = m.to_data_pair
+          acc[key] = str
+        end
+      end
+    end
+  end
+end

data/lib/vident2/stimulus/collection.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Vident2
+  module Stimulus
+    # Tiny aggregation wrapper for the plural `stimulus_<kind>s` parsers.
+    # Parametric over `kind`: the kind decides the per-element combining
+    # rule via its value class's `.to_data_hash`. Users interact with
+    # this object by splatting `{**component.stimulus_targets(...)}` into
+    # a `data:` option on a tag, so `#to_h` is the single required shape.
+    class Collection
+      include Enumerable
+
+      attr_reader :kind, :items
+
+      def initialize(kind:, items:)
+        @kind = kind
+        @items = items.freeze
+      end
+
+      def each(&block) = @items.each(&block)
+      def to_a = @items.dup
+      def size = @items.size
+      def length = @items.size
+      def empty? = @items.empty?
+      def any? = @items.any?
+
+      # Delegates to the kind's `.to_data_hash` — same path AttributeWriter
+      # uses at render time.
+      def to_h
+        @kind.value_class.to_data_hash(@items)
+      end
+      alias_method :to_hash, :to_h
+
+      def merge(other)
+        unless other.is_a?(self.class) && other.kind == @kind
+          raise ArgumentError, "Collection#merge: can only merge with same-kind Collection"
+        end
+        self.class.new(kind: @kind, items: @items + other.items)
+      end
+    end
+  end
+end