vident 1.0.1 → 2.0.0

data/lib/vident/internals/resolver.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "draft"
+
+module Vident
+  module Internals
+    # 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
+
+      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)
+        alias_map = build_alias_map(declarations)
+
+        seed_implied_controller(draft, instance)
+        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
+
+      def resolve_procs_into(draft, declarations, instance)
+        implied = build_implied_controller(instance)
+        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
+        ::Vident::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:, 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:) 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:) 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:) do |key, args, _meta|
+          parsed_args = [key_for_parse(key), *args]
+          parse_single(::Vident::Stimulus::Outlet, parsed_args, implied: implied, component_id: instance_id(instance))
+        end
+
+        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:)
+        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
+
+      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(::Vident::Stimulus::Value.parse(key, raw, implied: implied))
+            next
+          end
+
+          raw = resolve_value_meta(decl, instance)
+          next if raw.nil?
+          draft.add_values(::Vident::Stimulus::Value.parse(key, raw, implied: implied))
+        end
+
+        # 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(::Vident::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
+
+      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:, 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:, 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:, 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
+
+      def absorb_input(draft, kind, input, instance, implied, phase:, alias_map: {})
+        return if input.nil?
+
+        kind_meta = Registry.fetch(kind)
+        case input
+        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?
+              parsed = kind_meta.value_class.parse(key, absorbed, implied: implied, component_id: instance_id(instance))
+              draft.public_send(:"add_#{kind}", parsed)
+            else
+              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
+        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, 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, kind:, alias_map:)
+          draft.public_send(:"add_#{kind}", parsed) if parsed
+        end
+      end
+
+      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
+        in :all then true
+        in :static then !is_proc
+        in :procs then is_proc
+        end
+      end
+
+      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?
+            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
+
+      # 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
+
+      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
+
+      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
+
+      # Must match the mutation-API path (#id, memoised) so DSL outlet
+      # auto-selectors and runtime-added outlets scope identically.
+      def instance_id(instance)
+        instance.id
+      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/vident/internals/target_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+
+module Vident
+  module Internals
+    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/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/vident/stimulus/action.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "controller"
+require_relative "base"
+
+module Vident
+  module Stimulus
+    # `data-action` fragment: single action descriptor like
+    # `"click->admin--users#handleClick"`.
+    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
+      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
+
+      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]
+          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 ::Vident::ParseError, "Action.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      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
+
+      def self.to_data_hash(actions)
+        return {} if actions.empty?
+        {action: actions.map(&:to_s).join(" ")}
+      end
+
+      def self.from_descriptor(h, implied:)
+        invalid_options = Array(h[:options]) - VALID_OPTIONS
+        unless invalid_options.empty?
+          raise ::Vident::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
+
+      # 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)
+          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/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/vident/stimulus/class_map.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "base"
+require_relative "controller"
+
+module Vident
+  module Stimulus
+    # `data-<ctrl>-<name>-class` fragment — a named CSS class set readable
+    # on the JS side as `this.<name>Class`.
+    class ClassMap < Base
+      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 ::Vident::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 ::Vident::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
+    end
+  end
+end

data/lib/vident/stimulus/collection.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Vident
+  module Stimulus
+    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?
+
+      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

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

data/lib/vident/stimulus/controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "base"
+
+module Vident
+  module Stimulus
+    # `data-controller` fragment.
+    class Controller < Base
+      prop :path, String
+      prop :name, String
+      prop :alias_name, _Nilable(Symbol), default: nil
+
+      def self.parse(*args, implied:, as: nil, component_id: nil)
+        case args.size
+        when 0
+          new(path: implied.path, name: implied.name, alias_name: as)
+        when 1
+          raw = args[0]
+          path = raw.to_s
+          new(path: path, name: Naming.stimulize_path(path), alias_name: as)
+        else
+          raise ::Vident::ParseError, "Controller.parse: expected 0 or 1 positional args, got #{args.size}"
+        end
+      end
+
+      def identifier = name
+
+      def to_s = name
+
+      def to_data_pair = [:controller, name]
+
+      def to_h = {controller: name}
+      alias_method :to_hash, :to_h
+
+      def self.to_data_hash(controllers)
+        return {} if controllers.empty?
+        joined = controllers.map(&:name).reject(&:empty?).join(" ")
+        return {} if joined.empty?
+        {controller: joined}
+      end
+    end
+  end
+end