vident 1.0.1 → 2.0.0

data/lib/vident/stimulus_builder.rb

@@ -1,119 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusBuilder
-    # Primitives the DSL block tracks. Controllers are set via the component's
-    # `stimulus_controllers:` prop, not the DSL, so they're skipped here.
-    # Storage shape per primitive is an Array for positional kinds (actions,
-    # targets) and a Hash for keyed kinds (values, params, classes, outlets).
-    DSL_PRIMITIVES = Stimulus::PRIMITIVES.reject { |primitive| primitive.name == :controllers }.freeze
-
-    def initialize
-      @entries = DSL_PRIMITIVES.to_h { |primitive| [primitive.name, primitive.keyed? ? {} : []] }
-      @values_from_props = []
-    end
-
-    def merge_with(other)
-      DSL_PRIMITIVES.each do |primitive|
-        mine = @entries[primitive.name]
-        theirs = other.entries_for(primitive.name)
-        primitive.keyed? ? mine.merge!(theirs) : mine.concat(theirs)
-      end
-      @values_from_props.concat(other.values_from_props_list)
-      self
-    end
-
-    def actions(*names)
-      @entries[:actions].concat(names)
-      self
-    end
-
-    def targets(*names)
-      @entries[:targets].concat(names)
-      self
-    end
-
-    def values(**hash)
-      @entries[:values].merge!(hash) unless hash.empty?
-      self
-    end
-
-    def params(**hash)
-      @entries[:params].merge!(hash) unless hash.empty?
-      self
-    end
-
-    def classes(**hash)
-      @entries[:classes].merge!(hash) unless hash.empty?
-      self
-    end
-
-    def values_from_props(*names)
-      @values_from_props.concat(names)
-      self
-    end
-
-    # `outlets({"admin--users" => ".sel"})` accepts a positional Hash for
-    # identifiers that can't be Ruby kwarg keys (contain `--`).
-    def outlets(positional = nil, **hash)
-      bucket = @entries[:outlets]
-      bucket.merge!(positional) if positional.is_a?(Hash)
-      bucket.merge!(hash) unless hash.empty?
-      self
-    end
-
-    def to_attributes(component_instance)
-      attrs = {}
-      DSL_PRIMITIVES.each do |primitive|
-        entries = @entries[primitive.name]
-        next if entries.empty?
-        attrs[primitive.key] = resolve_entries(primitive, entries, component_instance)
-      end
-      attrs[:stimulus_values_from_props] = @values_from_props.dup unless @values_from_props.empty?
-      attrs
-    end
-
-    def to_hash(component_instance) = to_attributes(component_instance)
-    alias_method :to_h, :to_hash
-
-    protected
-
-    def entries_for(name) = @entries[name]
-
-    def values_from_props_list = @values_from_props
-
-    private
-
-    # Outlets don't support procs — static merge only. The other keyed kinds
-    # and the positional (Array-shaped) kinds resolve procs in the component
-    # instance and drop nil results.
-    def resolve_entries(primitive, entries, component_instance)
-      return entries.dup if primitive.name == :outlets
-
-      if primitive.keyed?
-        resolve_hash_filtering_nil(entries, component_instance)
-      else
-        resolve_array_filtering_nil(entries, component_instance)
-      end
-    end
-
-    def resolve_array_filtering_nil(array, component_instance)
-      array.each_with_object([]) do |value, out|
-        resolved = callable?(value) ? component_instance.instance_exec(&value) : value
-        out << resolved unless resolved.nil?
-      end
-    end
-
-    # Dropping nil matters because Stimulus's Boolean value parser reads an
-    # empty data attribute as `true` — so `-> { flag? || nil }` would silently
-    # flip a Boolean value on. Omitting the entry keeps the attribute off.
-    def resolve_hash_filtering_nil(hash, component_instance)
-      hash.each_with_object({}) do |(key, value), out|
-        resolved = callable?(value) ? component_instance.instance_exec(&value) : value
-        out[key] = resolved unless resolved.nil?
-      end
-    end
-
-    def callable?(value) = value.respond_to?(:call)
-  end
-end

data/lib/vident/stimulus_class.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusClass < StimulusAttributeBase
-    attr_reader :controller, :class_name, :css_classes
-
-    def to_s = @css_classes.join(" ")
-
-    def data_attribute_name = "#{@controller}-#{@class_name}-class"
-
-    def data_attribute_value = to_s
-
-    private
-
-    def parse_arguments(*args)
-      case args.size
-      when 2
-        parse_two_arguments(args[0], args[1])
-      when 3
-        parse_three_arguments(args[0], args[1], args[2])
-      else
-        raise ArgumentError, "Invalid number of arguments: #{args.size}"
-      end
-    end
-
-    def parse_two_arguments(class_name, css_classes)
-      if class_name.is_a?(Symbol)
-        # class name on implied controller + css classes
-        @controller = implied_controller_name
-        @class_name = class_name.to_s.dasherize
-        @css_classes = normalize_css_classes(css_classes)
-      else
-        raise ArgumentError, "Invalid argument types: #{class_name.class}, #{css_classes.class}"
-      end
-    end
-
-    def parse_three_arguments(controller, class_name, css_classes)
-      if controller.is_a?(String) && class_name.is_a?(Symbol)
-        # controller + class name + css classes
-        @controller = stimulize_path(controller)
-        @class_name = class_name.to_s.dasherize
-        @css_classes = normalize_css_classes(css_classes)
-      else
-        raise ArgumentError, "Invalid argument types: #{controller.class}, #{class_name.class}, #{css_classes.class}"
-      end
-    end
-
-    def normalize_css_classes(css_classes)
-      case css_classes
-      when String
-        css_classes.split(/\s+/).reject(&:empty?)
-      when Array
-        css_classes.map(&:to_s).reject(&:empty?)
-      else
-        raise ArgumentError, "CSS classes must be a String or Array, got #{css_classes.class}"
-      end
-    end
-  end
-end

data/lib/vident/stimulus_class_collection.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusClassCollection < StimulusCollectionBase
-    def to_h
-      return {} if items.empty?
-
-      items.each_with_object({}) { |css_class, merged| merged.merge!(css_class.to_h) }
-    end
-  end
-end

data/lib/vident/stimulus_collection_base.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusCollectionBase
-    def initialize(items = [])
-      @items = Array(items).flatten.compact
-    end
-
-    def <<(item)
-      @items << item
-      self
-    end
-
-    def to_h
-      raise NoMethodError, "Subclasses must implement to_h"
-    end
-
-    def to_a = @items.dup
-
-    def to_hash = to_h
-
-    def empty? = @items.empty?
-
-    def any? = !empty?
-
-    def merge(*other_collections)
-      merged = self.class.new
-      merged.instance_variable_set(:@items, @items.dup)
-
-      other_collections.each do |collection|
-        next unless collection.is_a?(self.class)
-        merged.instance_variable_get(:@items).concat(collection.instance_variable_get(:@items))
-      end
-
-      merged
-    end
-
-    def self.merge(*collections)
-      return new if collections.empty?
-
-      first_collection = collections.first
-      return first_collection if collections.size == 1
-
-      first_collection.merge(*collections[1..-1])
-    end
-
-    protected
-
-    attr_reader :items
-  end
-end

data/lib/vident/stimulus_component.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module StimulusComponent
-    extend ActiveSupport::Concern
-
-    include StimulusAttributes
-
-    # Thin back-compat alias; see `Vident::StimulusAttributeBase.stimulize_path`
-    # for the canonical implementation.
-    def stimulus_identifier_from_path(path)
-      StimulusAttributeBase.stimulize_path(path)
-    end
-    module_function :stimulus_identifier_from_path
-
-    # Base class for all Vident components, which provides common functionality and properties.
-
-    class_methods do
-      def no_stimulus_controller
-        @no_stimulus_controller = true
-      end
-
-      def stimulus_controller? = !@no_stimulus_controller
-
-      # The "path" of the Stimulus controller, which is used to generate the controller name.
-      def stimulus_identifier_path = name&.underscore || "anonymous_component"
-
-      # Stimulus controller identifier
-      def stimulus_identifier = StimulusComponent.stimulus_identifier_from_path(stimulus_identifier_path)
-
-      # The "name" of the component from its class name and namespace. This is used to generate an HTML class name
-      # that can helps identify the component type in the DOM or for styling purposes.
-      def component_name
-        @component_name ||= stimulus_identifier
-      end
-    end
-
-    # Components have the following properties
-    included do
-      extend Literal::Properties
-
-      # StimulusJS support
-      # # TODO: revisit inputs and how many ways of specifying the same thing...
-      prop :stimulus_controllers, _Array(_Union(String, Symbol, StimulusController, StimulusControllerCollection)), default: -> do
-        if self.class.stimulus_controller?
-          [default_controller_path]
-        else
-          []
-        end
-      end
-      prop :stimulus_actions, _Array(_Union(String, Symbol, Array, Hash, StimulusAction, StimulusAction::Descriptor, StimulusActionCollection)), default: -> { [] }
-      prop :stimulus_targets, _Array(_Union(String, Symbol, Array, Hash, StimulusTarget, StimulusTargetCollection)), default: -> { [] }
-      prop :stimulus_outlets, _Array(_Union(String, Symbol, StimulusOutlet, StimulusOutletCollection)), default: -> { [] }
-      prop :stimulus_outlet_host, _Nilable(Vident::Component) # A component that will host this component as an outlet
-      prop :stimulus_values, _Union(_Hash(Symbol, _Any), Array, StimulusValue, StimulusValueCollection), default: -> { {} } # TODO: instead of _Any, is it _Interface(:to_s)?
-      prop :stimulus_params, _Union(_Hash(Symbol, _Any), Array, StimulusParam, StimulusParamCollection), default: -> { {} }
-      prop :stimulus_classes, _Union(_Hash(Symbol, String), Array, StimulusClass, StimulusClassCollection), default: -> { {} }
-    end
-
-    # If connecting an outlet to this specific component instance, use this ID
-    def outlet_id
-      @outlet_id ||= [stimulus_identifier, "##{id}"]
-    end
-
-    # The Stimulus controller identifier for this component
-    def stimulus_identifier = self.class.stimulus_identifier
-
-    # An name that can helps identify the component type in the DOM or for styling purposes (its also used as a class name on the root element)
-    def component_name = self.class.component_name
-
-    # The `component` class name is used to create the controller name.
-    # The path of the Stimulus controller when none is explicitly set
-    def default_controller_path = self.class.stimulus_identifier_path
-  end
-end

data/lib/vident/stimulus_controller.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusController < StimulusAttributeBase
-    attr_reader :path, :name
-
-    def to_s = name
-
-    def data_attribute_name = "controller"
-
-    def data_attribute_value = name
-
-    private
-
-    # `@implied_controller` on this class is a raw path String (not a
-    # StimulusController instance as on the base), so the base class's
-    # `.path` / `.name` accessors don't apply and we override.
-    def implied_controller_path
-      raise ArgumentError, "implied_controller is required to get implied controller path" unless @implied_controller
-      @implied_controller
-    end
-
-    def implied_controller_name
-      raise ArgumentError, "implied_controller is required to get implied controller name" unless @implied_controller
-      stimulize_path(@implied_controller)
-    end
-
-    def parse_arguments(*args)
-      case args.size
-      when 0
-        @path = implied_controller_path
-        @name = implied_controller_name
-      when 1
-        @path = args[0].to_s
-        @name = stimulize_path(@path)
-      else
-        raise ArgumentError, "Invalid number of arguments: #{args.size}. Expected 0 or 1 argument."
-      end
-    end
-  end
-end

data/lib/vident/stimulus_controller_collection.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusControllerCollection < StimulusCollectionBase
-    def to_h
-      return {} if items.empty?
-
-      controller_values = items.map(&:to_s).reject(&:empty?)
-      return {} if controller_values.empty?
-
-      {controller: controller_values.join(" ")}
-    end
-  end
-end

data/lib/vident/stimulus_data_attribute_builder.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusDataAttributeBuilder
-    def initialize(**collections_by_name)
-      unknown = collections_by_name.keys - Stimulus.names
-      raise ArgumentError, "Unknown stimulus primitive(s) #{unknown.inspect}" if unknown.any?
-
-      @collections_by_name = collections_by_name.transform_values { |v| Array(v) }
-    end
-
-    def build
-      Stimulus::PRIMITIVES.each_with_object({}) do |primitive, attrs|
-        attrs.merge!(merge_collection(primitive.collection_class, @collections_by_name[primitive.name] || []))
-      end.transform_keys(&:to_s).compact
-    end
-
-    private
-
-    # Items are either pre-built collections (DSL / resolver path) or raw value
-    # objects (child_element path). Merge-or-wrap accordingly.
-    def merge_collection(collection_class, items)
-      return {} if items.empty?
-
-      if items.first.is_a?(collection_class)
-        collection_class.merge(*items).to_h
-      else
-        collection_class.new(items).to_h
-      end
-    end
-  end
-end

data/lib/vident/stimulus_helper.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module StimulusHelper
-    extend ActiveSupport::Concern
-
-    class_methods do
-      def stimulus(&block)
-        # Initialize stimulus builder if not already present
-        if @stimulus_builder.nil?
-          @stimulus_builder = StimulusBuilder.new
-          @inheritance_merged = false
-        end
-
-        # Ensure inheritance is applied
-        ensure_inheritance_merged
-
-        # Execute the new block to add/merge new attributes
-        @stimulus_builder.instance_eval(&block)
-      end
-
-      def stimulus_dsl_attributes(component_instance)
-        # If no stimulus blocks have been defined on this class, check parent
-        if @stimulus_builder.nil? && superclass.respond_to?(:stimulus_dsl_attributes)
-          return superclass.stimulus_dsl_attributes(component_instance)
-        end
-
-        # Ensure inheritance is applied at access time
-        ensure_inheritance_merged
-
-        @stimulus_builder&.to_attributes(component_instance) || {}
-      end
-
-      private
-
-      def ensure_inheritance_merged
-        return if @inheritance_merged || @stimulus_builder.nil?
-
-        if superclass.respond_to?(:stimulus_dsl_builder, true)
-          parent_builder = superclass.send(:stimulus_dsl_builder)
-          if parent_builder
-            @stimulus_builder.merge_with(parent_builder)
-          end
-        end
-        @inheritance_merged = true
-      end
-
-      protected
-
-      def stimulus_dsl_builder = @stimulus_builder
-    end
-
-    # Instance method to get DSL attributes for this component instance
-    def stimulus_dsl_attributes = self.class.stimulus_dsl_attributes(self)
-
-    # Instance method to resolve prop-mapped values at runtime
-    def resolve_values_from_props(prop_names)
-      return {} if prop_names.empty?
-
-      prop_names.each_with_object({}) do |name, resolved|
-        # Map from instance variable if it exists
-        resolved[name] = instance_variable_get("@#{name}") if instance_variable_defined?("@#{name}")
-      end
-    end
-  end
-end

data/lib/vident/stimulus_outlet.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusOutlet < StimulusAttributeBase
-    attr_reader :controller, :outlet_name, :selector
-
-    def initialize(*args, implied_controller:, component_id: nil)
-      @component_id = component_id
-      super(*args, implied_controller: implied_controller)
-    end
-
-    def to_s = @selector
-
-    def data_attribute_name = "#{@controller}-#{@outlet_name}-outlet"
-
-    def data_attribute_value = @selector
-
-    private
-
-    def parse_arguments(*args)
-      case args.size
-      when 1
-        parse_single_argument(args[0])
-      when 2
-        parse_two_arguments(args[0], args[1])
-      when 3
-        parse_three_arguments(args[0], args[1], args[2])
-      else
-        raise ArgumentError, "Invalid number of arguments: #{args.size}"
-      end
-    end
-
-    def parse_single_argument(arg)
-      @controller = implied_controller_name
-      if arg.is_a?(Symbol)
-        # Single symbol: outlet name on implied controller with auto-generated selector
-        outlet_identifier = arg.to_s.dasherize
-        @outlet_name = outlet_identifier
-        @selector = build_outlet_selector(outlet_identifier)
-      elsif arg.is_a?(String)
-        # Single string: outlet identifier with auto-generated selector
-        @outlet_name = arg.dasherize
-        @selector = build_outlet_selector(arg)
-      elsif arg.is_a?(Array) && arg.size == 2
-        # Array format: [outlet_identifier, css_selector]
-        @outlet_name = arg[0].to_s.dasherize
-        @selector = arg[1]
-      elsif arg.respond_to?(:stimulus_identifier)
-        # Component with stimulus_identifier
-        identifier = arg.stimulus_identifier
-        @outlet_name = identifier
-        @selector = build_outlet_selector(identifier)
-      elsif arg.respond_to?(:implied_controller_name)
-        # RootComponent with implied_controller_name
-        identifier = arg.implied_controller_name
-        @outlet_name = identifier
-        @selector = build_outlet_selector(identifier)
-      else
-        raise ArgumentError, "Invalid argument type: #{arg.class}"
-      end
-    end
-
-    def parse_two_arguments(arg1, arg2)
-      if (arg1.is_a?(Symbol) || arg1.is_a?(String)) && arg2.is_a?(String)
-        @controller = implied_controller_name
-        @outlet_name = arg1.to_s.dasherize
-        @selector = arg2
-      else
-        raise ArgumentError, "Invalid argument types: #{arg1.class}, #{arg2.class}"
-      end
-    end
-
-    def parse_three_arguments(controller, outlet_name, selector)
-      if controller.is_a?(String) && outlet_name.is_a?(Symbol) && selector.is_a?(String)
-        # controller path + outlet name + selector
-        @controller = stimulize_path(controller)
-        @outlet_name = outlet_name.to_s.dasherize
-        @selector = selector
-      else
-        raise ArgumentError, "Invalid argument types: #{controller.class}, #{outlet_name.class}, #{selector.class}"
-      end
-    end
-
-    # Build outlet selector following the same pattern as RootComponent
-    def build_outlet_selector(outlet_selector)
-      prefix = @component_id ? "##{@component_id} " : ""
-      "#{prefix}[data-controller~=#{outlet_selector}]"
-    end
-  end
-end

data/lib/vident/stimulus_outlet_collection.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusOutletCollection < StimulusCollectionBase
-    def to_h
-      return {} if items.empty?
-
-      items.each_with_object({}) { |outlet, merged| merged.merge!(outlet.to_h) }
-    end
-  end
-end

data/lib/vident/stimulus_param.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  # `data-<controller>-<name>-param="..."` — readable on the JS side as
-  # `event.params.<camelName>`. Element-scoped: every action on the element
-  # sees the same params.
-  class StimulusParam < StimulusAttributeBase
-    attr_reader :controller, :param_name, :value
-
-    def to_s = @value.to_s
-
-    def data_attribute_name = "#{@controller}-#{@param_name}-param"
-
-    def data_attribute_value = @value
-
-    private
-
-    def parse_arguments(*args)
-      case args.size
-      when 2 then parse_two_arguments(*args)
-      when 3 then parse_three_arguments(*args)
-      else raise ArgumentError, "Invalid number of arguments: #{args.size} (#{args.inspect}). Did you pass an array of hashes?"
-      end
-    end
-
-    def parse_two_arguments(param_name, value)
-      raise ArgumentError, "Invalid argument types: #{param_name.class}, #{value.class}" unless param_name.is_a?(Symbol)
-      @controller = implied_controller_name
-      @param_name = param_name.to_s.dasherize
-      @value = serialize_value(value)
-    end
-
-    def parse_three_arguments(controller, param_name, value)
-      unless controller.is_a?(String) && param_name.is_a?(Symbol)
-        raise ArgumentError, "Invalid argument types: #{controller.class}, #{param_name.class}, #{value.class}"
-      end
-      @controller = stimulize_path(controller)
-      @param_name = param_name.to_s.dasherize
-      @value = serialize_value(value)
-    end
-  end
-end

data/lib/vident/stimulus_param_collection.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusParamCollection < StimulusCollectionBase
-    def to_h
-      return {} if items.empty?
-
-      items.each_with_object({}) { |param, merged| merged.merge!(param.to_h) }
-    end
-  end
-end

data/lib/vident/stimulus_target.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusTarget < StimulusAttributeBase
-    attr_reader :controller, :name
-
-    def to_s = @name
-
-    # Returns the data attribute name for this target
-    def data_attribute_name = "#{@controller}-target"
-
-    # Returns the target name value for the data attribute
-    def data_attribute_value = @name
-
-    private
-
-    def parse_arguments(*args)
-      case args.size
-      when 1
-        parse_single_argument(args[0])
-      when 2
-        parse_two_arguments(args[0], args[1])
-      else
-        raise ArgumentError, "Invalid number of arguments: #{args.size}"
-      end
-    end
-
-    def parse_single_argument(arg)
-      @controller = implied_controller_name
-      @name = case arg
-      when Symbol then js_name(arg)  # name of target on implied controller
-      when String then arg           # target name on implied controller
-      else raise ArgumentError, "Invalid argument type: #{arg.class}"
-      end
-    end
-
-    def parse_two_arguments(part1, part2)
-      if part1.is_a?(String) && part2.is_a?(Symbol)
-        # 1 string arg, 1 symbol = controller + target
-        @controller = stimulize_path(part1)
-        @name = js_name(part2)
-      else
-        raise ArgumentError, "Invalid argument types: #{part1.class}, #{part2.class}"
-      end
-    end
-  end
-end