vident 0.13.0 → 1.0.0.alpha1

data/lib/vident/caching.rb

@@ -15,7 +15,7 @@ module Vident
       def with_cache_key(*attrs, name: :_collection)
         # Add view file to cache key
         attrs << :component_modified_time
-        attrs << :attributes
+        attrs << :to_h if respond_to?(:to_h)
         named_cache_key_includes(name, *attrs.uniq)
       end
 
@@ -46,11 +46,11 @@ module Vident
       def component_modified_time
         return @component_modified_time if Rails.env.production? && @component_modified_time
 
-        raise StandardError, "Must implement current_component_modified_time" unless respond_to?(:current_component_modified_time)
+        raise StandardError, "Must implement cache_component_modified_time" unless respond_to?(:cache_component_modified_time)
 
         # FIXME: This could stack overflow if there are circular dependencies
         deps = component_dependencies&.map(&:component_modified_time)&.join("-") || ""
-        @component_modified_time = deps + current_component_modified_time
+        @component_modified_time = deps + cache_component_modified_time
       end
 
       private

data/lib/vident/class_list_builder.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vident
+  class ClassListBuilder
+    CLASSNAME_SEPARATOR = " "
+
+    def initialize(tailwind_merger: nil, component_name: nil, element_classes: nil, html_class: nil, additional_classes: nil)
+      @class_list = component_name ? [component_name] : []
+      @class_list.concat(Array.wrap(element_classes)) if element_classes
+      @class_list.concat(Array.wrap(html_class)) if html_class
+      @class_list.concat(Array.wrap(additional_classes)) if additional_classes
+      @class_list.compact!
+      @tailwind_merger = tailwind_merger
+
+      if @tailwind_merger && !defined?(::TailwindMerge::Merger)
+        raise LoadError, "TailwindMerge gem is required when using tailwind_merger:. Add 'gem \"tailwind_merge\"' to your Gemfile."
+      end
+    end
+
+    # Main method to build a final class list from multiple sources
+    # @param class_lists [Array<String, Array, StimulusClass, nil>] Multiple class sources to merge
+    # @param stimulus_class_names [Array<Symbol, String>] Optional names of stimulus classes to include
+    # @return [String, nil] Final space-separated class string or nil if no classes
+    def build(extra_classes = nil, stimulus_class_names: [])
+      class_list = @class_list + Array.wrap(extra_classes).compact
+      flattened_classes = flatten_and_normalize_classes(class_list, stimulus_class_names)
+      return nil if flattened_classes.empty?
+
+      deduplicated_classes = dedupe_classes(flattened_classes)
+      return nil if deduplicated_classes.blank?
+
+      class_string = deduplicated_classes.join(CLASSNAME_SEPARATOR)
+
+      if @tailwind_merger
+        dedupe_with_tailwind(class_string)
+      else
+        class_string
+      end
+    end
+
+    private
+
+    # Flatten and normalize all input class sources
+    def flatten_and_normalize_classes(class_lists, stimulus_class_names)
+      stimulus_class_names_set = stimulus_class_names.map { |name| name.to_s.dasherize }.to_set
+
+      class_lists.compact.flat_map do |class_source|
+        case class_source
+        when String
+          class_source.split(CLASSNAME_SEPARATOR).reject(&:empty?)
+        when Array
+          class_source.flat_map { |item| normalize_single_class_item(item, stimulus_class_names_set) }
+        else
+          normalize_single_class_item(class_source, stimulus_class_names_set)
+        end
+      end.compact
+    end
+
+    # Normalize a single class item (could be string, StimulusClass, object with to_s, etc.)
+    def normalize_single_class_item(item, stimulus_class_names_set)
+      return [] if item.blank?
+
+      # Handle StimulusClass instances
+      if stimulus_class_instance?(item)
+        # Only include if the class name matches one of the requested names
+        # If stimulus_class_names_set is empty, exclude all stimulus classes
+        if stimulus_class_names_set.present? && stimulus_class_names_set.include?(item.class_name)
+          class_value = item.to_s
+          class_value.include?(CLASSNAME_SEPARATOR) ?
+            class_value.split(CLASSNAME_SEPARATOR).reject(&:empty?) :
+            [class_value]
+        else
+          []
+        end
+      else
+        # Handle regular strings and other objects
+        item_string = item.to_s
+        item_string.include?(CLASSNAME_SEPARATOR) ?
+          item_string.split(CLASSNAME_SEPARATOR).reject(&:empty?) :
+          [item_string]
+      end
+    end
+
+    # Check if an item is a StimulusClass instance
+    def stimulus_class_instance?(item)
+      item.respond_to?(:class_name) && item.respond_to?(:to_s)
+    end
+
+    # Deduplicate classes while preserving order (first occurrence wins)
+    def dedupe_classes(class_array)
+      class_array.reject(&:blank?).uniq
+    end
+
+    # Merge classes using Tailwind CSS merge
+    def dedupe_with_tailwind(class_string)
+      @tailwind_merger.merge(class_string)
+    end
+  end
+end

data/lib/vident/component.rb

@@ -4,29 +4,83 @@ module Vident
   module Component
     extend ActiveSupport::Concern
 
+    # Base class for all Vident components, which provides common functionality and properties.
     included do
-      include Vident::Base
-      include Vident::Attributes::NotTyped
-
-      attribute :id, delegates: false
-      attribute :html_options, delegates: false
-      attribute :element_tag, delegates: false
-
-      # StimulusJS support
-      attribute :controllers, default: [], delegates: false
-      attribute :actions, default: [], delegates: false
-      attribute :targets, default: [], delegates: false
-      attribute :outlets, default: [], delegates: false
-      attribute :outlet_host, delegates: false
-      attribute :values, default: [], delegates: false
-      attribute :named_classes, delegates: false
-    end
-
-    def initialize(attrs = {})
-      before_initialise(attrs)
-      prepare_attributes(attrs)
-      after_initialise
-      super()
+      # The HTML tag to use for the root element of the component, defaults to `:div`.
+      prop :element_tag, Symbol, default: :div
+      # ID of the component. If not set, a random ID is generated.
+      prop :id, _Nilable(String)
+      # Classes to apply to the root element (they add to the `class` attribute)
+      prop :classes, _Union(String, _Array(String)), default: -> { [] }
+      # HTML options to apply to the root element (will merge into and potentially override html_options of the element)
+      prop :html_options, Hash, default: -> { {} }
+    end
+
+    include StimulusComponent
+    include ComponentClassLists
+    include ComponentAttributeResolver
+
+    include TagHelper
+    include Tailwind
+    include StimulusDSL
+
+    # Override this method to perform any initialisation after attributes are set
+    def after_component_initialize
+    end
+
+    # This can be overridden to return an array of extra class names, or a string of class names.
+    def element_classes
+    end
+
+    # Properties/attributes passed to the "root" element of the component. You normally override this method to
+    # return a hash of attributes that should be applied to the root element of your component.
+    def root_element_attributes
+      {}
+    end
+
+    # Create a new component instance with optional overrides for properties.
+    def clone(overrides = {}) = self.class.new(**to_h.merge(**overrides))
+
+    def inspect(klass_name = "Component")
+      attr_text = to_h.map { |k, v| "#{k}=#{v.inspect}" }.join(", ")
+      "#<#{self.class.name}<Vident::#{klass_name}> #{attr_text}>"
+    end
+
+    # Generate a unique ID for a component, can be overridden as required. Makes it easier to setup things like ARIA
+    # attributes which require elements to reference by ID. Note this overrides the `id` accessor
+    def id = @id.presence || random_id
+
+    private
+
+    # Called by Literal::Properties after the component is initialized.
+    def after_initialize
+      prepare_component_attributes
+      after_component_initialize if respond_to?(:after_component_initialize)
+    end
+
+    def root_element(&block)
+      raise NoMethodError, "You must implement the `root_element` method in your component"
+    end
+
+    def root(...)
+      root_element(...)
+    end
+
+    def root_element_tag_options
+      options = @html_options&.dup || {}
+      data_attrs = stimulus_data_attributes
+      options[:data] = options[:data].present? ? data_attrs.merge(options[:data]) : data_attrs
+      return options unless @id
+      options.merge(id: @id)
+    end
+
+    def root_element_tag_type
+      @element_tag.presence&.to_sym || :div
+    end
+
+    # Generate a random ID for the component, which is used to ensure uniqueness in the DOM.
+    def random_id
+      @random_id ||= "#{component_name}-#{StableId.next_id_in_sequence}"
     end
   end
 end

data/lib/vident/component_attribute_resolver.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Vident
+  module ComponentAttributeResolver
+    private
+
+    # FIXME: in a view_component the parsing of html_options might have to be in `before_render`
+    def prepare_component_attributes
+      prepare_stimulus_collections
+
+      # Add stimulus attributes from DSL first (lower precedence)
+      add_stimulus_attributes_from_dsl
+
+      # Process root_element_attributes (higher precedence) 
+      extra = root_element_attributes
+      @html_options = (extra[:html_options] || {}).merge(@html_options) if extra.key?(:html_options)
+      @html_options[:class] = render_classes(extra[:classes])
+      @html_options[:id] = (extra[:id] || id) unless @html_options.key?(:id)
+      @element_tag = extra[:element_tag] if extra.key?(:element_tag)
+
+      add_stimulus_controllers(extra[:stimulus_controllers]) if extra.key?(:stimulus_controllers)
+      add_stimulus_actions(extra[:stimulus_actions]) if extra.key?(:stimulus_actions)
+      add_stimulus_targets(extra[:stimulus_targets]) if extra.key?(:stimulus_targets)
+      add_stimulus_outlets(extra[:stimulus_outlets]) if extra.key?(:stimulus_outlets)
+      add_stimulus_values(extra[:stimulus_values]) if extra.key?(:stimulus_values)
+      add_stimulus_classes(extra[:stimulus_classes]) if extra.key?(:stimulus_classes)
+    end
+
+    # Add stimulus attributes from DSL declarations using existing add_* methods
+    def add_stimulus_attributes_from_dsl
+      dsl_attrs = self.class.stimulus_dsl_attributes(self)
+      return if dsl_attrs.empty?
+
+      # Use existing add_* methods to integrate DSL attributes
+      add_stimulus_controllers(dsl_attrs[:stimulus_controllers]) if dsl_attrs[:stimulus_controllers]
+      add_stimulus_actions(dsl_attrs[:stimulus_actions]) if dsl_attrs[:stimulus_actions]
+      add_stimulus_targets(dsl_attrs[:stimulus_targets]) if dsl_attrs[:stimulus_targets]
+      add_stimulus_outlets(dsl_attrs[:stimulus_outlets]) if dsl_attrs[:stimulus_outlets]
+      
+      # Add static values (now includes resolved proc values)
+      add_stimulus_values(dsl_attrs[:stimulus_values]) if dsl_attrs[:stimulus_values]
+      
+      # Resolve and add values from props
+      if dsl_attrs[:stimulus_values_from_props]
+        resolved_values = resolve_values_from_props(dsl_attrs[:stimulus_values_from_props])
+        add_stimulus_values(resolved_values) unless resolved_values.empty?
+      end
+      
+      add_stimulus_classes(dsl_attrs[:stimulus_classes]) if dsl_attrs[:stimulus_classes]
+    end
+
+
+    # Prepare stimulus collections and implied controller path from the given attributes, called after initialization
+    def prepare_stimulus_collections # Convert raw attributes to stimulus attribute collections
+      @stimulus_controllers_collection = stimulus_controllers(*Array.wrap(@stimulus_controllers))
+      @stimulus_actions_collection = stimulus_actions(*Array.wrap(@stimulus_actions))
+      @stimulus_targets_collection = stimulus_targets(*Array.wrap(@stimulus_targets))
+      @stimulus_outlets_collection = stimulus_outlets(*Array.wrap(@stimulus_outlets))
+      @stimulus_values_collection = stimulus_values(*Array.wrap(@stimulus_values))
+      @stimulus_classes_collection = stimulus_classes(*Array.wrap(@stimulus_classes))
+
+      @stimulus_outlet_host.add_stimulus_outlets(self) if @stimulus_outlet_host
+    end
+
+    # Build stimulus data attributes using collection splat
+    def stimulus_data_attributes
+      StimulusDataAttributeBuilder.new(
+        controllers: @stimulus_controllers_collection,
+        actions: @stimulus_actions_collection,
+        targets: @stimulus_targets_collection,
+        outlets: @stimulus_outlets_collection,
+        values: @stimulus_values_collection,
+        classes: @stimulus_classes_collection
+      ).build
+    end
+  end
+end

data/lib/vident/component_class_lists.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Vident
+  module ComponentClassLists
+    # Generates the full list of HTML classes for the component
+    def render_classes(extra_classes = nil) = class_list_builder.build(extra_classes)
+
+    # Getter for a stimulus classes list so can be used in view to set initial state on SSR
+    # Returns a String of classes that can be used in a `class` attribute.
+    def class_list_for_stimulus_classes(*names)
+      class_list_builder.build(@stimulus_classes_collection&.to_a, stimulus_class_names: names) || ""
+    end
+
+    private
+
+    # Get or create a class list builder instance
+    # Automatically detects if Tailwind module is included and TailwindMerge gem is available
+    def class_list_builder
+      @class_list_builder ||= ClassListBuilder.new(
+        tailwind_merger:,
+        component_name:,
+        element_classes:,
+        additional_classes: @classes,
+        html_class: @html_options&.fetch(:class, nil)
+      )
+    end
+  end
+end

data/lib/vident/stimulus_action.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Vident
+  class StimulusAction < StimulusAttributeBase
+    attr_reader :event, :controller, :action
+
+    def to_s
+      if @event
+        "#{@event}->#{@controller}##{@action}"
+      else
+        "#{@controller}##{@action}"
+      end
+    end
+
+    def data_attribute_name
+      "action"
+    end
+
+    def data_attribute_value
+      to_s
+    end
+
+    private
+
+    def parse_arguments(*args)
+      part1, part2, part3 = args
+
+      case args.size
+      when 1
+        parse_single_argument(part1)
+      when 2
+        parse_two_arguments(part1, part2)
+      when 3
+        parse_three_arguments(part1, part2, part3)
+      else
+        raise ArgumentError, "Invalid number of 'action' arguments: #{args.size}"
+      end
+    end
+
+    def parse_single_argument(arg)
+      if arg.is_a?(Symbol)
+        # 1 symbol arg, name of method on implied controller
+        @event = nil
+        @controller = implied_controller_name
+        @action = js_name(arg)
+      elsif arg.is_a?(String)
+        # 1 string arg, fully qualified action - parse it
+        parse_qualified_action_string(arg)
+      else
+        raise ArgumentError, "Invalid 'action' argument types (1): #{arg.class}"
+      end
+    end
+
+    def parse_two_arguments(part1, part2)
+      if part1.is_a?(Symbol) && part2.is_a?(Symbol)
+        # 2 symbol args = event + action
+        @event = part1.to_s
+        @controller = implied_controller_name
+        @action = js_name(part2)
+      elsif part1.is_a?(String) && part2.is_a?(Symbol)
+        # 1 string arg, 1 symbol = controller + action
+        @event = nil
+        @controller = stimulize_path(part1)
+        @action = js_name(part2)
+      else
+        raise ArgumentError, "Invalid 'action' argument types (2): #{part1.class}, #{part2.class}"
+      end
+    end
+
+    def parse_three_arguments(part1, part2, part3)
+      if part1.is_a?(Symbol) && part2.is_a?(String) && part3.is_a?(Symbol)
+        # 1 symbol, 1 string, 1 symbol = event + controller + action
+        @event = part1.to_s
+        @controller = stimulize_path(part2)
+        @action = js_name(part3)
+      else
+        raise ArgumentError, "Invalid 'action' argument types (3): #{part1.class}, #{part2.class}, #{part3.class}"
+      end
+    end
+
+    def parse_qualified_action_string(action_string)
+      if action_string.include?("->")
+        # Has event: "click->controller#action"
+        event_part, controller_action = action_string.split("->", 2)
+        @event = event_part
+        controller_part, action_part = controller_action.split("#", 2)
+        @controller = controller_part
+        @action = action_part
+      else
+        # No event: "controller#action"
+        @event = nil
+        controller_part, action_part = action_string.split("#", 2)
+        @controller = controller_part
+        @action = action_part
+      end
+    end
+  end
+end

data/lib/vident/stimulus_action_collection.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Vident
+  class StimulusActionCollection < StimulusCollectionBase
+    def to_h
+      return {} if items.empty?
+
+      {action: items.map(&:to_s).join(" ")}
+    end
+  end
+end

data/lib/vident/stimulus_attribute_base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Vident
+  class StimulusAttributeBase
+    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}>"
+    end
+
+    def to_s
+      raise NoMethodError, "Subclasses must implement to_s"
+    end
+
+    def to_h
+      {data_attribute_name => data_attribute_value}
+    end
+
+    alias_method :to_hash, :to_h
+
+    def data_attribute_name
+      raise NoMethodError, "Subclasses must implement data_attribute_name"
+    end
+
+    def data_attribute_value
+      raise NoMethodError, "Subclasses must implement data_attribute_value"
+    end
+
+    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
+
+    # Convert a file path to a stimulus controller name
+    def stimulize_path(path)
+      path.split("/").map { |p| p.to_s.dasherize }.join("--")
+    end
+
+    # Convert a Ruby 'snake case' string to a JavaScript camel case strings
+    def js_name(name)
+      name.to_s.camelize(:lower)
+    end
+
+    # Subclasses must implement this method
+    def parse_arguments(*args)
+      raise NotImplementedError, "Subclasses must implement parse_arguments"
+    end
+  end
+end