vident 1.0.2 → 2.0.1

data/lib/vident/capabilities/root_element_rendering.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Vident
+  module Capabilities
+    module RootElementRendering
+      def root_element_attributes = {}
+
+      def root_element_classes
+        nil
+      end
+
+      def root_element(**overrides, &block)
+        raise NoMethodError, "subclass must implement root_element"
+      end
+
+      # Dispatches to the adapter-specific `root_element` on subclasses
+      # (Phlex / ViewComponent). Keep as `def` not `alias_method` so Ruby's
+      # dynamic dispatch finds the subclass override.
+      def root(...)
+        root_element(...)
+      end
+
+      private
+
+      def root_element_tag_type
+        tag = resolved_root_element_attributes[:element_tag] || @element_tag
+        tag.presence&.to_sym || :div
+      end
+    end
+  end
+end

data/lib/vident/capabilities/stimulus_data_emitting.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "../internals/attribute_writer"
+require_relative "../internals/class_list_builder"
+
+module Vident
+  module Capabilities
+    module StimulusDataEmitting
+      # For components rendering the root via a third-party helper instead of
+      # `root_element(...)`. `extra_classes` lands at the lowest-priority tier
+      # so it cannot be clobbered by a cascade winner.
+      def root_element_class_list(extra_classes = nil)
+        extra = resolved_root_element_attributes
+        extra_html_options = extra[:html_options] || {}
+        combined_classes = [@classes, extra_classes].flatten.compact
+        result = ::Vident::Internals::ClassListBuilder.call(
+          component_name: component_name,
+          root_element_classes: root_element_classes,
+          root_element_attributes_classes: extra[:classes],
+          html_options_class: @html_options[:class] || extra_html_options[:class],
+          classes_prop: combined_classes.empty? ? nil : combined_classes,
+          tailwind_merger: tailwind_merger
+        )
+        result || ""
+      end
+
+      # Seals the Draft on first call (idempotent). Symbol keys.
+      def root_element_data_attributes
+        plan = seal_draft
+        data_attrs = ::Vident::Internals::AttributeWriter.call(plan)
+
+        extra = resolved_root_element_attributes
+        extra_data = (extra[:html_options] || {})[:data] || {}
+
+        merged = data_attrs.dup
+        merged.merge!(symbolize_keys(extra_data))
+        merged.merge!(symbolize_keys(@html_options[:data] || {}))
+        merged
+      end
+
+      private
+
+      def resolved_root_element_attributes
+        return @__vident_rea if defined?(@__vident_rea)
+        value = root_element_attributes
+        @__vident_rea = value.is_a?(Hash) ? value : {}
+      end
+
+      def build_root_element_attributes(overrides)
+        plan = seal_draft
+        data_attrs = ::Vident::Internals::AttributeWriter.call(plan)
+
+        extra = resolved_root_element_attributes
+        extra_html_options = extra[:html_options] || {}
+        extra_class = extra[:classes]
+        extra_id = extra[:id]
+        extra_data = extra_html_options[:data] || {}
+
+        # data precedence (low→high): Plan fragments → attrs html_options[:data]
+        # → instance html_options[:data] → overrides[:data].
+        merged_data = data_attrs.dup
+        merged_data.merge!(symbolize_keys(extra_data))
+        merged_data.merge!(symbolize_keys(@html_options[:data] || {}))
+        merged_data.merge!(symbolize_keys(overrides[:data] || {}))
+
+        class_list = ::Vident::Internals::ClassListBuilder.call(
+          component_name: component_name,
+          root_element_classes: root_element_classes,
+          root_element_attributes_classes: extra_class,
+          root_element_html_class: overrides[:class],
+          html_options_class: @html_options[:class] || extra_html_options[:class],
+          classes_prop: @classes,
+          tailwind_merger: tailwind_merger
+        )
+
+        merged = {}
+        merged.merge!(extra_html_options.except(:data, :class))
+        merged.merge!(@html_options.except(:data, :class))
+        merged.merge!(overrides.except(:data, :class))
+        merged[:class] = class_list if class_list
+        merged[:data] = merged_data unless merged_data.empty?
+        merged[:id] ||= extra_id || id
+
+        merged
+      end
+
+      # Intentionally NOT `hash.symbolize_keys` (ActiveSupport): that calls
+      # `to_sym` on every key, including integers, and would raise on keys
+      # that don't respond to `to_sym`. Here we convert only String keys and
+      # leave anything else (Symbols already) untouched — safe for the
+      # user-supplied `data:` hashes that reach this method.
+      def symbolize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+        hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+      end
+    end
+  end
+end

data/lib/vident/capabilities/stimulus_declaring.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../internals/declarations"
+require_relative "../internals/dsl"
+
+module Vident
+  module Capabilities
+    module StimulusDeclaring
+      extend ActiveSupport::Concern
+
+      included do
+        @__vident_declarations = ::Vident::Internals::Declarations.empty
+        @__vident_no_stimulus_controller = false
+      end
+
+      class_methods do
+        def declarations
+          @__vident_declarations ||= ::Vident::Internals::Declarations.empty
+        end
+
+        def no_stimulus_controller
+          if declarations.any?
+            raise ::Vident::DeclarationError,
+              "#{name || "anonymous component"} called `no_stimulus_controller` after " \
+              "`stimulus do` already recorded DSL entries. Declare `no_stimulus_controller` " \
+              "before any `stimulus do` block."
+          end
+          @__vident_no_stimulus_controller = true
+        end
+
+        def has_stimulus_controller
+          @__vident_no_stimulus_controller = false
+        end
+
+        def stimulus_controller?
+          !@__vident_no_stimulus_controller
+        end
+
+        # Second+ calls append (positional) or last-write-wins (keyed).
+        def stimulus(&block)
+          call_site = caller_locations(1, 1)&.first
+          dsl = ::Vident::Internals::DSL.new(caller_location: call_site)
+          dsl.instance_eval(&block) if block
+          fresh = dsl.to_declarations
+
+          if !stimulus_controller? && fresh.any?
+            location = call_site ? " at #{call_site.path}:#{call_site.lineno}" : ""
+            raise ::Vident::DeclarationError,
+              "#{name || "anonymous component"} declared `no_stimulus_controller` but `stimulus do` emitted DSL entries#{location}. " \
+              "A class with no implied controller cannot route DSL entries; drop the `stimulus do` block or remove `no_stimulus_controller`."
+          end
+
+          @__vident_declarations = declarations.merge(fresh).freeze
+        end
+
+        def stimulus_scoped_event(event)
+          :"#{component_name}:#{event.to_s.camelize(:lower)}"
+        end
+
+        def stimulus_scoped_event_on_window(event)
+          :"#{component_name}:#{event.to_s.camelize(:lower)}@window"
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@__vident_declarations, declarations)
+          subclass.instance_variable_set(
+            :@__vident_no_stimulus_controller,
+            instance_variable_get(:@__vident_no_stimulus_controller) || false
+          )
+        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)
+    end
+  end
+end

data/lib/vident/capabilities/stimulus_draft.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../internals/resolver"
+
+module Vident
+  module Capabilities
+    module StimulusDraft
+      def after_component_initialize
+      end
+
+      # Flag set before the guards so a sealed Draft can't trap us in a
+      # loop where every subsequent call re-takes the sealed branch.
+      def resolve_stimulus_attributes_at_render_time
+        return if @__vident_procs_resolved
+        @__vident_procs_resolved = true
+        return if @__vident_draft.nil? || @__vident_draft.sealed?
+        ::Vident::Internals::Resolver.resolve_procs_into(
+          @__vident_draft, self.class.declarations, self
+        )
+      end
+
+      private
+
+      # DSL procs defer to render (`view_context` isn't wired yet at init time).
+      def after_initialize
+        @__vident_draft = ::Vident::Internals::Resolver.call(
+          self.class.declarations, self, phase: :static
+        )
+        @stimulus_outlet_host&.add_stimulus_outlets(self)
+        after_component_initialize
+      end
+
+      def raise_if_sealed!
+        if @__vident_draft.nil?
+          raise ::Vident::StateError,
+            "stimulus Draft is nil — Literal::Data `after_initialize` never fired. " \
+            "If you subclassed and overrode `initialize`, ensure `super` is called. " \
+            "If you instantiated with `allocate`, call `after_initialize` manually."
+        end
+        return unless @__vident_draft.sealed?
+        raise ::Vident::StateError,
+          "cannot modify stimulus attributes after rendering has begun"
+      end
+
+      def seal_draft
+        resolve_stimulus_attributes_at_render_time
+        @__vident_plan ||= @__vident_draft.seal!
+      end
+    end
+  end
+end

data/lib/vident/capabilities/stimulus_mutation.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../internals/registry"
+require_relative "../stimulus/collection"
+
+module Vident
+  module Capabilities
+    module StimulusMutation
+      extend ActiveSupport::Concern
+
+      included do
+        unless ancestors.include?(::Vident::Capabilities::Identifiable)
+          raise ::Vident::DeclarationError,
+            "#{name || "anonymous component"} must include Vident::Capabilities::Identifiable before Vident::Capabilities::StimulusMutation"
+        end
+      end
+
+      ::Vident::Internals::Registry.each do |kind|
+        define_method(:"add_stimulus_#{kind.plural_name}") do |input|
+          raise_if_sealed!
+          values = unwrap_mutator_input(kind, input)
+          values.each { |v| @__vident_draft.public_send(:"add_#{kind.name}", v) if v }
+          self
+        end
+      end
+
+      private
+
+      # Array input is ONE entry — does not splat across multiple entries
+      # (mirrors the DSL's plural→singular forwarding).
+      #
+      # Hash input is only accepted for keyed kinds (values, params, class_maps,
+      # outlets) and Actions. Passing a Hash to a non-keyed, non-Action kind
+      # (controllers, targets) raises ParseError — use a String or Symbol instead.
+      def unwrap_mutator_input(kind, input)
+        case input
+        in nil
+          []
+        in ^(kind.value_class) => v
+          [v]
+        in ::Vident::Stimulus::Collection => coll
+          coll.items
+        in Hash => h if kind.keyed?
+          h.map { |name, raw| kind.value_class.parse(name, raw, implied: implied_controller, component_id: id) }
+        in Hash => h if kind.value_class == ::Vident::Stimulus::Action
+          [kind.value_class.parse(h, implied: implied_controller, component_id: id)]
+        in Hash
+          raise ::Vident::ParseError,
+            "add_stimulus_#{kind.plural_name}: Hash input is not valid for #{kind.plural_name}. " \
+            "Use a String or Symbol instead, e.g. add_stimulus_#{kind.plural_name}(\"name\"). " \
+            "Hash input is only accepted for keyed kinds (values, params, classes, outlets) and actions."
+        in Array => a
+          [kind.value_class.parse(*a, implied: implied_controller, component_id: id)]
+        else
+          [kind.value_class.parse(input, implied: implied_controller, component_id: id)]
+        end
+      end
+    end
+  end
+end

data/lib/vident/capabilities/stimulus_parsing.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "../internals/registry"
+require_relative "../stimulus/collection"
+
+module Vident
+  module Capabilities
+    # Include order: Identifiable must be included before this module
+    # (generated methods call `implied_controller` and `id`).
+    module StimulusParsing
+      extend ActiveSupport::Concern
+
+      included do
+        unless ancestors.include?(::Vident::Capabilities::Identifiable)
+          raise ::Vident::DeclarationError,
+            "#{name || "anonymous component"} must include Vident::Capabilities::Identifiable before Vident::Capabilities::StimulusParsing"
+        end
+      end
+
+      ::Vident::Internals::Registry.each do |kind|
+        define_method(:"stimulus_#{kind.singular_name}") do |*args|
+          return args.first if args.length == 1 && args.first.is_a?(kind.value_class)
+          kind.value_class.parse(*args, implied: implied_controller, component_id: id)
+        end
+
+        define_method(:"stimulus_#{kind.plural_name}") do |*args|
+          return ::Vident::Stimulus::Collection.new(kind: kind, items: []) if args.empty? || args.all?(&:nil?)
+          return args.first if args.length == 1 && args.first.is_a?(::Vident::Stimulus::Collection)
+
+          items = []
+          args.each do |arg|
+            case arg
+            in ^(kind.value_class) => v
+              items << v
+            in ::Vident::Stimulus::Collection => coll
+              items.concat(coll.items)
+            in Hash => h if kind.keyed?
+              h.each { |name, val| items << kind.value_class.parse(name, val, implied: implied_controller, component_id: id) }
+            in Hash => h
+              items << kind.value_class.parse(h, implied: implied_controller, component_id: id)
+            in Array => a
+              items << kind.value_class.parse(*a, implied: implied_controller, component_id: id)
+            else
+              items << kind.value_class.parse(arg, implied: implied_controller, component_id: id)
+            end
+          end
+          ::Vident::Stimulus::Collection.new(kind: kind, items: items)
+        end
+      end
+
+      # Class-level builders reject cross-controller forms (receiver's implied
+      # controller would be silently ignored) — call `Vident::Stimulus::*.parse`
+      # directly for those. `stimulus_outlet` additionally requires an explicit
+      # selector (no component_id to auto-scope).
+      class_methods do
+        def stimulus_controller
+          implied_controller_for_class
+        end
+
+        def stimulus_target(*args)
+          case args
+          in [String => ctrl_path, Symbol]
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_target does not accept cross-controller form at class level. " \
+              "Call Vident::Stimulus::Target.parse(#{ctrl_path.inspect}, ...) directly."
+          else
+            ::Vident::Stimulus::Target.parse(*args, implied: implied_controller_for_class)
+          end
+        end
+
+        def stimulus_action(*args)
+          case args
+          in [String => ctrl_path, Symbol]
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_action does not accept cross-controller form at class level. " \
+              "Call Vident::Stimulus::Action.parse(#{ctrl_path.inspect}, ...) directly."
+          in [Symbol, String, Symbol]
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_action does not accept cross-controller form at class level. " \
+              "Call Vident::Stimulus::Action.parse directly."
+          else
+            ::Vident::Stimulus::Action.parse(*args, implied: implied_controller_for_class)
+          end
+        end
+
+        def stimulus_value(*args)
+          case args
+          in [String, Symbol, *]
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_value does not accept cross-controller form at class level. " \
+              "Call Vident::Stimulus::Value.parse directly."
+          else
+            ::Vident::Stimulus::Value.parse(*args, implied: implied_controller_for_class)
+          end
+        end
+
+        def stimulus_param(*args)
+          case args
+          in [String, Symbol, *]
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_param does not accept cross-controller form at class level. " \
+              "Call Vident::Stimulus::Param.parse directly."
+          else
+            ::Vident::Stimulus::Param.parse(*args, implied: implied_controller_for_class)
+          end
+        end
+
+        def stimulus_class(*args)
+          case args
+          in [String, Symbol, *]
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_class does not accept cross-controller form at class level. " \
+              "Call Vident::Stimulus::ClassMap.parse directly."
+          else
+            ::Vident::Stimulus::ClassMap.parse(*args, implied: implied_controller_for_class)
+          end
+        end
+
+        def stimulus_outlet(*args)
+          case args
+          in [Symbol => _name, String => _selector] | [String => _name, String => _selector]
+            ::Vident::Stimulus::Outlet.parse(*args, implied: implied_controller_for_class)
+          else
+            raise ::Vident::ParseError,
+              "#{name}.stimulus_outlet requires (name, selector) — no component_id at class level. " \
+              "Use instance-level `component.stimulus_outlet(:name)` for auto-selector, " \
+              "or `#{name}.stimulus_outlet(:name, '.selector')` with an explicit selector."
+          end
+        end
+
+        private
+
+        # Memoised on the class's own singleton — Ruby doesn't share
+        # singleton ivars through inheritance, so subclasses get their own.
+        def implied_controller_for_class
+          @__vident_class_implied_controller ||= ::Vident::Stimulus::Controller.new(
+            path: stimulus_identifier_path,
+            name: stimulus_identifier
+          )
+        end
+      end
+    end
+  end
+end

data/lib/vident/capabilities/tailwind.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Vident
+  module Capabilities
+    module Tailwind
+      def tailwind_merger
+        return unless tailwind_merge_available?
+        return @tailwind_merger if defined?(@tailwind_merger)
+
+        @tailwind_merger = Thread.current[:vident_tailwind_merger] ||= ::TailwindMerge::Merger.new
+      end
+
+      def tailwind_merge_available?
+        defined?(::TailwindMerge::Merger) && ::TailwindMerge::Merger.respond_to?(:new)
+      end
+    end
+  end
+end

data/lib/vident/component.rb

@@ -1,84 +1,22 @@
 # frozen_string_literal: true
 
 module Vident
+  # Composition root. Include order mirrors capability dependencies.
+  # Caching is opt-in and NOT included here.
   module Component
     extend ActiveSupport::Concern
 
-    # Base class for all Vident components, which provides common functionality and properties.
-    included do
-      # 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
-
-    class_methods do
-      # Returns the names of the properties defined in the component class.
-      def prop_names
-        literal_properties.properties_index.keys.map(&:to_sym)
-      end
-    end
-
-    include StimulusComponent
-    include ComponentClassLists
-    include ComponentAttributeResolver
-
-    include ChildElementHelper
-    include Tailwind
-    include StimulusHelper
-
-    # 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 root_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 = {}
-
-    # 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
-
-    # Return the names of the properties defined in the component class.
-    def prop_names = self.class.prop_names
-
-    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_type = @element_tag.presence&.to_sym || :div
-
-    # 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
+    include ::Vident::Capabilities::Tailwind
+    include ::Vident::Capabilities::Declarable
+    include ::Vident::Capabilities::Identifiable
+    include ::Vident::Capabilities::StimulusDeclaring
+    include ::Vident::Capabilities::StimulusParsing
+    include ::Vident::Capabilities::StimulusMutation
+    include ::Vident::Capabilities::StimulusDraft
+    include ::Vident::Capabilities::StimulusDataEmitting
+    include ::Vident::Capabilities::ClassListBuilding
+    include ::Vident::Capabilities::RootElementRendering
+    include ::Vident::Capabilities::ChildElementRendering
+    include ::Vident::Capabilities::Inspectable
   end
 end

data/lib/vident/engine.rb

@@ -1,13 +1,14 @@
+# frozen_string_literal: true
+
 module Vident
+  # Registers acronym inflections Zeitwerk needs to load `Vident::Internals::DSL`
+  # and `Vident::Phlex::HTML` from their respective files.
   class Engine < ::Rails::Engine
-    lib_path = File.expand_path("../../../lib/", __FILE__)
-    config.autoload_paths << lib_path
-    config.eager_load_paths << lib_path
-
     config.before_initialize do
       Rails.autoloaders.each do |autoloader|
         autoloader.inflector.inflect(
-          "version" => "VERSION"
+          "dsl" => "DSL",
+          "html" => "HTML"
         )
       end
     end

data/lib/vident/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Vident
+  # Base for all gem-raised exceptions; consumers can rescue by category.
+  class Error < StandardError; end
+
+  class DeclarationError < Error; end
+
+  class ParseError < Error; end
+
+  class RenderError < Error; end
+
+  class StateError < Error; end
+
+  class ConfigurationError < Error; end
+end

data/lib/{vident2 → vident}/internals/action_builder.rb

@@ -2,30 +2,26 @@
 
 require_relative "declaration"
 
-module Vident2
+module Vident
   module Internals
-    # @api private
-    # Fluent chain returned by `action(...)` inside a `stimulus do` block.
-    # Each method mutates state and returns `self` so chains compose:
-    #
-    #   action(:submit).on(:form).modifier(:prevent).keyboard("enter")
-    #
-    # At `to_declaration` time the captured state is folded into a Hash
-    # descriptor that the `Stimulus::Action` parser already understands.
-    # If no chain method was called, the raw args pass through untouched
-    # so existing `action :click` / `action [:click, :handle]` callsites
-    # behave exactly as before.
+    # Fluent builder returned by `action(...)`. If no chain methods are called,
+    # raw args pass through untouched so bare `action :click` still works.
     class ActionBuilder
-      def initialize(*args)
+      KWARG_KEYS = %i[on call_method modifier keyboard window on_controller when].freeze
+
+      def initialize(*args, **meta)
         @args = args
-        @event = nil
-        @method_name = nil
-        @modifiers = nil
-        @keyboard = nil
-        @window = false
-        @controller_ref = nil
-        @when_proc = nil
-        @touched = false
+        unknown = meta.keys - KWARG_KEYS
+        raise ArgumentError, "action: unknown option(s) #{unknown.inspect}. Valid: #{KWARG_KEYS.inspect}" unless unknown.empty?
+
+        @event = meta[:on]
+        @method_name = meta[:call_method]
+        @modifiers = meta.key?(:modifier) ? Array(meta[:modifier]) : nil
+        @keyboard = meta[:keyboard]
+        @window = meta.fetch(:window, false)
+        @controller_ref = meta[:on_controller]
+        @when_proc = meta[:when]
+        @touched = !meta.empty?
       end
 
       def on(event)
@@ -34,7 +30,7 @@ module Vident2
         self
       end
 
-      def method(name)
+      def call_method(name)
         @method_name = name
         @touched = true
         self