vident 1.0.1 → 2.0.0

data/lib/vident/class_list_builder.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-require "set"
-
-module Vident
-  class ClassListBuilder
-    CLASSNAME_SEPARATOR = " "
-
-    # If the HTML "class" option is provided, it is taken in order of precedence of source.
-    # The order of precedence is:
-    # lowest  | root_element_classes => whatever is returned
-    # ....... | root_element_attributes => the `html_options[:class]` value
-    # ....... | root_element(class: ...) => the `class` value of the arguments passed to the root element
-    # highest | render MyComponent.new(html_options: { class: ... }) => the `html_options[:class]` value
-    # The "classes" prop on the component on the other hand is used to add additional classes to the component.
-    # eg: render MyComponent.new(classes: "my-additional-class another-class")
-    def initialize(tailwind_merger: nil, component_name: nil, root_element_attributes_classes: nil, root_element_classes: nil, root_element_html_class: nil, html_class: nil, additional_classes: nil)
-      @class_list = component_name ? [component_name] : []
-      @class_list.concat(Array.wrap(root_element_classes)) if root_element_classes && !root_element_attributes_classes && !root_element_html_class && !html_class
-      @class_list.concat(Array.wrap(root_element_attributes_classes)) if root_element_attributes_classes && !root_element_html_class && !html_class
-      @class_list.concat(Array.wrap(root_element_html_class)) if root_element_html_class && !html_class
-      @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_attribute_resolver.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module ComponentAttributeResolver
-    include Stimulus::Naming
-
-    private
-
-    # Prepare attributes set at initialization, which will later be merged together before rendering.
-    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)
-      @root_element_attributes_classes = extra[:classes]
-      @root_element_attributes_id = extra[:id] || id
-      @element_tag = extra[:element_tag] if extra.key?(:element_tag)
-
-      Stimulus::PRIMITIVES.each do |primitive|
-        send(mutator_method(primitive), extra[primitive.key]) if extra.key?(primitive.key)
-      end
-    end
-
-    def resolve_root_element_attributes_before_render(root_element_html_options = nil)
-      extra = root_element_html_options || {}
-
-      # Options set on component at render time take precedence over attributes set by methods on the component
-      # or attributes passed to root_element in the template
-      final_attributes = {
-        data: stimulus_data_attributes  # Lowest precedence
-      }
-      if root_element_html_options.present? # Mid precedence
-        root_element_tag_html_options_merge(final_attributes, root_element_html_options)
-      end
-      if @html_options.present? # Highest precedence
-        root_element_tag_html_options_merge(final_attributes, @html_options)
-      end
-      final_attributes[:class] = render_classes(extra[:class])
-      final_attributes[:id] = (extra[:id] || @root_element_attributes_id) unless final_attributes.key?(:id)
-      final_attributes
-    end
-
-    def root_element_tag_html_options_merge(final_attributes, other_html_options)
-      if other_html_options[:data].present?
-        final_attributes[:data].merge!(other_html_options[:data])
-      end
-      final_attributes.merge!(other_html_options.except(:data))
-    end
-
-    # Run every DSL attribute through its `add_stimulus_*` mutator. `values_from_props`
-    # is a sidecar on values, resolved at instance render time.
-    def add_stimulus_attributes_from_dsl
-      dsl_attrs = self.class.stimulus_dsl_attributes(self)
-      return if dsl_attrs.empty?
-
-      Stimulus::PRIMITIVES.each do |primitive|
-        value = dsl_attrs[primitive.key]
-        send(mutator_method(primitive), value) if value
-      end
-
-      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
-    end
-
-    # Seed the collection ivars from each prop's raw value.
-    def prepare_stimulus_collections
-      Stimulus::PRIMITIVES.each do |primitive|
-        raw = instance_variable_get(prop_ivar(primitive))
-        collection = send(primitive.key, *Array.wrap(raw))
-        instance_variable_set(collection_ivar(primitive), collection)
-      end
-
-      @stimulus_outlet_host.add_stimulus_outlets(self) if @stimulus_outlet_host
-    end
-
-    def stimulus_data_attributes
-      collections = Stimulus::PRIMITIVES.to_h { |primitive| [primitive.name, instance_variable_get(collection_ivar(primitive))] }
-      StimulusDataAttributeBuilder.new(**collections).build
-    end
-  end
-end

data/lib/vident/component_class_lists.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module ComponentClassLists
-    # Generates the full list of HTML classes for the component
-    def render_classes(root_element_html_class = nil) = class_list_builder(root_element_html_class).build
-
-    # 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)
-      ClassListBuilder.new(tailwind_merger:).build(
-        @stimulus_classes_collection&.to_a,
-        stimulus_class_names: names
-      ) || ""
-    end
-
-    private
-
-    # Not memoised: the per-thread TailwindMerger is the only expensive piece
-    # and it's already cached; the builder itself just copies a few ivars.
-    # Memoising here would latch the first caller's `root_element_html_class:`.
-    def class_list_builder(root_element_html_class = nil)
-      ClassListBuilder.new(
-        tailwind_merger:,
-        component_name:,
-        root_element_attributes_classes: @root_element_attributes_classes,
-        root_element_classes:,
-        root_element_html_class:,
-        additional_classes: @classes,
-        html_class: @html_options&.fetch(:class, nil)
-      )
-    end
-  end
-end

data/lib/vident/stimulus/primitive.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module Stimulus
-    # A Stimulus primitive kind: name, plus the Value/Collection classes that
-    # back it. Two concrete subclasses distinguish how the primitive behaves
-    # when a Hash is passed to the plural parser:
-    #
-    #   - `Keyed`      — `{a: 1, b: 2}` expands to one value object per pair.
-    #                    Used for values / params / classes / outlets.
-    #   - `Positional` — `{...}` is a single-arg descriptor (e.g. Action's
-    #                    `{event:, method:, ...}` short form).
-    #                    Used for controllers / actions / targets.
-    class Primitive < ::Data.define(:name, :value_class, :collection_class)
-      # Short forms. `name` (Data field) is the plural — `:values`; `plural`
-      # is an alias for symmetry with `singular`.
-      alias_method :plural, :name
-      def singular = name.to_s.singularize.to_sym
-
-      # The primitive's key in Vident's attribute namespace. Used both as the
-      # parser method name (`def stimulus_values(...)`) and as the hash key
-      # in DSL attrs / component props / `root_element_attributes` — the same
-      # Symbol serves all three roles.
-      def key = :"stimulus_#{name}"
-      def singular_key = :"stimulus_#{singular}"
-
-      def keyed? = raise NotImplementedError
-    end
-
-    class KeyedPrimitive < Primitive
-      def keyed? = true
-    end
-
-    class PositionalPrimitive < Primitive
-      def keyed? = false
-    end
-  end
-end

data/lib/vident/stimulus.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  module Stimulus
-    # Registry of primitive kinds. Add an entry (paired with a Value/Collection
-    # class pair) to extend; plural parsers, mutators, and the data-attribute
-    # builder pick it up. Array order = data attribute emission order.
-    PRIMITIVES = [
-      PositionalPrimitive.new(:controllers, StimulusController, StimulusControllerCollection),
-      PositionalPrimitive.new(:actions, StimulusAction, StimulusActionCollection),
-      PositionalPrimitive.new(:targets, StimulusTarget, StimulusTargetCollection),
-      KeyedPrimitive.new(:outlets, StimulusOutlet, StimulusOutletCollection),
-      KeyedPrimitive.new(:values, StimulusValue, StimulusValueCollection),
-      KeyedPrimitive.new(:params, StimulusParam, StimulusParamCollection),
-      KeyedPrimitive.new(:classes, StimulusClass, StimulusClassCollection)
-    ].freeze
-
-    PRIMITIVES_BY_NAME = PRIMITIVES.to_h { |primitive| [primitive.name, primitive] }.freeze
-
-    class << self
-      def primitive(name)
-        PRIMITIVES_BY_NAME[name] or
-          raise ArgumentError, "Unknown stimulus primitive #{name.inspect}; valid: #{PRIMITIVES_BY_NAME.keys.inspect}"
-      end
-
-      def each(&block) = PRIMITIVES.each(&block)
-
-      def names = PRIMITIVES.map(&:name)
-    end
-  end
-end

data/lib/vident/stimulus_action.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-
-module Vident
-  class StimulusAction < StimulusAttributeBase
-    # https://stimulus.hotwired.dev/reference/actions#options
-    VALID_OPTIONS = [:once, :prevent, :stop, :passive, :"!passive", :capture, :self].freeze
-
-    # Typed descriptor for modifiers (`:once`/`:prevent`/etc., keyboard filter,
-    # `@window`) that the plain Array form can't express. Hash input to the
-    # parsers (`{event:, method:, ...}`) is desugared into one of these.
-    class Descriptor < ::Literal::Data
-      prop :method, _Union(Symbol, String)
-      prop :event, _Nilable(_Union(Symbol, String)), default: nil
-      prop :controller, _Nilable(String), default: nil
-      prop :options, _Array(Symbol), default: -> { [] }
-      prop :keyboard, _Nilable(String), default: nil
-      prop :window, _Boolean, default: false
-    end
-
-    attr_reader :event, :controller, :action, :options, :keyboard, :window
-
-    def initialize(*args, implied_controller: nil)
-      @options = []
-      @keyboard = nil
-      @window = false
-      super
-    end
-
-    def to_s
-      head =
-        if @event
-          ev = @event.to_s
-          ev = "#{ev}.#{@keyboard}" if @keyboard
-          ev = "#{ev}#{@options.map { |o| ":#{o}" }.join}" if @options.any?
-          ev = "#{ev}@window" if @window
-          "#{ev}->"
-        else
-          ""
-        end
-      "#{head}#{@controller}##{@action}"
-    end
-
-    def data_attribute_name = "action"
-
-    def data_attribute_value = to_s
-
-    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)
-      case arg
-      when Descriptor then apply_descriptor(arg)
-      when Hash then apply_descriptor(Descriptor.new(**arg))
-      when Symbol
-        @event = nil
-        @controller = implied_controller_name
-        @action = js_name(arg)
-      when String then parse_qualified_action_string(arg)
-      else raise ArgumentError, "Invalid 'action' argument type (1): #{arg.class}"
-      end
-    end
-
-    # (:event, :method) or ("controller/path", :method)
-    def parse_two_arguments(part1, part2)
-      if part1.is_a?(Symbol) && part2.is_a?(Symbol)
-        @event = part1.to_s
-        @controller = implied_controller_name
-        @action = js_name(part2)
-      elsif part1.is_a?(String) && part2.is_a?(Symbol)
-        @event = nil
-        @controller = stimulize_path(part1)
-        @action = js_name(part2)
-      else
-        raise ArgumentError, "Invalid 'action' argument types (2): #{part1.class}, #{part2.class}"
-      end
-    end
-
-    # (:event, "controller/path", :method)
-    def parse_three_arguments(part1, part2, part3)
-      if part1.is_a?(Symbol) && part2.is_a?(String) && part3.is_a?(Symbol)
-        @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 apply_descriptor(d)
-      invalid = d.options - VALID_OPTIONS
-      unless invalid.empty?
-        raise ArgumentError,
-          "Invalid action option(s) #{invalid.inspect}. Valid: #{VALID_OPTIONS.inspect}"
-      end
-
-      @event = d.event&.to_s
-      @controller = d.controller ? stimulize_path(d.controller) : implied_controller_name
-      @action = d.method.is_a?(Symbol) ? js_name(d.method) : d.method.to_s
-      @options = d.options
-      @keyboard = d.keyboard
-      @window = d.window
-    end
-
-    def parse_qualified_action_string(action_string)
-      if action_string.include?("->")
-        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
-        @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

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

@@ -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