vident 1.0.1 → 2.0.0

data/lib/vident/internals/action_builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+
+module Vident
+  module Internals
+    # Fluent builder returned by `action(...)`. If no chain methods are called,
+    # raw args pass through untouched so bare `action :click` still works.
+    class ActionBuilder
+      KWARG_KEYS = %i[on call_method modifier keyboard window on_controller when].freeze
+
+      def initialize(*args, **meta)
+        @args = args
+        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)
+        @event = event
+        @touched = true
+        self
+      end
+
+      def call_method(name)
+        @method_name = name
+        @touched = true
+        self
+      end
+
+      def modifier(*mods)
+        (@modifiers ||= []).concat(mods)
+        @touched = true
+        self
+      end
+
+      def keyboard(str)
+        @keyboard = str
+        @touched = true
+        self
+      end
+
+      def window
+        @window = true
+        @touched = true
+        self
+      end
+
+      def on_controller(ref)
+        @controller_ref = ref
+        @touched = true
+        self
+      end
+
+      def when(callable = nil, &block)
+        @when_proc = block || callable
+        self
+      end
+
+      def to_declaration
+        return Declaration.new(args: @args.freeze, when_proc: @when_proc, meta: {}.freeze) unless @touched
+        Declaration.new(args: [build_descriptor].freeze, when_proc: @when_proc, meta: {}.freeze)
+      end
+
+      private
+
+      def build_descriptor
+        h = base_descriptor.dup
+        h[:event] = @event if @event
+        h[:method] = @method_name if @method_name
+        h[:options] = @modifiers.dup if @modifiers
+        h[:keyboard] = @keyboard if @keyboard
+        h[:window] = true if @window
+        h[:controller] = @controller_ref if @controller_ref
+        h
+      end
+
+      def base_descriptor
+        case @args
+        in [Symbol => m] then {method: m}
+        in [Symbol => e, Symbol => m] then {event: e, method: m}
+        in [Symbol => e, String => ctrl, Symbol => m] then {event: e, method: m, controller: ctrl}
+        in [Hash => h] then h
+        else {}
+        end
+      end
+    end
+  end
+end

data/lib/vident/internals/attribute_writer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Vident
+  module Internals
+    module AttributeWriter
+      module_function
+
+      def call(plan)
+        Registry::KINDS.reduce({}) do |acc, kind|
+          acc.merge(kind.value_class.to_data_hash(plan.public_send(kind.name)))
+        end
+      end
+    end
+  end
+end

data/lib/vident/internals/class_list_builder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vident
+  module Internals
+    # Builds the root element's CSS class list with a 6-tier precedence cascade.
+    # Tiers (left-to-right): component_name, then the highest-priority non-nil of
+    # root_element_classes / root_element_attributes[:classes] / root_element(class:) /
+    # html_options[:class], then classes: prop (always appended), then stimulus class maps.
+    module ClassListBuilder
+      CLASSNAME_SEPARATOR = " "
+
+      module_function
+
+      def call(
+        component_name: nil,
+        root_element_classes: nil,
+        root_element_attributes_classes: nil,
+        root_element_html_class: nil,
+        html_options_class: nil,
+        classes_prop: nil,
+        stimulus_classes: nil,
+        stimulus_class_names: nil,
+        tailwind_merger: nil
+      )
+        parts = []
+        parts << component_name if component_name
+
+        if html_options_class
+          parts.concat(Array.wrap(html_options_class))
+        elsif root_element_html_class
+          parts.concat(Array.wrap(root_element_html_class))
+        elsif root_element_attributes_classes
+          parts.concat(Array.wrap(root_element_attributes_classes))
+        elsif root_element_classes
+          parts.concat(Array.wrap(root_element_classes))
+        end
+
+        parts.concat(Array.wrap(classes_prop)) if classes_prop
+
+        parts.compact!
+
+        if stimulus_classes && stimulus_class_names && !stimulus_class_names.empty?
+          parts.concat(stimulus_class_css(stimulus_classes, stimulus_class_names))
+        end
+
+        flattened = parts.flat_map { |s| s.to_s.split(/\s+/) }.reject(&:empty?)
+        deduped = flattened.uniq
+        return nil if deduped.empty?
+
+        joined = deduped.join(CLASSNAME_SEPARATOR)
+        tailwind_merger ? tailwind_merger.merge(joined) : joined
+      end
+
+      def stimulus_class_css(class_maps, names)
+        names_set = names.map { |n| n.to_s.dasherize }.to_set
+        class_maps.select { |cm| names_set.include?(cm.name) }.map(&:css)
+      end
+    end
+  end
+end

data/lib/vident/internals/declaration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Vident
+  module Internals
+    # One unresolved DSL entry; the Resolver parses it into typed Stimulus
+    # value objects at instance init time.
+    Declaration = Data.define(:args, :when_proc, :meta) do
+      def self.of(*args, when_proc: nil, **meta)
+        new(args: args.freeze, when_proc: when_proc, meta: meta.freeze)
+      end
+    end
+  end
+end

data/lib/vident/internals/declarations.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+
+module Vident
+  module Internals
+    # Frozen per-class aggregate of raw `Declaration` entries from `stimulus do` blocks.
+    # Keyed kinds use `[key, Declaration]` pairs so later same-key entries replace earlier ones;
+    # positional kinds are flat arrays where later blocks append.
+    class Declarations < Data.define(
+      :controllers,
+      :actions,
+      :targets,
+      :outlets,
+      :values,
+      :params,
+      :class_maps,
+      :values_from_props
+    )
+      EMPTY_ARRAY = [].freeze
+
+      def self.empty = @empty ||= new(
+        controllers: EMPTY_ARRAY,
+        actions: EMPTY_ARRAY,
+        targets: EMPTY_ARRAY,
+        outlets: EMPTY_ARRAY,
+        values: EMPTY_ARRAY,
+        params: EMPTY_ARRAY,
+        class_maps: EMPTY_ARRAY,
+        values_from_props: EMPTY_ARRAY
+      ).freeze
+
+      def any?
+        !controllers.empty? || !actions.empty? || !targets.empty? ||
+          !outlets.empty? || !values.empty? || !params.empty? ||
+          !class_maps.empty? || !values_from_props.empty?
+      end
+
+      def merge(other)
+        self.class.new(
+          controllers: concat_positional(controllers, other.controllers),
+          actions: concat_positional(actions, other.actions),
+          targets: concat_positional(targets, other.targets),
+          outlets: merge_keyed(outlets, other.outlets),
+          values: merge_keyed(values, other.values),
+          params: merge_keyed(params, other.params),
+          class_maps: merge_keyed(class_maps, other.class_maps),
+          values_from_props: (values_from_props + other.values_from_props).uniq.freeze
+        )
+      end
+
+      private
+
+      def concat_positional(a, b) = (a + b).freeze
+
+      def merge_keyed(a, b)
+        merged = {}
+        a.each { |(k, d)| merged[k] = d }
+        b.each { |(k, d)| merged[k] = d }
+        merged.to_a.freeze
+      end
+    end
+  end
+end

data/lib/vident/internals/draft.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "plan"
+
+module Vident
+  module Internals
+    # Per-instance mutable accumulator; seals into a frozen Plan once rendering begins.
+    class Draft
+      def initialize(**collections)
+        @collections = Registry.names.to_h { |name| [name, []] }
+        collections.each { |k, v| @collections[k] = v.dup if @collections.key?(k) }
+        @sealed = false
+      end
+
+      Registry.each do |kind|
+        define_method(kind.name) { @collections[kind.name] }
+
+        define_method(:"add_#{kind.name}") do |value_or_values|
+          raise_if_sealed!
+          Array(value_or_values).each { |v| @collections[kind.name] << v }
+          self
+        end
+      end
+
+      def sealed? = @sealed
+
+      def seal!
+        return @plan if @sealed
+        @sealed = true
+        @collections.each_value(&:freeze)
+        @collections.freeze
+        @plan = Plan.new(**@collections)
+      end
+
+      def plan = seal!
+
+      private
+
+      def raise_if_sealed!
+        return unless @sealed
+        raise ::Vident::StateError,
+          "cannot modify stimulus attributes after rendering has begun"
+      end
+    end
+  end
+end

data/lib/vident/internals/dsl.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "declarations"
+require_relative "action_builder"
+require_relative "target_builder"
+
+module Vident
+  module Internals
+    # Block receiver for `stimulus do ... end`. Records raw Declaration entries;
+    # parsing into typed Stimulus value objects is deferred to the Resolver.
+    class DSL
+      attr_reader :caller_location
+
+      def initialize(caller_location: nil)
+        @caller_location = caller_location
+        @controllers = []
+        @actions = []
+        @targets = []
+        @outlets = []
+        @values = []
+        @params = []
+        @class_maps = []
+        @values_from_props = []
+      end
+
+      # ---- plural (kwargs) forms --------------------------------------
+
+      def controllers(*args)
+        args.each do |arg|
+          case arg
+          in Array
+            controller(*arg)
+          else
+            controller(arg)
+          end
+        end
+        self
+      end
+
+      def actions(*names)
+        names.each do |name|
+          case name
+          in Array
+            action(*name)
+          else
+            action(name)
+          end
+        end
+        self
+      end
+
+      def targets(*names)
+        names.each do |name|
+          case name
+          in Array
+            target(*name)
+          else
+            target(name)
+          end
+        end
+        self
+      end
+
+      def values(**hash)
+        hash.each { |k, v| record_keyed(@values, k, v) }
+        self
+      end
+
+      def params(**hash)
+        hash.each { |k, v| record_keyed(@params, k, v) }
+        self
+      end
+
+      def classes(**hash)
+        hash.each { |k, v| record_keyed(@class_maps, k, v) }
+        self
+      end
+
+      # Positional Hash arg supports keys like `"admin--users"` that can't be Ruby kwargs.
+      def outlets(positional = nil, **hash)
+        if positional.is_a?(Hash)
+          positional.each { |k, v| record_keyed(@outlets, k, v) }
+        elsif !positional.nil?
+          raise ArgumentError, "outlets: positional arg must be a Hash, got #{positional.class}"
+        end
+        hash.each { |k, v| record_keyed(@outlets, k, v) }
+        self
+      end
+
+      def values_from_props(*names)
+        @values_from_props.concat(names.map(&:to_sym))
+        self
+      end
+
+      # ---- singular forms --------------------------------------------
+
+      def controller(*args, **meta)
+        @controllers << Declaration.of(*args, **meta)
+        self
+      end
+
+      def action(*args, **meta)
+        builder = ActionBuilder.new(*args, **meta)
+        @actions << builder
+        builder
+      end
+
+      def target(*args)
+        builder = TargetBuilder.new(*args)
+        @targets << builder
+        builder
+      end
+
+      def value(name, *args, **meta)
+        entry = [name, Declaration.of(*args, **meta)]
+        replace_or_append(@values, entry)
+        self
+      end
+
+      def param(name, *args, **meta)
+        entry = [name, Declaration.of(*args, **meta)]
+        replace_or_append(@params, entry)
+        self
+      end
+
+      def outlet(name, *args, **meta)
+        entry = [name, Declaration.of(*args, **meta)]
+        replace_or_append(@outlets, entry)
+        self
+      end
+
+      def class_map(name, *args, **meta)
+        entry = [name, Declaration.of(*args, **meta)]
+        replace_or_append(@class_maps, entry)
+        self
+      end
+
+      # ---- folding ----------------------------------------------------
+
+      def to_declarations
+        Declarations.new(
+          controllers: @controllers.dup.freeze,
+          actions: @actions.map(&:to_declaration).freeze,
+          targets: @targets.map(&:to_declaration).freeze,
+          outlets: @outlets.dup.freeze,
+          values: @values.dup.freeze,
+          params: @params.dup.freeze,
+          class_maps: @class_maps.dup.freeze,
+          values_from_props: @values_from_props.dup.freeze
+        ).freeze
+      end
+
+      private
+
+      def record_keyed(bucket, key, value)
+        entry = [key, Declaration.of(value)]
+        replace_or_append(bucket, entry)
+      end
+
+      def replace_or_append(bucket, entry)
+        key = entry.first
+        idx = bucket.index { |(k, _)| k == key }
+        if idx
+          bucket[idx] = entry
+        else
+          bucket << entry
+        end
+      end
+    end
+  end
+end

data/lib/vident/internals/plan.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Vident
+  module Internals
+    Plan = Data.define(*Registry.names)
+  end
+end

data/lib/vident/internals/registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../stimulus/controller"
+require_relative "../stimulus/action"
+require_relative "../stimulus/target"
+require_relative "../stimulus/outlet"
+require_relative "../stimulus/value"
+require_relative "../stimulus/param"
+require_relative "../stimulus/class_map"
+
+module Vident
+  module Internals
+    module Registry
+      Kind = Data.define(:name, :plural_name, :singular_name, :value_class, :keyed) do
+        alias_method :keyed?, :keyed
+      end
+
+      KINDS = [
+        Kind.new(:controllers, :controllers, :controller, Vident::Stimulus::Controller, false),
+        Kind.new(:actions, :actions, :action, Vident::Stimulus::Action, false),
+        Kind.new(:targets, :targets, :target, Vident::Stimulus::Target, false),
+        Kind.new(:outlets, :outlets, :outlet, Vident::Stimulus::Outlet, true),
+        Kind.new(:values, :values, :value, Vident::Stimulus::Value, true),
+        Kind.new(:params, :params, :param, Vident::Stimulus::Param, true),
+        Kind.new(:class_maps, :classes, :class, Vident::Stimulus::ClassMap, true)
+      ].freeze
+
+      BY_NAME = KINDS.to_h { |k| [k.name, k] }.freeze
+
+      def self.fetch(name) = BY_NAME.fetch(name)
+
+      def self.each(&block) = KINDS.each(&block)
+
+      def self.names = BY_NAME.keys
+    end
+  end
+end