vident 1.0.0.beta2 → 1.0.0

data/lib/vident/stable_id.rb

@@ -1,39 +1,70 @@
 # frozen_string_literal: true
 
-begin
-  # Introduced in Ruby 3.1
-  require "random/formatter"
-rescue LoadError
-  # to support Ruby 3.0
-  require "securerandom"
-end
+require "random/formatter"
+require "digest/md5"
 
 module Vident
   class StableId
+    class GeneratorNotSetError < StandardError; end
+
+    class StrategyNotConfiguredError < StandardError; end
+
+    RANDOM_FALLBACK = ->(generator) do
+      return Random.hex(16) unless generator
+      generator.next.join("-")
+    end
+
+    STRICT = ->(generator) do
+      unless generator
+        raise GeneratorNotSetError,
+          "No Vident::StableId sequence generator is set on the current thread. " \
+          "Call Vident::StableId.set_current_sequence_generator(seed: ...) in a " \
+          "before_action (or wrap the render in StableId.with_sequence_generator)."
+      end
+      generator.next.join("-")
+    end
+
     class << self
-      def set_current_sequence_generator
-        ::Thread.current[:vident_number_sequence_generator] = id_sequence_generator
+      # Callable(generator_or_nil) -> String. Starts nil; host app must configure it.
+      attr_accessor :strategy
+
+      def set_current_sequence_generator(seed:)
+        ::Thread.current[:vident_number_sequence_generator] = id_sequence_generator(seed)
       end
-      alias_method :new_current_sequence_generator, :set_current_sequence_generator
 
       def clear_current_sequence_generator
         ::Thread.current[:vident_number_sequence_generator] = nil
       end
 
+      def with_sequence_generator(seed:)
+        previous = ::Thread.current[:vident_number_sequence_generator]
+        set_current_sequence_generator(seed: seed)
+        yield
+      ensure
+        ::Thread.current[:vident_number_sequence_generator] = previous
+      end
+
       def next_id_in_sequence
-        generator = ::Thread.current[:vident_number_sequence_generator]
-        # When no generator exists, use a random value. This means we loose the stability of the ID sequence but
-        # at least generate unique IDs for the current render.
-        return Random.hex(16) unless generator
-        generator.next.join("-")
+        unless @strategy
+          raise StrategyNotConfiguredError,
+            "Vident::StableId.strategy is not configured. Run " \
+            "`bin/rails generate vident:install`, or set it manually in an " \
+            "initializer (e.g. `Vident::StableId.strategy = Vident::StableId::STRICT`)."
+        end
+        @strategy.call(::Thread.current[:vident_number_sequence_generator])
       end
 
       private
 
-      def id_sequence_generator
-        number_generator = Random.new(42)
+      def id_sequence_generator(seed)
+        raise ArgumentError, "seed: cannot be nil" if seed.nil?
+        number_generator = Random.new(coerce_seed(seed))
         Enumerator.produce { number_generator.hex(16) }.with_index
       end
+
+      def coerce_seed(seed)
+        Digest::MD5.hexdigest(seed.to_s).to_i(16)
+      end
     end
   end
 end

data/lib/vident/stimulus/naming.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Vident
+  module Stimulus
+    # Vident's internal naming conventions for per-primitive wiring — the
+    # `add_stimulus_<plural>` mutator method, the `@stimulus_<plural>` prop
+    # ivar, and the `@stimulus_<plural>_collection` parsed-collection ivar.
+    # Mixed in by the consumers that need these helpers. Kept off `Primitive`
+    # so the primitive stays a clean domain value object and doesn't carry
+    # the implementation details of its consumers.
+    module Naming
+      def mutator_method(primitive) = :"add_stimulus_#{primitive.name}"
+
+      def prop_ivar(primitive) = :"@stimulus_#{primitive.name}"
+
+      def collection_ivar(primitive) = :"@stimulus_#{primitive.name}_collection"
+    end
+  end
+end

data/lib/vident/stimulus/primitive.rb

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

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

@@ -2,24 +2,48 @@
 
 module Vident
   class StimulusAction < StimulusAttributeBase
-    attr_reader :event, :controller, :action
+    # https://stimulus.hotwired.dev/reference/actions#options
+    VALID_OPTIONS = [:once, :prevent, :stop, :passive, :"!passive", :capture, :self].freeze
 
-    def to_s
-      if @event
-        "#{@event}->#{@controller}##{@action}"
-      else
-        "#{@controller}##{@action}"
-      end
+    # 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
 
-    def data_attribute_name
-      "action"
+    attr_reader :event, :controller, :action, :options, :keyboard, :window
+
+    def initialize(*args, implied_controller: nil)
+      @options = []
+      @keyboard = nil
+      @window = false
+      super
     end
 
-    def data_attribute_value
-      to_s
+    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)
@@ -38,27 +62,25 @@ module Vident
     end
 
     def parse_single_argument(arg)
-      if arg.is_a?(Symbol)
-        # 1 symbol arg, name of method on implied controller
+      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)
-      elsif arg.is_a?(String)
-        # 1 string arg, fully qualified action - parse it
-        parse_qualified_action_string(arg)
-      else
-        raise ArgumentError, "Invalid 'action' argument types (1): #{arg.class}"
+      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)
-        # 2 symbol args = event + action
         @event = part1.to_s
         @controller = implied_controller_name
         @action = js_name(part2)
       elsif part1.is_a?(String) && part2.is_a?(Symbol)
-        # 1 string arg, 1 symbol = controller + action
         @event = nil
         @controller = stimulize_path(part1)
         @action = js_name(part2)
@@ -67,9 +89,9 @@ module Vident
       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)
-        # 1 symbol, 1 string, 1 symbol = event + controller + action
         @event = part1.to_s
         @controller = stimulize_path(part2)
         @action = js_name(part3)
@@ -78,16 +100,29 @@ module Vident
       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?("->")
-        # Has event: "click->controller#action"
         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
-        # No event: "controller#action"
         @event = nil
         controller_part, action_part = action_string.split("#", 2)
         @controller = controller_part

data/lib/vident/stimulus_attribute_base.rb

@@ -2,8 +2,20 @@
 
 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)
@@ -11,27 +23,17 @@ module Vident
       parse_arguments(*args)
     end
 
-    def inspect
-      "#<#{self.class.name} #{to_h}>"
-    end
+    def inspect = "#<#{self.class.name} #{to_h}>"
 
-    def to_s
-      raise NoMethodError, "Subclasses must implement to_s"
-    end
+    def to_s = raise(NoMethodError, "Subclasses must implement to_s")
 
-    def to_h
-      {data_attribute_name => data_attribute_value}
-    end
+    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"
-    end
+    def data_attribute_name = raise(NoMethodError, "Subclasses must implement data_attribute_name")
 
-    def data_attribute_value
-      raise NoMethodError, "Subclasses must implement data_attribute_value"
-    end
+    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
@@ -45,17 +47,19 @@ module Vident
 
     private
 
-    # Convert a file path to a stimulus controller name
-    def stimulize_path(path)
-      path.split("/").map { |p| p.to_s.dasherize }.join("--")
-    end
+    def stimulize_path(path) = self.class.stimulize_path(path)
 
-    # Convert a Ruby 'snake case' string to a JavaScript camel case strings
-    def js_name(name)
-      name.to_s.camelize(:lower)
+    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
 
-    # Subclasses must implement this method
     def parse_arguments(*args)
       raise NotImplementedError, "Subclasses must implement parse_arguments"
     end