vident 1.0.2 → 2.0.1

data/lib/vident/stimulus_attribute_base.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/core_ext/string/inflections"
-
-require "json"
-
-module Vident
-  class StimulusAttributeBase
-    # `"admin/users"` → `"admin--users"`; accepts Symbol or String.
-    def self.stimulize_path(path)
-      path.to_s.split("/").map(&:dasherize).join("--")
-    end
-
-    # `:my_thing` → `"myThing"`
-    def self.js_name(name)
-      name.to_s.camelize(:lower)
-    end
-
-    attr_reader :implied_controller
-
-    def initialize(*args, implied_controller: nil)
-      @implied_controller = implied_controller
-      parse_arguments(*args)
-    end
-
-    def inspect = "#<#{self.class.name} #{to_h}>"
-
-    def to_s = raise(NoMethodError, "Subclasses must implement to_s")
-
-    def to_h = {data_attribute_name => data_attribute_value}
-
-    alias_method :to_hash, :to_h
-
-    def data_attribute_name = raise(NoMethodError, "Subclasses must implement data_attribute_name")
-
-    def data_attribute_value = raise(NoMethodError, "Subclasses must implement data_attribute_value")
-
-    def implied_controller_path
-      raise ArgumentError, "implied_controller is required to get implied controller path" unless implied_controller
-      implied_controller.path
-    end
-
-    def implied_controller_name
-      raise ArgumentError, "implied_controller is required to get implied controller name" unless implied_controller
-      implied_controller.name
-    end
-
-    private
-
-    def stimulize_path(path) = self.class.stimulize_path(path)
-
-    def js_name(name) = self.class.js_name(name)
-
-    # Arrays/Hashes serialise as JSON; everything else via `to_s` (which is how
-    # `Vident::StimulusNull` emits the literal `"null"`).
-    def serialize_value(value)
-      case value
-      when Array, Hash then value.to_json
-      else value.to_s
-      end
-    end
-
-    def parse_arguments(*args)
-      raise NotImplementedError, "Subclasses must implement parse_arguments"
-    end
-  end
-end

data/lib/vident/stimulus_attributes.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module StimulusAttributes
-    extend ActiveSupport::Concern
-    # `extend` + `include` so Naming helpers are callable both in the module
-    # body (outside define_method args) and inside define_method blocks
-    # (at instance call-time).
-    extend Stimulus::Naming
-    include Stimulus::Naming
-
-    class_methods do
-      # Symbol so the action parser treats it as a Stimulus event type.
-      def stimulus_scoped_event(event)
-        :"#{component_name}:#{stimulus_js_name(event)}"
-      end
-
-      def stimulus_scoped_event_on_window(event)
-        :"#{component_name}:#{stimulus_js_name(event)}@window"
-      end
-
-      private
-
-      def stimulus_js_name(name) = name.to_s.camelize(:lower)
-    end
-
-    def stimulus_controller(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusController)
-      StimulusController.new(*args, implied_controller: implied_controller_path)
-    end
-
-    # Plural parsers `stimulus_<kind>s(*args)` — generated from the primitives
-    # registry below. Each accepts: pre-built Value (pass-through), pre-built
-    # Collection (unwrapped; a single one is returned as-is), Array (splatted
-    # into the singular builder), Hash (expanded per-pair for
-    # `hash_expands: true`, single-arg descriptor otherwise), else passed to
-    # the singular builder. Methods defined this way: `stimulus_controllers`,
-    # `stimulus_actions`, `stimulus_targets`, `stimulus_outlets`,
-    # `stimulus_values`, `stimulus_params`, `stimulus_classes`.
-    Stimulus::PRIMITIVES.each do |primitive|
-      define_method(primitive.key) do |*args|
-        collection_class = primitive.collection_class
-        return collection_class.new if args.empty? || args.all?(&:blank?)
-        return args.first if args.length == 1 && args.first.is_a?(collection_class)
-
-        singular = primitive.singular_key
-        converted = []
-        args.each do |arg|
-          case arg
-          when primitive.value_class then converted << arg
-          when collection_class then converted.concat(arg.to_a)
-          when Hash
-            if primitive.keyed?
-              arg.each { |name, val| converted << send(singular, name, val) }
-            else
-              converted << send(singular, arg)
-            end
-          when Array then converted << send(singular, *arg)
-          else converted << send(singular, arg)
-          end
-        end
-        collection_class.new(converted)
-      end
-    end
-
-    def stimulus_action(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusAction)
-      StimulusAction.new(*args, implied_controller:)
-    end
-
-    def stimulus_target(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusTarget)
-      StimulusTarget.new(*args, implied_controller:)
-    end
-
-    # `component_id: @id` scopes the auto-generated selector to this component
-    # instance (e.g. `#<host-id> [data-controller~=<outlet>]`).
-    def stimulus_outlet(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusOutlet)
-      StimulusOutlet.new(*args, implied_controller:, component_id: @id)
-    end
-
-    def stimulus_value(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusValue)
-      StimulusValue.new(*args, implied_controller:)
-    end
-
-    def stimulus_param(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusParam)
-      StimulusParam.new(*args, implied_controller:)
-    end
-
-    def stimulus_class(*args)
-      return args.first if args.length == 1 && args.first.is_a?(StimulusClass)
-      StimulusClass.new(*args, implied_controller:)
-    end
-
-    # Mutators `add_stimulus_<kind>s` — build from input, merge into the
-    # per-kind collection ivar. Methods defined: `add_stimulus_controllers`,
-    # `add_stimulus_actions`, `add_stimulus_targets`, `add_stimulus_outlets`,
-    # `add_stimulus_values`, `add_stimulus_params`, `add_stimulus_classes`.
-    Stimulus::PRIMITIVES.each do |primitive|
-      define_method(mutator_method(primitive)) do |input|
-        added = send(primitive.key, *Array.wrap(input))
-        existing = instance_variable_get(collection_ivar(primitive))
-        instance_variable_set(collection_ivar(primitive), existing ? existing.merge(added) : added)
-      end
-    end
-
-    def stimulus_scoped_event(event) = self.class.stimulus_scoped_event(event)
-
-    def stimulus_scoped_event_on_window(event) = self.class.stimulus_scoped_event_on_window(event)
-
-    private
-
-    def implied_controller
-      StimulusController.new(implied_controller: implied_controller_path)
-    end
-
-    # The first registered controller path becomes the implied controller for
-    # unqualified DSL entries (e.g. `actions :click` → `implied#click`).
-    def implied_controller_path
-      return @implied_controller_path if defined?(@implied_controller_path)
-      path = Array.wrap(@stimulus_controllers).first
-      raise(StandardError, "No controllers have been specified") unless path
-      @implied_controller_path = path
-    end
-  end
-end

data/lib/vident/stimulus_builder.rb

@@ -1,136 +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
-
-    # `phase:` controls which entries are resolved.
-    # - `:static` — resolve non-proc entries only; procs are skipped entirely
-    #   (no placeholder). Used at init time, before helpers/view_context exist.
-    # - `:procs` — resolve proc entries only; non-procs are skipped. Used at
-    #   render time so procs can reach `helpers` / `view_context`.
-    # - `:all` — resolve everything (legacy path, retained for safety).
-    def to_attributes(component_instance, phase: :all)
-      attrs = {}
-      DSL_PRIMITIVES.each do |primitive|
-        entries = @entries[primitive.name]
-        next if entries.empty?
-        resolved = resolve_entries(primitive, entries, component_instance, phase:)
-        attrs[primitive.key] = resolved unless resolved.nil? || resolved.empty?
-      end
-      if phase != :procs && !@values_from_props.empty?
-        attrs[:stimulus_values_from_props] = @values_from_props.dup
-      end
-      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, phase:)
-      if primitive.name == :outlets
-        return (phase == :procs) ? {} : entries.dup
-      end
-
-      if primitive.keyed?
-        resolve_hash_filtering_nil(entries, component_instance, phase:)
-      else
-        resolve_array_filtering_nil(entries, component_instance, phase:)
-      end
-    end
-
-    def resolve_array_filtering_nil(array, component_instance, phase:)
-      array.each_with_object([]) do |value, out|
-        is_proc = callable?(value)
-        next if phase == :static && is_proc
-        next if phase == :procs && !is_proc
-        resolved = is_proc ? 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, phase:)
-      hash.each_with_object({}) do |(key, value), out|
-        is_proc = callable?(value)
-        next if phase == :static && is_proc
-        next if phase == :procs && !is_proc
-        resolved = is_proc ? 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, phase: :all)
-        # 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, phase:)
-        end
-
-        # Ensure inheritance is applied at access time
-        ensure_inheritance_merged
-
-        @stimulus_builder&.to_attributes(component_instance, phase:) || {}
-      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(phase: :all) = self.class.stimulus_dsl_attributes(self, phase:)
-
-    # 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