vident 1.0.2 → 2.0.0

data/lib/{vident2 → vident}/internals/resolver.rb

@@ -3,26 +3,11 @@
 require_relative "registry"
 require_relative "draft"
 
-module Vident2
+module Vident
   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.
+    # Resolves raw Declarations and instance state into a Draft of typed Stimulus values.
+    # Phase `:static` skips proc-bearing entries; `:procs` processes only those; `:all` does both.
+    # Procs nested inside a Hash descriptor escape the phase gate — use the fluent builder instead.
     module Resolver
       module_function
 
@@ -31,28 +16,41 @@ module Vident2
 
         draft = Draft.new
         implied = build_implied_controller(instance)
+        alias_map = build_alias_map(declarations)
 
         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)
+        resolve_declarations(draft, declarations, instance, implied, phase:, alias_map:)
+        absorb_stimulus_props(draft, instance, implied, phase:, alias_map:)
+        absorb_root_element_attributes(draft, instance, implied, phase:, alias_map:)
 
         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)
+        alias_map = build_alias_map(declarations)
+        resolve_declarations(draft, declarations, instance, implied, phase: :procs, alias_map:)
+        absorb_stimulus_props(draft, instance, implied, phase: :procs, alias_map:)
+        absorb_root_element_attributes(draft, instance, implied, phase: :procs, alias_map:)
         draft
       end
 
+      def build_alias_map(declarations)
+        map = {}
+        declarations.controllers.each do |decl|
+          alias_name = decl.meta[:as]
+          next unless alias_name
+          raw_path = decl.args.first
+          next if raw_path.nil?
+          map[alias_name] = raw_path.to_s
+        end
+        map
+      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)
+        ::Vident::Stimulus::Controller.new(path: path, name: name)
       end
 
       def seed_implied_controller(draft, instance)
@@ -60,27 +58,40 @@ module Vident2
         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))
+      def resolve_declarations(draft, declarations, instance, implied, phase:, alias_map: {})
+        resolve_positional(draft, :controllers, declarations.controllers, instance, phase:) do |args, meta, _inst|
+          ::Vident::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))
+        resolve_positional(draft, :actions, declarations.actions, instance, phase:) do |args, _meta, _inst|
+          parse_single(::Vident::Stimulus::Action, resolve_action_aliases(args, alias_map), 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))
+        resolve_positional(draft, :targets, declarations.targets, instance, phase:) do |args, _meta, _inst|
+          parse_single(::Vident::Stimulus::Target, args, implied: implied, component_id: instance_id(instance))
         end
 
-        resolve_keyed(draft, :outlets, declarations.outlets, instance, phase: phase) do |key, args, _meta|
+        resolve_keyed(draft, :outlets, declarations.outlets, instance, 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))
+          parse_single(::Vident::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)
+        resolve_keyed_values(draft, declarations, instance, implied, phase:)
+        resolve_keyed_scalars(draft, :params, declarations.params, instance, implied, ::Vident::Stimulus::Param, phase:)
+        resolve_keyed_scalars(draft, :class_maps, declarations.class_maps, instance, implied, ::Vident::Stimulus::ClassMap, phase:)
+      end
+
+      # Unknown aliases raise — a symbolic controller ref is declared intent, not a guess.
+      def resolve_action_aliases(args, alias_map)
+        return args if alias_map.empty?
+        args.map do |arg|
+          next arg unless arg.is_a?(Hash) && arg[:controller].is_a?(Symbol)
+          sym = arg[:controller]
+          unless alias_map.key?(sym)
+            raise ::Vident::DeclarationError, "Unknown controller alias :#{sym} in action. Declared aliases: #{alias_map.keys.inspect}"
+          end
+          arg.merge(controller: alias_map[sym])
+        end
       end
 
       def resolve_positional(draft, kind, entries, instance, phase:)
@@ -95,8 +106,6 @@ module Vident2
         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
@@ -120,22 +129,21 @@ module Vident2
           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))
+            draft.add_values(::Vident::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))
+          draft.add_values(::Vident::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.
+        # values_from_props has no when_proc, so phase_matches? doesn't apply; skip on :procs pass.
         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))
+          draft.add_values(::Vident::Stimulus::Value.parse(name, raw, implied: implied))
         end
       end
 
@@ -149,95 +157,103 @@ module Vident2
         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)
+      def absorb_stimulus_props(draft, instance, implied, phase:, alias_map: {})
+        absorb_input(draft, :controllers, instance_ivar(instance, :@stimulus_controllers), instance, implied, phase:, alias_map:)
+        absorb_input(draft, :actions, instance_ivar(instance, :@stimulus_actions), instance, implied, phase:, alias_map:)
+        absorb_input(draft, :targets, instance_ivar(instance, :@stimulus_targets), instance, implied, phase:, alias_map:)
+        absorb_input(draft, :outlets, instance_ivar(instance, :@stimulus_outlets), instance, implied, phase:, alias_map:)
+        absorb_input(draft, :values, instance_ivar(instance, :@stimulus_values), instance, implied, phase:, alias_map:)
+        absorb_input(draft, :params, instance_ivar(instance, :@stimulus_params), instance, implied, phase:, alias_map:)
+        absorb_input(draft, :class_maps, instance_ivar(instance, :@stimulus_classes), instance, implied, phase:, alias_map:)
       end
 
-      def absorb_root_element_attributes(draft, instance, implied, phase:)
+      def absorb_root_element_attributes(draft, instance, implied, phase:, alias_map: {})
         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)
+        absorb_input(draft, :controllers, attrs[:stimulus_controllers], instance, implied, phase:, alias_map:)
+        absorb_input(draft, :actions, attrs[:stimulus_actions], instance, implied, phase:, alias_map:)
+        absorb_input(draft, :targets, attrs[:stimulus_targets], instance, implied, phase:, alias_map:)
+        absorb_input(draft, :outlets, attrs[:stimulus_outlets], instance, implied, phase:, alias_map:)
+        absorb_input(draft, :values, attrs[:stimulus_values], instance, implied, phase:, alias_map:)
+        absorb_input(draft, :params, attrs[:stimulus_params], instance, implied, phase:, alias_map:)
+        absorb_input(draft, :class_maps, attrs[:stimulus_classes], instance, implied, phase:, alias_map:)
       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:)
+      def absorb_input(draft, kind, input, instance, implied, phase:, alias_map: {})
         return if input.nil?
 
         kind_meta = Registry.fetch(kind)
         case input
-        when Hash
-          input.each do |key, raw|
+        in Hash => h
+          h.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
+            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))
+              entry = resolve_absorb_alias(kind, [key, absorbed], alias_map)
+              parsed = parse_entry(kind_meta, entry, implied: implied, component_id: instance_id(instance))
               draft.public_send(:"add_#{kind}", parsed) if parsed
             end
           end
-        when Array
-          input.each do |entry|
+        in Array => a
+          a.each do |entry|
             is_proc = entry.is_a?(Proc)
             next unless phase_allows?(is_proc, phase)
-            parsed = absorb_one(kind_meta, entry, instance, implied)
+            parsed = absorb_one(kind_meta, entry, instance, implied, kind:, alias_map:)
             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)
+          parsed = absorb_one(kind_meta, input, instance, implied, kind:, alias_map:)
           draft.public_send(:"add_#{kind}", parsed) if parsed
         end
       end
 
-      # Element-level gate (raw boolean; parallels Declaration-level `phase_matches?`).
+      def resolve_absorb_alias(kind, entry, alias_map)
+        return entry unless kind == :actions && alias_map.any?
+        return entry unless entry.is_a?(Hash) && entry[:controller].is_a?(Symbol)
+        sym = entry[:controller]
+        unless alias_map.key?(sym)
+          raise ::Vident::DeclarationError, "Unknown controller alias :#{sym} in stimulus_actions input. Declared aliases: #{alias_map.keys.inspect}"
+        end
+        entry.merge(controller: alias_map[sym])
+      end
+
+      # Uses pattern matching so an unknown phase raises NoMatchingPatternError early.
       def phase_allows?(is_proc, phase)
         case phase
-        when :all    then true
-        when :static then !is_proc
-        when :procs  then is_proc
+        in :all then true
+        in :static then !is_proc
+        in :procs then is_proc
         end
       end
 
-      def absorb_one(kind_meta, entry, instance, implied)
+      def absorb_one(kind_meta, entry, instance, implied, kind: nil, alias_map: {})
         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)
 
+        entry = resolve_absorb_alias(kind, entry, alias_map) if kind
         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
+          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
@@ -250,15 +266,13 @@ module Vident2
         end
       end
 
-      # Evaluate proc args in the instance binding. Only nil drops —
-      # false / blank strings / empty collections reach the parser.
+      # Only nil drops — false, blank strings, and 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?
@@ -279,7 +293,6 @@ module Vident2
 
       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)
@@ -287,13 +300,10 @@ module Vident2
         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.
+      # Must match the mutation-API path (#id, memoised) so DSL outlet
+      # auto-selectors and runtime-added outlets scope identically.
       def instance_id(instance)
-        return nil unless instance.instance_variable_defined?(:@id)
-        raw = instance.instance_variable_get(:@id)
-        raw.presence
+        instance.id
       end
 
       def read_prop(instance, name)

data/lib/{vident2 → vident}/internals/target_builder.rb

@@ -2,14 +2,8 @@
 
 require_relative "declaration"
 
-module Vident2
+module Vident
   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

data/lib/vident/stable_id.rb

@@ -5,9 +5,9 @@ require "digest/md5"
 
 module Vident
   class StableId
-    class GeneratorNotSetError < StandardError; end
+    class GeneratorNotSetError < ::Vident::ConfigurationError; end
 
-    class StrategyNotConfiguredError < StandardError; end
+    class StrategyNotConfiguredError < ::Vident::ConfigurationError; end
 
     RANDOM_FALLBACK = ->(generator) do
       return Random.hex(16) unless generator
@@ -25,7 +25,7 @@ module Vident
     end
 
     class << self
-      # Callable(generator_or_nil) -> String. Starts nil; host app must configure it.
+      # Callable(generator_or_nil) -> String. Host app must configure before first render.
       attr_accessor :strategy
 
       def set_current_sequence_generator(seed:)

data/lib/{vident2 → vident}/stimulus/action.rb

@@ -3,18 +3,14 @@
 require "literal"
 require_relative "naming"
 require_relative "controller"
+require_relative "base"
 
-module Vident2
+module Vident
   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.
+    class Action < Base
+      # 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
@@ -24,15 +20,12 @@ module Vident2
       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 [Action => a]
+          a
+        in [Symbol => event, Action => a]
+          a.with(event: event.to_s)
         in [Hash => h]
           from_descriptor(h, implied: implied)
         in [Symbol => method_sym]
@@ -62,11 +55,10 @@ module Vident2
             event: event.to_s
           )
         else
-          raise ::Vident2::ParseError, "Action.parse: invalid arguments #{args.inspect}"
+          raise ::Vident::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
@@ -86,18 +78,15 @@ module Vident2
       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,
+          raise ::Vident::ParseError,
             "Action.parse: invalid option(s) #{invalid_options.inspect}. Valid: #{VALID_OPTIONS.inspect}"
         end
 
@@ -114,9 +103,7 @@ module Vident2
         )
       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.
+      # Pass-through: the controller segment is NOT re-stimulized.
       def self.parse_qualified_string(s)
         if s.include?("->")
           event_part, ctrl_method = s.split("->", 2)

data/lib/vident/stimulus/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "combinable"
+
+module Vident
+  module Stimulus
+    # Shared frozen-value base for the Stimulus primitive value classes
+    # (Action, Target, Controller, Outlet, Value, Param, ClassMap).
+    # Provides `Combinable` (`with`, pattern-matching `deconstruct_keys`)
+    # and a default `to_data_hash(items)` that subclasses override when
+    # they need non-trivial collection semantics (space-join etc.).
+    #
+    # Subclasses still override `to_h` / `to_hash` per class — Literal
+    # auto-generates a prop-hash `to_h` from the prop DSL that would
+    # shadow any default here, so the data-attribute-shape override
+    # must live on each concrete class.
+    class Base < ::Literal::Data
+      include Combinable
+
+      def self.to_data_hash(items)
+        items.to_h(&:to_data_pair)
+      end
+    end
+  end
+end

data/lib/{vident2 → vident}/stimulus/class_map.rb

@@ -2,19 +2,14 @@
 
 require "literal"
 require_relative "naming"
+require_relative "base"
 require_relative "controller"
 
-module Vident2
+module Vident
   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
+    # on the JS side as `this.<name>Class`.
+    class ClassMap < Base
       prop :controller, Controller
       prop :name, String
       prop :css, String
@@ -34,7 +29,7 @@ module Vident2
             css: normalize_css(css_input)
           )
         else
-          raise ::Vident2::ParseError, "ClassMap.parse: invalid arguments #{args.inspect}"
+          raise ::Vident::ParseError, "ClassMap.parse: invalid arguments #{args.inspect}"
         end
       end
 
@@ -45,7 +40,7 @@ module Vident2
         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}"
+          raise ::Vident::ParseError, "ClassMap.parse: css must be a String or Array, got #{input.class}"
         end
       end
 
@@ -57,13 +52,6 @@ module Vident2
 
       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 → vident}/stimulus/collection.rb

@@ -1,12 +1,7 @@
 # frozen_string_literal: true
 
-module Vident2
+module Vident
   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
 
@@ -18,14 +13,17 @@ module Vident2
       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

data/lib/vident/stimulus/combinable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Vident
+  module Stimulus
+    # Shared `with(**overrides)` combinator for the frozen value classes.
+    # Mirrors Ruby's `Data.define#with` convention (which Literal::Data
+    # doesn't ship) so callers can decorate a value object without
+    # mutating it.
+    module Combinable
+      # Canonical Ruby Data-object hooks. The value classes override `to_h`
+      # to serialise to their data-attribute shape; without this module,
+      # `deconstruct_keys` would inherit that override and pattern-matching
+      # (`case a; in {event:}`) would silently fail.
+      def deconstruct_keys(keys)
+        h = self.class.literal_properties.properties_index.each_with_object({}) do |(name, _), acc|
+          acc[name.to_sym] = public_send(name)
+        end
+        keys ? h.slice(*keys) : h
+      end
+
+      def deconstruct
+        deconstruct_keys(nil).values
+      end
+
+      def with(**overrides)
+        self.class.new(**deconstruct_keys(nil).merge(overrides))
+      end
+    end
+  end
+end