vident 0.13.1 → 1.0.0.alpha2

data/lib/vident/stimulus_attributes.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Vident
+  module StimulusAttributes
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Class methods for generating scoped event names. Returns a symbol
+      # so that the action parser will see it as a Stimulus event.
+      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
+    end
+
+    # Parse inputs to create a StimulusController instance representing a Stimulus controller attribute
+    #   examples:
+    #   stimulus_controller("my_controller") => StimulusController that converts to {"controller" => "my-controller"}
+    #   stimulus_controller("path/to/controller") => StimulusController that converts to {"controller" => "path--to--controller"}
+    #   stimulus_controller() => StimulusController that uses implied controller name
+    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
+
+    # Parse inputs to create a StimulusControllerCollection instance representing multiple Stimulus controllers
+    #   examples:
+    #   stimulus_controllers(:my_controller) => StimulusControllerCollection with one controller that converts to {"controller" => "my-controller"}
+    #   stimulus_controllers(:my_controller, "path/to/another") => StimulusControllerCollection with two controllers that converts to {"controller" => "my-controller path--to--another"}
+    def stimulus_controllers(*controllers)
+      return StimulusControllerCollection.new if controllers.empty? || controllers.all?(&:blank?)
+
+      converted_controllers = controllers.map do |controller|
+        controller.is_a?(Array) ? stimulus_controller(*controller) : stimulus_controller(controller)
+      end
+      StimulusControllerCollection.new(converted_controllers)
+    end
+
+    # Parse inputs to create a StimulusAction instance representing a Stimulus action attribute
+    #   examples:
+    #   stimulus_action(:my_thing) => StimulusAction that converts to "current_controller#myThing"
+    #   stimulus_action(:click, :my_thing) => StimulusAction that converts to "click->current_controller#myThing"
+    #   stimulus_action("click->current_controller#myThing") => StimulusAction that converts to "click->current_controller#myThing"
+    #   stimulus_action("path/to/current", :my_thing) => StimulusAction that converts to "path--to--current_controller#myThing"
+    #   stimulus_action(:click, "path/to/current", :my_thing) => StimulusAction that converts to "click->path--to--current_controller#myThing"
+    def stimulus_action(*args)
+      return args.first if args.length == 1 && args.first.is_a?(StimulusAction)
+      StimulusAction.new(*args, implied_controller:)
+    end
+
+    # Parse inputs to create a StimulusActionCollection instance representing multiple Stimulus actions
+    def stimulus_actions(*actions)
+      return StimulusActionCollection.new if actions.empty? || actions.all?(&:blank?)
+
+      converted_actions = actions.map do |action|
+        action.is_a?(Array) ? stimulus_action(*action) : stimulus_action(action)
+      end
+      StimulusActionCollection.new(converted_actions)
+    end
+
+    # Parse inputs to create a StimulusTarget instance representing a Stimulus target attribute
+    #   examples:
+    #   stimulus_target(:my_target) => StimulusTarget that converts to {"current_controller-target" => "myTarget"}
+    #   stimulus_target("path/to/current", :my_target) => StimulusTarget that converts to {"path--to--current-target" => "myTarget"}
+    def stimulus_target(*args)
+      return args.first if args.length == 1 && args.first.is_a?(StimulusTarget)
+      StimulusTarget.new(*args, implied_controller:)
+    end
+
+    # Parse inputs to create a StimulusTargetCollection instance representing multiple Stimulus targets
+    def stimulus_targets(*targets)
+      return StimulusTargetCollection.new if targets.empty? || targets.all?(&:blank?)
+
+      converted_targets = targets.map do |target|
+        target.is_a?(Array) ? stimulus_target(*target) : stimulus_target(target)
+      end
+      StimulusTargetCollection.new(converted_targets)
+    end
+
+    # Parse inputs to create a StimulusOutlet instance representing a Stimulus outlet attribute
+    #   examples:
+    #   stimulus_outlet(:user_status, ".online-user") => StimulusOutlet that converts to {"current_controller-user-status-outlet" => ".online-user"}
+    #   stimulus_outlet("path/to/current", :user_status, ".online-user") => StimulusOutlet that converts to {"path--to--current-user-status-outlet" => ".online-user"}
+    #   stimulus_outlet(:user_status) => StimulusOutlet with auto-generated selector
+    #   stimulus_outlet(component_instance) => StimulusOutlet from component
+    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
+
+    # Parse inputs to create a StimulusOutletCollection instance representing multiple Stimulus outlets
+    def stimulus_outlets(*outlets)
+      return StimulusOutletCollection.new if outlets.empty? || outlets.all?(&:blank?)
+
+      converted_outlets = []
+      outlets.each do |outlet|
+        if outlet.is_a?(Hash)
+          # Hash format: {name: selector, other_name: other_selector} - expands to multiple outlets
+          outlet.each { |name, selector| converted_outlets << stimulus_outlet(name, selector) }
+        elsif outlet.is_a?(Array)
+          # Array format: [name, selector] - splat into stimulus_outlet
+          converted_outlets << stimulus_outlet(*outlet)
+        else
+          converted_outlets << stimulus_outlet(outlet)
+        end
+      end
+      StimulusOutletCollection.new(converted_outlets)
+    end
+
+    # Parse inputs to create a StimulusValue instance representing a Stimulus value attribute
+    #   examples:
+    #   stimulus_value(:url, "https://example.com") => StimulusValue that converts to {"current_controller-url-value" => "https://example.com"}
+    #   stimulus_value("path/to/current", :url, "https://example.com") => StimulusValue that converts to {"path--to--current-url-value" => "https://example.com"}
+    def stimulus_value(*args)
+      return args.first if args.length == 1 && args.first.is_a?(StimulusValue)
+      StimulusValue.new(*args, implied_controller:)
+    end
+
+    # Parse inputs to create a StimulusValueCollection instance representing multiple Stimulus values
+    def stimulus_values(*values)
+      return StimulusValueCollection.new if values.empty? || values.all?(&:blank?)
+
+      converted_values = []
+
+      values.each do |value|
+        if value.is_a?(Hash)
+          # Hash format: {name: value, other_name: other_value} - expands to multiple values
+          value.each { |name, val| converted_values << stimulus_value(name, val) }
+        elsif value.is_a?(Array)
+          # Array format: [controller, name, value] or [name, value] - splat into stimulus_value
+          converted_values << stimulus_value(*value)
+        else
+          converted_values << stimulus_value(value)
+        end
+      end
+
+      StimulusValueCollection.new(converted_values)
+    end
+
+    # Parse inputs to create a StimulusClass instance representing a Stimulus class attribute
+    #   examples:
+    #   stimulus_class(:loading, "spinner active") => StimulusClass that converts to {"current_controller-loading-class" => "spinner active"}
+    #   stimulus_class("path/to/current", :loading, ["spinner", "active"]) => StimulusClass that converts to {"path--to--current-loading-class" => "spinner active"}
+    def stimulus_class(*args)
+      return args.first if args.length == 1 && args.first.is_a?(StimulusClass)
+      StimulusClass.new(*args, implied_controller:)
+    end
+
+    # Parse inputs to create a StimulusClassCollection instance representing multiple Stimulus classes
+    def stimulus_classes(*classes)
+      return StimulusClassCollection.new if classes.empty? || classes.all?(&:blank?)
+
+      converted_classes = []
+
+      classes.each do |cls|
+        if cls.is_a?(Hash)
+          # Hash format: {loading: "spinner active", error: "text-red-500"} - expands to multiple classes
+          cls.each { |name, class_list| converted_classes << stimulus_class(name, class_list) }
+        elsif cls.is_a?(Array)
+          # Array format: [controller, name, classes] or [name, classes] - splat into stimulus_class
+          converted_classes << stimulus_class(*cls)
+        else
+          converted_classes << stimulus_class(cls)
+        end
+      end
+
+      StimulusClassCollection.new(converted_classes)
+    end
+
+    # Methods to add to the stimulus collections
+
+    def add_stimulus_controllers(controllers)
+      s_controllers = stimulus_controllers(*Array.wrap(controllers))
+      @stimulus_controllers_collection = if @stimulus_controllers_collection
+        @stimulus_controllers_collection.merge(s_controllers)
+      else
+        s_controllers
+      end
+    end
+
+    def add_stimulus_actions(actions)
+      s_actions = stimulus_actions(*Array.wrap(actions))
+      @stimulus_actions_collection = if @stimulus_actions_collection
+        @stimulus_actions_collection.merge(s_actions)
+      else
+        s_actions
+      end
+    end
+
+    def add_stimulus_targets(targets)
+      s_targets = stimulus_targets(*Array.wrap(targets))
+      @stimulus_targets_collection = if @stimulus_targets_collection
+        @stimulus_targets_collection.merge(s_targets)
+      else
+        s_targets
+      end
+    end
+
+    def add_stimulus_outlets(outlets)
+      s_outlets = stimulus_outlets(*Array.wrap(outlets))
+      @stimulus_outlets_collection = if @stimulus_outlets_collection
+        @stimulus_outlets_collection.merge(s_outlets)
+      else
+        s_outlets
+      end
+    end
+
+    def add_stimulus_values(values)
+      s_values = stimulus_values(values)
+      @stimulus_values_collection = if @stimulus_values_collection
+        @stimulus_values_collection.merge(s_values)
+      else
+        s_values
+      end
+    end
+
+    def add_stimulus_classes(named_classes)
+      classes = stimulus_classes(named_classes)
+      @stimulus_classes_collection = if @stimulus_classes_collection
+        @stimulus_classes_collection.merge(classes)
+      else
+        classes
+      end
+    end
+
+    # Stimulus events name for this component
+    def stimulus_scoped_event(event)
+      self.class.stimulus_scoped_event(event)
+    end
+
+    def stimulus_scoped_event_on_window(event)
+      self.class.stimulus_scoped_event_on_window(event)
+    end
+
+    private
+
+    def implied_controller
+      StimulusController.new(implied_controller: implied_controller_path)
+    end
+
+    # When using the DSL if you dont specify, the first controller is implied
+    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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Vident
+  class StimulusBuilder
+    def initialize
+      @actions = []
+      @targets = []
+      @values = {}
+      @values_from_props = []
+      @classes = {}
+      @outlets = {}
+    end
+
+    def merge_with(other_builder)
+      @actions.concat(other_builder.actions_list)
+      @targets.concat(other_builder.targets_list)
+      @values.merge!(other_builder.values_hash)
+      @values_from_props.concat(other_builder.values_from_props_list)
+      @classes.merge!(other_builder.classes_hash)
+      @outlets.merge!(other_builder.outlets_hash)
+      self
+    end
+
+    def actions(*action_names)
+      @actions.concat(action_names)
+      self
+    end
+
+    def targets(*target_names)
+      @targets.concat(target_names)
+      self
+    end
+
+    def values(**value_hash)
+      @values.merge!(value_hash) unless value_hash.empty?
+      self
+    end
+
+    def values_from_props(*prop_names)
+      @values_from_props.concat(prop_names)
+      self
+    end
+
+    def classes(**class_mappings)
+      @classes.merge!(class_mappings)
+      self
+    end
+
+    def outlets(**outlet_mappings)
+      @outlets.merge!(outlet_mappings) unless outlet_mappings.empty?
+      self
+    end
+
+    def to_attributes(component_instance)
+      attrs = {}
+      attrs[:stimulus_actions] = resolve_attributes_filtering_nil(@actions, component_instance) unless @actions.empty?
+      attrs[:stimulus_targets] = resolve_attributes_filtering_nil(@targets, component_instance) unless @targets.empty?
+      attrs[:stimulus_values] = resolve_hash_values_allowing_nil(@values, component_instance) unless @values.empty?
+      attrs[:stimulus_values_from_props] = @values_from_props.dup unless @values_from_props.empty?
+      attrs[:stimulus_classes] = resolve_hash_classes_filtering_nil(@classes, component_instance) unless @classes.empty?
+      attrs[:stimulus_outlets] = @outlets.dup unless @outlets.empty?
+      attrs
+    end
+
+    def to_hash(component_instance)
+      to_attributes(component_instance)
+    end
+    alias_method :to_h, :to_hash
+
+    protected
+
+    def actions_list
+      @actions
+    end
+
+    def targets_list
+      @targets
+    end
+
+    def values_hash
+      @values
+    end
+
+    def values_from_props_list
+      @values_from_props
+    end
+
+    def classes_hash
+      @classes
+    end
+
+    def outlets_hash
+      @outlets
+    end
+
+    private
+
+    # For actions, targets - filter out nil values from procs AND static
+    def resolve_attributes_filtering_nil(array, component_instance)
+      result = []
+      array.each do |value|
+        if callable?(value)
+          resolved_value = component_instance.instance_exec(&value)
+          # Exclude nil from procs (nil is not valid for actions/targets)
+          result << resolved_value unless resolved_value.nil?
+        else
+          # Exclude static nil values (nil is not valid for actions/targets)
+          result << value unless value.nil?
+        end
+      end
+      result
+    end
+
+    # For values - allow nil values from procs and static (will become "null" in JavaScript)
+    def resolve_hash_values_allowing_nil(hash, component_instance)
+      hash.transform_values { |value| callable?(value) ? component_instance.instance_exec(&value) : value }
+    end
+
+    # For classes - filter out nil values from procs AND static
+    def resolve_hash_classes_filtering_nil(hash, component_instance)
+      result = {}
+      hash.each do |key, value|
+        if callable?(value)
+          resolved_value = component_instance.instance_exec(&value)
+          # Exclude nil from procs (nil is not valid for classes)
+          result[key] = resolved_value unless resolved_value.nil?
+        else
+          # Exclude static nil values (nil is not valid for classes)
+          result[key] = value unless value.nil?
+        end
+      end
+      result
+    end
+
+    def callable?(value)
+      value.respond_to?(:call)
+    end
+  end
+end

data/lib/vident/stimulus_class.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Vident
+  class StimulusClass < StimulusAttributeBase
+    attr_reader :controller, :class_name, :css_classes
+
+    def to_s
+      @css_classes.join(" ")
+    end
+
+    def data_attribute_name
+      "#{@controller}-#{@class_name}-class"
+    end
+
+    def data_attribute_value
+      to_s
+    end
+
+    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

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

data/lib/vident/stimulus_collection_base.rb

@@ -0,0 +1,59 @@
+# 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
+    end
+
+    def to_hash
+      to_h
+    end
+
+    def empty?
+      @items.empty?
+    end
+
+    def any?
+      !empty?
+    end
+
+    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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vident
+  module StimulusComponent
+    extend ActiveSupport::Concern
+
+    include StimulusAttributes
+
+    # Module utilities for working with Stimulus identifiers
+
+    def stimulus_identifier_from_path(path)
+      path.split("/").map { |p| p.to_s.dasherize }.join("--")
+    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 = ::Vident::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, StimulusActionCollection)), default: -> { [] }
+      prop :stimulus_targets, _Array(_Union(String, Symbol, 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), StimulusValue, StimulusValueCollection), default: -> { {} } # TODO: instead of _Any, is it _Interface(:to_s)?
+      prop :stimulus_classes, _Union(_Hash(Symbol, String), 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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Vident
+  class StimulusController < StimulusAttributeBase
+    attr_reader :path, :name
+
+    def to_s
+      name
+    end
+
+    def data_attribute_name
+      "controller"
+    end
+
+    def data_attribute_value
+      name
+    end
+
+    private
+
+    def implied_controller_path
+      @implied_controller
+    end
+
+    def implied_controller_name
+      stimulize_path(@implied_controller)
+    end
+
+    def parse_arguments(*args)
+      case args.size
+      when 0
+        # No arguments: use implied controller path
+        @path = implied_controller_path
+        @name = implied_controller_name
+      when 1
+        # Single argument: controller path
+        @path = args[0]
+        @name = stimulize_path(args[0])
+      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

@@ -0,0 +1,14 @@
+# 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