vident 1.0.1 → 2.0.0

data/lib/vident/stimulus/naming.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/string/inflections"
+
 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}"
+      module_function
 
-      def prop_ivar(primitive) = :"@stimulus_#{primitive.name}"
+      def stimulize_path(path)
+        path.to_s.split("/").map(&:dasherize).join("--")
+      end
 
-      def collection_ivar(primitive) = :"@stimulus_#{primitive.name}_collection"
+      def js_name(name)
+        name.to_s.camelize(:lower)
+      end
     end
   end
 end

data/lib/vident/stimulus/null.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Vident
+  module Stimulus
+    Null = ::Vident::StimulusNull
+  end
+end

data/lib/vident/stimulus/outlet.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "base"
+require_relative "controller"
+
+module Vident
+  module Stimulus
+    # `data-<ctrl>-<name>-outlet` fragment. `selector` is the CSS selector
+    # the Stimulus runtime uses to resolve the outlet on the page.
+    class Outlet < Base
+      prop :controller, Controller
+      prop :name, String
+      prop :selector, String
+
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => sym]
+          name = sym.to_s.dasherize
+          new(
+            controller: implied,
+            name: name,
+            selector: auto_selector(name, component_id: component_id)
+          )
+        in [String => str]
+          name = str.dasherize
+          new(
+            controller: implied,
+            name: name,
+            selector: auto_selector(name, component_id: component_id)
+          )
+        in [[identifier, selector]]
+          new(
+            controller: implied,
+            name: identifier.to_s.dasherize,
+            selector: selector
+          )
+        in [Symbol => sym, String => sel]
+          new(
+            controller: implied,
+            name: sym.to_s.dasherize,
+            selector: sel
+          )
+        in [String => id_or_name, String => sel]
+          new(
+            controller: implied,
+            name: id_or_name.dasherize,
+            selector: sel
+          )
+        in [String => ctrl_path, Symbol => sym, String => sel]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: sym.to_s.dasherize,
+            selector: sel
+          )
+        in [obj] if obj.respond_to?(:stimulus_identifier)
+          ident = obj.stimulus_identifier
+          new(
+            controller: implied,
+            name: ident,
+            selector: auto_selector(ident, component_id: component_id)
+          )
+        else
+          raise ::Vident::ParseError, "Outlet.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def self.auto_selector(outlet_identifier, component_id:)
+        prefix = component_id ? "##{css_escape_ident(component_id)} " : ""
+        "#{prefix}[data-controller~=#{outlet_identifier}]"
+      end
+
+      # CSS-escapes anything outside the bare identifier alphabet
+      # (`A-Za-z0-9_-`) using the `\HH ` hex form (with trailing space
+      # delimiter). Bare `\<char>` works for many punctuation cases but
+      # not for whitespace, parens, or non-ASCII — the hex form is
+      # always valid per CSS Syntax §4.3.7.
+      def self.css_escape_ident(id)
+        id.to_s.gsub(/[^A-Za-z0-9_-]/) { |c| "\\#{c.ord.to_s(16)} " }
+      end
+
+      def to_s = selector
+
+      def data_attribute_key = :"#{controller.name}-#{name}-outlet"
+
+      def to_data_pair = [data_attribute_key, selector]
+
+      def to_h = {data_attribute_key => selector}
+      alias_method :to_hash, :to_h
+    end
+  end
+end

data/lib/vident/stimulus/param.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+require "literal"
+require_relative "naming"
+require_relative "base"
+require_relative "null"
+require_relative "controller"
+
+module Vident
+  module Stimulus
+    # `data-<ctrl>-<name>-param` fragment — same shape as Value, distinct
+    # semantics on the JS side (read via `event.params.<camel>`).
+    class Param < Base
+      prop :controller, Controller
+      prop :name, String
+      prop :serialized, String
+
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => name_sym, raw]
+          new(
+            controller: implied,
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        in [String => ctrl_path, Symbol => name_sym, raw]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        else
+          raise ::Vident::ParseError, "Param.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def self.serialize(raw)
+        raise ::Vident::ParseError, "Param.serialize: nil is not serializable — filter nil upstream" if raw.nil?
+        case raw
+        when Array, Hash then raw.to_json
+        else raw.to_s
+        end
+      end
+
+      def to_s = serialized
+
+      def data_attribute_key = :"#{controller.name}-#{name}-param"
+
+      def to_data_pair = [data_attribute_key, serialized]
+
+      def to_h = {data_attribute_key => serialized}
+      alias_method :to_hash, :to_h
+    end
+  end
+end

data/lib/vident/stimulus/target.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "literal"
+require_relative "naming"
+require_relative "base"
+require_relative "controller"
+
+module Vident
+  module Stimulus
+    # `data-<ctrl>-target` fragment.
+    class Target < Base
+      prop :controller, Controller
+      prop :name, String
+
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => sym]
+          new(controller: implied, name: Naming.js_name(sym))
+        in [String => str]
+          new(controller: implied, name: str)
+        in [String => ctrl_path, Symbol => sym]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: Naming.js_name(sym)
+          )
+        else
+          raise ::Vident::ParseError, "Target.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def to_s = name
+
+      def data_attribute_key = :"#{controller.name}-target"
+
+      def to_data_pair = [data_attribute_key, name]
+
+      def to_h = {data_attribute_key => name}
+      alias_method :to_hash, :to_h
+
+      def self.to_data_hash(targets)
+        targets.each_with_object({}) do |t, acc|
+          key, value = t.to_data_pair
+          acc[key] = acc.key?(key) ? "#{acc[key]} #{value}" : value
+        end
+      end
+    end
+  end
+end

data/lib/vident/stimulus/value.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+require "literal"
+require_relative "naming"
+require_relative "base"
+require_relative "controller"
+require_relative "null"
+
+module Vident
+  module Stimulus
+    # `data-<ctrl>-<name>-value` fragment. Holds the serialised form
+    # (always a String). Only `nil` is rejected — `false`, blank strings,
+    # and empty collections emit their serialised form.
+    class Value < Base
+      prop :controller, Controller
+      prop :name, String
+      prop :serialized, String
+
+      def self.parse(*args, implied:, component_id: nil)
+        case args
+        in [Symbol => name_sym, raw]
+          new(
+            controller: implied,
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        in [String => ctrl_path, Symbol => name_sym, raw]
+          new(
+            controller: Controller.parse(ctrl_path, implied: implied),
+            name: name_sym.to_s.dasherize,
+            serialized: serialize(raw)
+          )
+        else
+          raise ::Vident::ParseError, "Value.parse: invalid arguments #{args.inspect}"
+        end
+      end
+
+      def self.serialize(raw)
+        raise ::Vident::ParseError, "Value.serialize: nil is not serializable — filter nil upstream" if raw.nil?
+        case raw
+        when Array, Hash then raw.to_json
+        else raw.to_s
+        end
+      end
+
+      def to_s = serialized
+
+      def data_attribute_key = :"#{controller.name}-#{name}-value"
+
+      def to_data_pair = [data_attribute_key, serialized]
+
+      def to_h = {data_attribute_key => serialized}
+      alias_method :to_hash, :to_h
+    end
+  end
+end

data/lib/vident/stimulus_null.rb

@@ -9,13 +9,9 @@ module Vident
   # A bare `nil` (static or returned from a proc) omits the attribute entirely so
   # Stimulus uses its per-type default. Reach for this sentinel only when you need
   # an explicit JS `null`.
-  StimulusNull = Object.new
-  def StimulusNull.inspect
-    "Vident::StimulusNull"
-  end
+  StimulusNull = Object.new.tap do |s|
+    def s.inspect = "Vident::StimulusNull"
 
-  def StimulusNull.to_s
-    "null"
-  end
-  StimulusNull.freeze
+    def s.to_s = "null"
+  end.freeze
 end

data/lib/vident/tailwind.rb

@@ -1,21 +1,8 @@
 # frozen_string_literal: true
 
-module Vident
-  # Adds Tailwind CSS class merging functionality to components
-  # This module provides methods to create and manage TailwindMerge::Merger instances
-  module Tailwind
-    # Get or create a thread-safe Tailwind merger instance
-    def tailwind_merger
-      return unless tailwind_merge_available?
-
-      return @tailwind_merger if defined?(@tailwind_merger)
+require_relative "capabilities/tailwind"
 
-      @tailwind_merger = Thread.current[:vident_tailwind_merger] ||= ::TailwindMerge::Merger.new
-    end
-
-    # Check if TailwindMerge gem is available
-    def tailwind_merge_available?
-      defined?(::TailwindMerge::Merger) && ::TailwindMerge::Merger.respond_to?(:new)
-    end
-  end
+module Vident
+  # Top-level alias for the mixin at `Vident::Capabilities::Tailwind`.
+  Tailwind = Capabilities::Tailwind
 end

data/lib/vident/types.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "literal"
+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
+  # Canonical Literal type unions for the seven `stimulus_*:` props.
+  # The same objects are used internally by `Vident::Capabilities::Declarable`
+  # for the built-in props; exposed here so user components can reference
+  # them when adding matching props of their own.
+  module Types
+    extend Literal::Types
+
+    StimulusControllers = _Array(_Union(String, Symbol, ::Vident::Stimulus::Controller))
+    StimulusActions = _Array(_Union(String, Symbol, Array, Hash, ::Vident::Stimulus::Action))
+    StimulusTargets = _Array(_Union(String, Symbol, Array, ::Vident::Stimulus::Target))
+    StimulusOutlets = _Array(_Union(String, Symbol, Array, ::Vident::Stimulus::Outlet))
+    StimulusValues = _Union(_Hash(Symbol, _Any), Array, ::Vident::Stimulus::Value)
+    StimulusParams = _Union(_Hash(Symbol, _Any), Array, ::Vident::Stimulus::Param)
+    StimulusClasses = _Union(_Hash(Symbol, _Any), Array, ::Vident::Stimulus::ClassMap)
+  end
+end

data/lib/vident/version.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
 module Vident
-  VERSION = "1.0.1"
-
-  # Shared version for all vident gems
-  def self.version
-    VERSION
-  end
+  VERSION = "2.0.0"
 end

data/lib/vident.rb

@@ -5,46 +5,54 @@ require "active_support/concern"
 require "literal"
 
 require "vident/version"
-require "vident/tailwind"
 
-require "vident/stimulus_null"
-require "vident/stimulus_attribute_base"
-require "vident/stimulus_controller"
-require "vident/stimulus_action"
-require "vident/stimulus_target"
-require "vident/stimulus_outlet"
-require "vident/stimulus_value"
-require "vident/stimulus_param"
-require "vident/stimulus_class"
-
-require "vident/stimulus_collection_base"
-require "vident/stimulus_controller_collection"
-require "vident/stimulus_action_collection"
-require "vident/stimulus_target_collection"
-require "vident/stimulus_outlet_collection"
-require "vident/stimulus_value_collection"
-require "vident/stimulus_param_collection"
-require "vident/stimulus_class_collection"
-
-require "vident/stimulus/primitive"
-require "vident/stimulus/naming"
-require "vident/stimulus"
+module Vident
+end
 
-require "vident/stimulus_attributes"
-require "vident/stimulus_data_attribute_builder"
-
-require "vident/child_element_helper"
+require "vident/engine" if defined?(Rails::Engine)
+require "vident/error"
 require "vident/stable_id"
-require "vident/class_list_builder"
+require "vident/stimulus_null"
 
-require "vident/stimulus_component"
-require "vident/component_class_lists"
-require "vident/component_attribute_resolver"
-require "vident/stimulus_builder"
-require "vident/stimulus_helper"
+require "vident/stimulus/naming"
+require "vident/stimulus/null"
+require "vident/stimulus/controller"
+require "vident/stimulus/action"
+require "vident/stimulus/target"
+require "vident/stimulus/outlet"
+require "vident/stimulus/value"
+require "vident/stimulus/param"
+require "vident/stimulus/class_map"
+require "vident/stimulus/collection"
+require "vident/types"
+require "vident/internals/registry"
+require "vident/internals/declaration"
+require "vident/internals/declarations"
+require "vident/internals/dsl"
+require "vident/internals/draft"
+require "vident/internals/plan"
+require "vident/internals/resolver"
+require "vident/internals/attribute_writer"
+require "vident/internals/class_list_builder"
+
+require "vident/capabilities/tailwind"
+require "vident/capabilities/caching"
+require "vident/capabilities/declarable"
+require "vident/capabilities/identifiable"
+require "vident/capabilities/stimulus_declaring"
+require "vident/capabilities/stimulus_parsing"
+require "vident/capabilities/stimulus_mutation"
+require "vident/capabilities/stimulus_draft"
+require "vident/capabilities/stimulus_data_emitting"
+require "vident/capabilities/class_list_building"
+require "vident/capabilities/root_element_rendering"
+require "vident/capabilities/child_element_rendering"
+require "vident/capabilities/inspectable"
 
-require "vident/component"
+require "vident/tailwind"
+require "vident/caching"
 
-require "vident/engine" if defined?(Rails)
+require "vident/component"
 
-module Vident; end
+require "vident/phlex"
+require "vident/view_component"