vident 1.0.2 → 2.0.0

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

@@ -2,24 +2,12 @@
 
 require "set"
 
-module Vident2
+module Vident
   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.
+    # 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 = " "
 
@@ -39,7 +27,6 @@ module Vident2
         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
@@ -50,8 +37,6 @@ module Vident2
           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!
@@ -68,8 +53,6 @@ module Vident2
         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)

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/{vident2 → vident}/internals/declarations.rb

@@ -2,19 +2,12 @@
 
 require_relative "declaration"
 
-module Vident2
+module Vident
   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(
+    # 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,
@@ -23,7 +16,7 @@ module Vident2
       :params,
       :class_maps,
       :values_from_props
-    ) do
+    )
       EMPTY_ARRAY = [].freeze
 
       def self.empty = @empty ||= new(
@@ -43,9 +36,6 @@ module Vident2
           !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),
@@ -63,8 +53,6 @@ module Vident2
 
       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 }

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

@@ -3,16 +3,9 @@
 require_relative "registry"
 require_relative "plan"
 
-module Vident2
+module Vident
   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.
+    # Per-instance mutable accumulator; seals into a frozen Plan once rendering begins.
     class Draft
       def initialize(**collections)
         @collections = Registry.names.to_h { |name| [name, []] }
@@ -21,12 +14,8 @@ module Vident2
       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 }
@@ -36,8 +25,6 @@ module Vident2
 
       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
@@ -52,7 +39,7 @@ module Vident2
 
       def raise_if_sealed!
         return unless @sealed
-        raise ::Vident2::StateError,
+        raise ::Vident::StateError,
           "cannot modify stimulus attributes after rendering has begun"
       end
     end

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

@@ -5,15 +5,10 @@ require_relative "declarations"
 require_relative "action_builder"
 require_relative "target_builder"
 
-module Vident2
+module Vident
   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.
+    # 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
 
@@ -31,9 +26,6 @@ module Vident2
 
       # ---- 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
@@ -46,10 +38,6 @@ module Vident2
         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
@@ -89,10 +77,7 @@ module Vident2
         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.
+      # 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) }
@@ -110,31 +95,23 @@ module Vident2
 
       # ---- 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)
+      def action(*args, **meta)
+        builder = ActionBuilder.new(*args, **meta)
         @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)
@@ -161,8 +138,6 @@ module Vident2
 
       # ---- 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,
@@ -183,7 +158,6 @@ module Vident2
         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 }

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