vident 0.1.0

data/lib/vident/attributes/typed.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+if Gem.loaded_specs.has_key? "dry-struct"
+  require_relative "./types"
+  require_relative "./typed_niling_struct"
+
+  module Vident
+    # Adapts Dry Types to confinus Typed Attributes. We use dry-struct (see ::Core::NilingStruct) but
+    # we could probably also use dry-initializer directly, saving us from maintaining the schema.
+    module Attributes
+      module Typed
+        extend ActiveSupport::Concern
+
+        def prepare_attributes(attributes)
+          @__attributes = self.class.schema.new(**attributes)
+        end
+
+        def attributes
+          @__attributes.attributes
+        end
+
+        def attribute_names
+          @attribute_names ||= self.class.attribute_names
+        end
+
+        def attribute(key)
+          if Rails.env.development? && !key?(key)
+            raise StandardError, "Attribute #{key} not found in #{self.class.name}"
+          end
+          @__attributes.attributes[key]
+        end
+        alias_method :[], :attribute
+
+        def key?(key)
+          self.class.schema.attribute_names.include?(key)
+        end
+
+        def to_hash
+          @__attributes.to_h
+        end
+
+        class_methods do
+          def inherited(subclass)
+            subclass.instance_variable_set(:@schema, @schema.clone)
+            subclass.instance_variable_set(:@attribute_ivar_names, @attribute_ivar_names.clone)
+            super
+          end
+
+          def attribute_names
+            schema.attribute_names
+          end
+
+          def attribute_metadata(key)
+            schema.schema.key(key).meta
+          end
+
+          attr_reader :schema, :attribute_ivar_names
+
+          def attribute(name, type = :any, **options)
+            type_info = map_primitive_to_dry_type(type, !options[:convert])
+            type_info = set_constraints(type_info, type, options)
+            define_on_schema(name, type_info, options)
+          end
+
+          private
+
+          def set_constraints(type_info, specified_type, options)
+            member_klass = options[:type] || options[:sub_type]
+            if member_klass && type_info.respond_to?(:of)
+              # Sub types of collections currently can be nil - this should be an option
+              type_info = type_info.of(
+                map_primitive_to_dry_type(member_klass, !options[:convert]).optional.meta(required: false)
+              )
+            end
+            type_info = type_info.optional.meta(required: false) if allows_nil?(options)
+            type_info = type_info.constrained(filled: true) unless allows_blank?(options)
+            if options[:default]&.is_a?(Proc)
+              type_info = type_info.default(options[:default].freeze)
+            elsif !options[:default].nil?
+              type_info = type_info.default(->(_) { options[:default] }.freeze)
+            end
+            type_info = type_info.constrained(included_in: options[:in].freeze) if options[:in]
+
+            # Store adapter type info in the schema for use by typed form
+            metadata = {typed_attribute_type: specified_type, typed_attribute_options: options}
+            type_info.meta(**metadata)
+          end
+
+          def delegates?(options)
+            options[:delegates] != false
+          end
+
+          def define_on_schema(name, type_info, options)
+            @attribute_ivar_names ||= {}
+            @attribute_ivar_names[name] = :"@#{name}"
+            define_attribute_delegate(name) if delegates?(options)
+            @schema ||= Class.new(Vident::Attributes::TypedNilingStruct)
+            @schema.attribute name, type_info
+          end
+
+          def define_attribute_delegate(attr_name)
+            # Define reader & presence check method
+            class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+          def #{attr_name}
+            @__attributes.attributes[:#{attr_name}]
+          end
+  
+          def #{attr_name}?
+            send(:#{attr_name}).present?
+          end
+            RUBY
+          end
+
+          def allows_nil?(options)
+            return true unless options
+            allow_nil = options[:allow_nil]
+            return false if allow_nil == false
+            allow_nil || allows_blank?(options)
+          end
+
+          def allows_blank?(options)
+            return true unless options
+            allow_blank = options[:allow_blank]
+            allow_blank.nil? ? true : allow_blank
+          end
+
+          def map_primitive_to_dry_type(type, strict)
+            if type == :any
+              Types::Nominal::Any
+            elsif type == Integer
+              strict ? Types::Strict::Integer : Types::Params::Integer
+            elsif type == BigDecimal
+              strict ? Types::Strict::Decimal : Types::Params::Decimal
+            elsif type == Float
+              strict ? Types::Strict::Float : Types::Params::Float
+            elsif type == Numeric
+              if strict
+                Types::Strict::Float | Types::Strict::Integer | Types::Strict::Decimal
+              else
+                Types::Params::Float | Types::Params::Integer | Types::Params::Decimal
+              end
+            elsif type == Symbol
+              strict ? Types::Strict::Symbol : Types::Coercible::Symbol
+            elsif type == String
+              strict ? Types::Strict::String : Types::Coercible::String
+            elsif type == Time
+              strict ? Types::Strict::Time : Types::Params::Time
+            elsif type == Date
+              strict ? Types::Strict::Date : Types::Params::Date
+            elsif type == Array
+              strict ? Types::Strict::Array : Types::Params::Array
+            elsif type == Hash
+              strict ? Types::Strict::Hash : Types::Coercible::Hash
+            elsif type == :boolean
+              strict ? Types::Strict::Bool : Types::Params::Bool
+            elsif strict
+              # when strict create a Nominal type with a is_a? constraint, otherwise create a Nominal type which constructs
+              # values using the default constructor, `new`.
+              Types.Instance(type)
+            else
+              Types.Constructor(type) { |values| type.new(**values) }
+            end
+          end
+        end
+      end
+    end
+  end
+else
+  module Vident
+    module Attributes
+      module Typed
+        def self.included(base)
+          raise "Vident::Attributes::Typed requires dry-struct to be installed"
+        end
+      end
+    end
+  end
+end

data/lib/vident/attributes/typed_niling_struct.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Vident
+  module Attributes
+    # A dry struct that is loose about keys provided on initialization. It sets them to nil if not provided.
+    # It is strict about types but not about provided keys
+    class TypedNilingStruct < ::Dry::Struct
+      # convert string keys to symbols
+      transform_keys(&:to_sym)
+
+      # resolve default types on nil
+      transform_types do |type|
+        if type.default?
+          type.constructor { |value| value.nil? ? ::Dry::Types::Undefined : value }
+        else
+          type
+        end
+      end
+
+      class << self
+        def check_schema_duplication(new_keys)
+          # allow overriding keys
+        end
+      end
+    end
+  end
+end

data/lib/vident/attributes/types.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module Vident
+  module Attributes
+    module Types
+      include ::Dry.Types
+
+      StrippedString = Types::String.constructor(&:strip)
+      BooleanDefaultFalse = Types::Bool.default(false)
+      BooleanDefaultTrue = Types::Bool.default(true)
+      HashDefaultEmpty = Types::Hash.default({}.freeze)
+    end
+  end
+end

data/lib/vident/base.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Vident
+  module Base
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def no_stimulus_controller
+        @no_stimulus_controller = true
+      end
+
+      def stimulus_controller?
+        !@no_stimulus_controller
+      end
+
+      # The "name" of the component from its class name and namespace. This is used to generate a HTML class name
+      # that can helps identify the component type in the DOM or for styling purposes.
+      def component_name
+        @component_name ||= stimulus_identifier
+      end
+
+      def slots?
+        registered_slots.present?
+      end
+
+      # TODO: move stuff related to cache key to a module
+
+      # TypedComponents can be used with fragment caching, but you need to be careful! Read on...
+      #
+      #     <% cache component do %>
+      #      <%= render component %>
+      #    <% end %>
+      #
+      # The most important point is that Rails cannot track dependencies on the component itself, so you need to
+      # be careful to be explicit on the attributes, and manually specify any sub Viewcomponent dependencies that the
+      # component has. The assumption is that the subcomponent takes any attributes from the parent, so the cache key
+      # depends on the parent component attributes. Otherwise changes to the parent or sub component views/Ruby class
+      # will result in different cache keys too. Of course if you invalidate all cache keys with a modifier on deploy
+      # then no need to worry about changing the cache key on component changes, only on attribute/data changes.
+      #
+      # A big caveat is that the cache key cannot depend on anything related to the view_context of the component (such
+      # as `helpers` as the key is created before the rending pipline is invoked (which is when the view_context is set).
+      def depends_on(*klasses)
+        @component_dependencies ||= []
+        @component_dependencies += klasses
+      end
+
+      attr_reader :component_dependencies
+
+      def with_cache_key(*attrs, name: :_collection)
+        raise StandardError, "with_cache_key can only be used on components *without* slots as there is no eary way to track their content changes so too risky" if slots?
+        # Add view file to cache key
+        attrs << :component_modified_time
+        super
+      end
+
+      def component_modified_time
+        return @component_modified_time if Rails.env.production? && @component_modified_time
+        # FIXME: This could stack overflow if there are circular dependencies
+        deps = component_dependencies&.map(&:component_modified_time)&.join("-") || ""
+        @component_modified_time = deps + sidecar_view_modified_time + rb_component_modified_time
+      end
+
+      def sidecar_view_modified_time
+        return @sidecar_view_modified_time if Rails.env.production? && defined?(@sidecar_view_modified_time)
+        @sidecar_view_modified_time = ::File.exist?(template_path) ? ::File.mtime(template_path).to_i.to_s : ""
+      end
+
+      def rb_component_modified_time
+        return @rb_component_modified_time if Rails.env.production? && defined?(@rb_component_modified_time)
+        @rb_component_modified_time = ::File.exist?(component_path) ? ::File.mtime(component_path).to_i.to_s : ""
+      end
+
+      def template_path
+        File.join components_base_path, "#{virtual_path}.html.erb"
+      end
+
+      def component_path
+        File.join components_base_path, "#{virtual_path}.rb"
+      end
+
+      def components_base_path
+        ::Rails.configuration.view_component.view_component_path || "app/components"
+      end
+
+      # Dont check collection params, we use kwargs
+      def validate_collection_parameter!(validate_default: false)
+      end
+
+      # stimulus controller identifier
+      def stimulus_identifier
+        stimulus_identifier_from_path(identifier_name_path)
+      end
+
+      def identifier_name_path
+        if ancestors.include?(Phlex::HTML)
+          name.remove("Views::").underscore
+        else
+          name.underscore
+        end
+      end
+
+      def stimulus_identifier_from_path(path)
+        path.split("/").map { |p| p.to_s.dasherize }.join("--")
+      end
+
+      private
+
+      # Define reader & presence check method, for performance use ivar directly
+      def define_attribute_delegate(attr_name)
+        class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+          def #{attr_name}
+            #{@attribute_ivar_names[attr_name]}
+          end
+
+          def #{attr_name}?
+            #{@attribute_ivar_names[attr_name]}.present?
+          end
+        RUBY
+      end
+    end
+
+    def prepare_attributes(attributes)
+      raise NotImplementedError
+    end
+
+    # Override this method to perform any initialisation before attributes are set
+    def before_initialise(_attrs)
+    end
+
+    # Override this method to perform any initialisation after attributes are set
+    def after_initialise
+    end
+
+    def clone(overrides = {})
+      new_set = to_hash.merge(**overrides)
+      self.class.new(**new_set)
+    end
+
+    def inspect(klass_name = "Component")
+      attr_text = attributes.map { |k, v| "#{k}=#{v.inspect}" }.join(", ")
+      "#<#{self.class.name}<Vident::#{klass_name}> #{attr_text}>"
+    end
+
+    # Generate a unique ID for a component, can be overridden as required. Makes it easier to setup things like ARIA
+    # attributes which require elements to reference by ID. Note this overrides the `id` accessor
+    def id
+      @id.presence || random_id
+    end
+
+    # Methods to use in component views
+    # ---------------------------------
+
+    delegate :params, to: :helpers
+
+    # HTML and attribute definition and creation
+
+    # Helper to create the main element
+    def parent_element(**options)
+      @parent_element ||= begin
+        # Note: we cant mix phlex and view_component render contexts
+        klass = if self.class.ancestors.include?(Phlex::HTML)
+          RootComponent::UsingPhlexHTML
+        else
+          RootComponent::UsingViewComponent
+        end
+        klass.new(**stimulus_options_for_component(options))
+      end
+    end
+    alias_method :root, :parent_element
+
+    # FIXME: if we call them before `root` we will setup the root element before we intended
+    # The separation between component and root element is a bit messy. Might need rethinking.
+    delegate :action, :target, :named_classes, to: :root
+
+    # This can be overridden to return an array of extra class names
+    def element_classes
+    end
+
+    # A HTML class name that can helps identify the component type in the DOM or for styling purposes.
+    def component_class_name
+      self.class.component_name
+    end
+    alias_method :js_event_name_prefix, :component_class_name
+
+    # Generates the full list of HTML classes for the component
+    def render_classes(erb_defined_classes = nil)
+      # TODO: avoid pointless creation of arrays
+      base_classes = [component_class_name] + Array.wrap(element_classes)
+      base_classes += Array.wrap(erb_defined_classes) if erb_defined_classes
+      classes_on_component = attribute(:html_options)&.fetch(:class, nil)
+      base_classes += Array.wrap(classes_on_component) if classes_on_component
+      produce_style_classes(base_classes)
+    end
+
+    def stimulus_identifier
+      self.class.stimulus_identifier
+    end
+
+    # TODO: Move to caching module
+    # Component modified time which is combined with other cache key attributes to generate cache key for an instance
+    def component_modified_time
+      self.class.component_modified_time
+    end
+
+    # The `component` class name is used to create the controller name.
+    # The path of the Stimulus controller when none is explicitly set
+    def default_controller_path
+      self.class.identifier_name_path
+    end
+
+    protected
+
+    # Prepare the stimulus attributes for a StimulusComponent
+    def stimulus_options_for_component(options)
+      {
+        **options.except(:id, :element_tag, :html_options, :controller, :controllers, :actions, :targets, :named_classes, :data_maps),
+        id: respond_to?(:id) ? id : (attribute(:id) || options[:id]),
+        element_tag: attribute(:element_tag) || options[:element_tag] || :div,
+        html_options: prepare_html_options(options[:html_options]),
+        controllers: (
+          self.class.stimulus_controller? ? [default_controller_path] : []
+        ) + Array.wrap(options[:controllers]) + attribute(:controllers),
+        actions: attribute(:actions) + Array.wrap(options[:actions]),
+        targets: attribute(:targets) + Array.wrap(options[:targets]),
+        named_classes: merge_stimulus_option(options, :named_classes),
+        data_maps: prepare_stimulus_option(options, :data_maps)
+      }
+    end
+
+    private
+
+    def prepare_html_options(erb_options)
+      # Options should override in this order:
+      # - defined on component class methods (lowest priority)
+      # - defined by passing to component erb
+      # - defined by passing to component constructor (highest priority)
+      options = erb_options&.except(:class) || {}
+      classes_from_view = Array.wrap(erb_options[:class]) if erb_options&.key?(:class)
+      options[:class] = render_classes(classes_from_view)
+      options.merge!(attribute(:html_options).except(:class)) if attribute(:html_options)
+      options
+    end
+
+    # TODO: deprecate the ability to set via method on class (responds_to?) and just use component attributes
+    # or attributes passed to parent_element
+    def prepare_stimulus_option(options, name)
+      resolved = respond_to?(name) ? Array.wrap(send(name)) : []
+      resolved.concat(Array.wrap(attribute(name)))
+      resolved.concat(Array.wrap(options[name]))
+      resolved
+    end
+
+    def merge_stimulus_option(options, name)
+      (attribute(name) || {}).merge(options[name] || {})
+    end
+
+    def produce_style_classes(class_names)
+      dedupe_view_component_classes(class_names)
+    end
+
+    def template_path
+      self.class.template_path
+    end
+
+    def random_id
+      @random_id ||= "#{self.class.component_name}-#{StableId.next_id_in_sequence}"
+    end
+
+    CLASSNAME_SEPARATOR = " "
+
+    # Join all the various class definisions possible and dedupe
+    def dedupe_view_component_classes(html_classes)
+      html_classes.reject!(&:blank?)
+
+      # Join, then dedupe.
+      # This ensures that entries from the classes array such as "a b", "a", "b" are correctly deduped.
+      # Note we are trying to do this with less allocations to avoid GC churn
+      # classes = classes.join(" ").split(" ").uniq
+      html_classes.map! { |x| x.include?(CLASSNAME_SEPARATOR) ? x.split(CLASSNAME_SEPARATOR) : x }
+        .flatten!
+      html_classes.uniq!
+      html_classes.present? ? html_classes.join(CLASSNAME_SEPARATOR) : nil
+    end
+  end
+end

data/lib/vident/component.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "./attributes/not_typed"
+
+module Vident
+  module Component
+    extend ActiveSupport::Concern
+
+    included do
+      include Vident::Base
+      include Vident::Attributes::NotTyped
+
+      attribute :id, delegates: false
+      attribute :html_options, delegates: false
+      attribute :element_tag, delegates: false
+
+      # StimulusJS support
+      attribute :controllers, default: [], delegates: false
+      attribute :actions, default: [], delegates: false
+      attribute :targets, default: [], delegates: false
+      attribute :data_maps, default: [], delegates: false
+      attribute :named_classes, delegates: false
+    end
+
+    def initialize(attrs = {})
+      before_initialise(attrs)
+      prepare_attributes(attrs)
+      after_initialise
+      super()
+    end
+  end
+end

data/lib/vident/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Vident
+  # Include rake tasks
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load "tasks/vident.rake"
+    end
+  end
+end