vident 1.0.1 → 1.0.2

data/lib/vident2/internals/attribute_writer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Vident2
+  module Internals
+    # @api private
+    # Pure: `Plan -> Hash{Symbol => String}` of `data-*` fragments.
+    # Delegates per-kind combining (space-join, grouped-by-controller,
+    # one-per-key) to each value class's `.to_data_hash`.
+    module AttributeWriter
+      module_function
+
+      def call(plan)
+        Registry::KINDS.each_with_object({}) do |kind, acc|
+          fragment = kind.value_class.to_data_hash(plan.public_send(kind.name))
+          acc.merge!(fragment)
+        end
+      end
+    end
+  end
+end

data/lib/vident2/internals/class_list_builder.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Vident2
+  module Internals
+    # @api private
+    # Root-element class-list builder. Implements the 6-tier precedence
+    # cascade plus optional TailwindMerger dedup.
+    #
+    # Tiers (render order, left -> right):
+    #   1. component_name — always first.
+    #   2-5. Priority cascade (only the highest non-nil wins):
+    #        root_element_classes (instance override) <
+    #        root_element_attributes[:classes] <
+    #        root_element(class:) from template <
+    #        html_options[:class] from prop
+    #   6. classes: prop — ALWAYS appended, even when tier 5 is present.
+    #
+    # Plus: per-kind StimulusClassMap entries whose name is in
+    # `stimulus_class_names` are appended as CSS. Tailwind merge runs last
+    # if the merger is passed.
+    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
+
+        # Priority cascade: top-down, first non-nil wins.
+        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
+
+        # `classes:` prop: always appended, even when something in the
+        # cascade already contributed.
+        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
+
+      # Pick ClassMap entries whose `name` matches any of the requested
+      # Symbols/Strings (dasherized to match the ClassMap's canonical form).
+      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/vident2/internals/declaration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Vident2
+  module Internals
+    # @api private
+    # One unresolved DSL entry. `args` is the raw argument tuple passed
+    # to the DSL primitive; the Resolver parses it into a Stimulus value
+    # object at instance init. `when_proc` (optional) is a `-> { ... }`
+    # filter evaluated in the component binding; `meta` is a free-form
+    # Hash for options like `from_prop: true` the parser needs to see.
+    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/vident2/internals/declarations.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+
+module Vident2
+  module Internals
+    # @api private
+    # Frozen per-class aggregate of what `stimulus do ... end` declared.
+    # One field per kind (plural Registry name) plus `values_from_props`.
+    # Entries stay as raw `Declaration` records — the Resolver parses
+    # them into `Stimulus::*` value objects at instance init, not here.
+    #
+    # Keyed kinds (values, params, class_maps, outlets) use `(key, entry)`
+    # pairs to let a later block's same-key entry replace an earlier one.
+    # Positional kinds (controllers, actions, targets) are flat arrays;
+    # later blocks append.
+    Declarations = Data.define(
+      :controllers,
+      :actions,
+      :targets,
+      :outlets,
+      :values,
+      :params,
+      :class_maps,
+      :values_from_props
+    ) do
+      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
+
+      # Merge two Declarations, treating `self` as parent and `other` as
+      # child. Positional kinds concat (parent first, then child).
+      # Keyed kinds last-wins on matching key.
+      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
+
+      # Keyed entries are `[key, Declaration]` tuples; last write on a
+      # given key wins, insertion order otherwise preserved.
+      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/vident2/internals/draft.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "plan"
+
+module Vident2
+  module Internals
+    # @api private
+    # Per-instance mutable working copy. Seven Arrays, one per Registry
+    # kind. `add_<kind>(value_or_values)` mutators are the single sanctioned
+    # seam for cross-instance mutation (outlet-host pattern) and for
+    # `add_stimulus_*` calls from `after_component_initialize`.
+    #
+    # After `seal!` the Draft is closed — any further `add_*` raises
+    # `Vident2::StateError`. The sealed Plan is a frozen Data.define snapshot.
+    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|
+        # reader
+        define_method(kind.name) { @collections[kind.name] }
+
+        # mutator: one call = one logical add. Array input concats all
+        # elements as pre-parsed values; a single non-Array value appends
+        # as one entry.
+        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
+
+      # Freeze the working copy and snapshot as a frozen Plan. Idempotent:
+      # subsequent calls return the memoised Plan.
+      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 ::Vident2::StateError,
+          "cannot modify stimulus attributes after rendering has begun"
+      end
+    end
+  end
+end

data/lib/vident2/internals/dsl.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "declarations"
+require_relative "action_builder"
+require_relative "target_builder"
+
+module Vident2
+  module Internals
+    # @api private
+    # Block receiver for `stimulus do ... end`. Records each primitive
+    # call as one or more `Declaration` raw entries; `finalize` folds
+    # them into a frozen `Declarations` aggregate.
+    #
+    # Parsing into `Stimulus::*` value objects is deferred to the
+    # Resolver — this class stores only raw argument tuples.
+    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 --------------------------------------
+
+      # Each arg becomes one controller entry. An Array arg is splatted
+      # into positional args for a single controller (e.g. a tuple
+      # `[path, {as: :alias}]`); anything else is treated as a path.
+      def controllers(*args)
+        args.each do |arg|
+          case arg
+          in Array
+            controller(*arg)
+          else
+            controller(arg)
+          end
+        end
+        self
+      end
+
+      # Array in the plural form splats into the singular parser (matching
+      # V1's plural→singular forwarding) so `actions [:click, :handle]`
+      # records a single Action entry with event+method rather than two
+      # separate Actions.
+      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
+
+      # Outlets accept a positional Hash (for keys like `"admin--users"`
+      # that can't be a Ruby kwarg) plus kwargs. Order: positional first,
+      # kwargs after — last-write wins on duplicates per the keyed merge
+      # rule.
+      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 --------------------------------------------
+
+      # Optional `as: :alias` captured in meta for the Resolver.
+      def controller(*args, **meta)
+        @controllers << Declaration.of(*args, **meta)
+        self
+      end
+
+      # Returns an `ActionBuilder` so users can fluent-chain
+      # `.on(:event).modifier(:prevent).keyboard("ctrl+s").window.when { ... }`.
+      # If no chain methods are called, the raw args pass through unchanged.
+      def action(*args)
+        builder = ActionBuilder.new(*args)
+        @actions << builder
+        builder
+      end
+
+      # Returns a `TargetBuilder` so users can chain `.when { ... }` for
+      # conditional inclusion.
+      def target(*args)
+        builder = TargetBuilder.new(*args)
+        @targets << builder
+        builder
+      end
+
+      # `value(:url, "x")`, `value(:url, -> { ... })`,
+      # `value(:count, static: 0)`, `value(:clicked_count, from_prop: true)`.
+      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 ----------------------------------------------------
+
+      # Returns a frozen Declarations snapshot of what this block
+      # received. Called once the block finishes executing.
+      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
+
+      # Last-write wins on matching key, insertion order otherwise.
+      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/vident2/internals/plan.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Vident2
+  module Internals
+    # @api private
+    # Frozen snapshot produced by `Draft#seal!`. One field per Registry
+    # kind, each an Array<Stimulus::*>.
+    Plan = Data.define(*Registry.names)
+  end
+end

data/lib/vident2/internals/registry.rb

@@ -0,0 +1,41 @@
+# 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 Vident2
+  # @api private — consumed by the DSL, Resolver, Draft, Plan,
+  # AttributeWriter, and Capabilities::StimulusMutation. Not a public
+  # extension surface; extensions monkeypatch at their own risk.
+  module Internals
+    module Registry
+      # Per-kind metadata. `name` is the canonical internal key;
+      # `plural_name` / `singular_name` drive DSL method names (e.g.
+      # `stimulus_classes` / `stimulus_class` for `class_maps`); `keyed`
+      # distinguishes hash-shaped kinds (values, params, class_maps,
+      # outlets) from positional ones (controllers, actions, targets).
+      Kind = Data.define(:name, :plural_name, :singular_name, :value_class, :keyed)
+
+      KINDS = [
+        Kind.new(:controllers, :controllers, :controller, Vident2::Stimulus::Controller, false),
+        Kind.new(:actions,     :actions,     :action,     Vident2::Stimulus::Action,     false),
+        Kind.new(:targets,     :targets,     :target,     Vident2::Stimulus::Target,     false),
+        Kind.new(:outlets,     :outlets,     :outlet,     Vident2::Stimulus::Outlet,     true),
+        Kind.new(:values,      :values,      :value,      Vident2::Stimulus::Value,      true),
+        Kind.new(:params,      :params,      :param,      Vident2::Stimulus::Param,      true),
+        Kind.new(:class_maps,  :classes,     :class,      Vident2::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