view_component 2.49.1 → 3.23.2

data/lib/view_component/slotable.rb

@@ -1,147 +1,444 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
-
+require "active_support/inflector/inflections"
 require "view_component/slot"
 
 module ViewComponent
   module Slotable
     extend ActiveSupport::Concern
 
+    RESERVED_NAMES = {
+      singular: %i[content render].freeze,
+      plural: %i[contents renders].freeze
+    }.freeze
+
+    # Setup component slot state
     included do
       # Hash of registered Slots
-      class_attribute :slots
-      self.slots = {}
+      class_attribute :registered_slots
+      self.registered_slots = {}
     end
 
     class_methods do
-      # support initializing slots as:
-      #
-      # with_slot(
-      #   :header,
-      #   collection: true|false,
-      #   class_name: "Header" # class name string, used to instantiate Slot
-      # )
-      def with_slot(*slot_names, collection: false, class_name: nil)
-        ActiveSupport::Deprecation.warn(
-          "`with_slot` is deprecated and will be removed in ViewComponent v3.0.0.\n" \
-          "Use the new slots API (https://viewcomponent.org/guide/slots.html) instead."
-        )
-
-        slot_names.each do |slot_name|
-          # Ensure slot_name isn't already declared
-          if self.slots.key?(slot_name)
-            raise ArgumentError.new("#{slot_name} slot declared multiple times")
+      ##
+      # Registers a sub-component
+      #
+      # = Example
+      #
+      #   renders_one :header -> (classes:) do
+      #     HeaderComponent.new(classes: classes)
+      #   end
+      #
+      #   # OR
+      #
+      #   renders_one :header, HeaderComponent
+      #
+      #   where `HeaderComponent` is defined as:
+      #
+      #   class HeaderComponent < ViewComponent::Base
+      #     def initialize(classes:)
+      #       @classes = classes
+      #     end
+      #   end
+      #
+      #   and has the following template:
+      #
+      #   <header class="<%= @classes %>">
+      #     <%= content %>
+      #   </header>
+      #
+      # = Rendering sub-component content
+      #
+      # The component's sidecar template can access the sub-component by calling a
+      # helper method with the same name as the sub-component.
+      #
+      #   <h1>
+      #     <%= header do %>
+      #       My header title
+      #     <% end %>
+      #   </h1>
+      #
+      # = Setting sub-component content
+      #
+      # Consumers of the component can render a sub-component by calling a
+      # helper method with the same name as the slot prefixed with `with_`.
+      #
+      #   <%= render_inline(MyComponent.new) do |component| %>
+      #     <% component.with_header(classes: "Foo") do %>
+      #       <p>Bar</p>
+      #     <% end %>
+      #   <% end %>
+      #
+      # Additionally, content can be set by calling `with_SLOT_NAME_content`
+      # on the component instance.
+      #
+      #   <%= render_inline(MyComponent.new.with_header_content("Foo")) %>
+      def renders_one(slot_name, callable = nil)
+        validate_singular_slot_name(slot_name)
+
+        if callable.is_a?(Hash) && callable.key?(:types)
+          register_polymorphic_slot(slot_name, callable[:types], collection: false)
+        else
+          validate_plural_slot_name(ActiveSupport::Inflector.pluralize(slot_name).to_sym)
+
+          setter_method_name = :"with_#{slot_name}"
+
+          define_method setter_method_name do |*args, &block|
+            set_slot(slot_name, nil, *args, &block)
           end
+          ruby2_keywords(setter_method_name) if respond_to?(:ruby2_keywords, true)
 
-          # Ensure slot name isn't :content
-          if slot_name == :content
-            raise ArgumentError.new ":content is a reserved slot name. Please use another name, such as ':body'"
+          self::GeneratedSlotMethods.define_method slot_name do
+            get_slot(slot_name)
           end
 
-          # Set the name of the method used to access the Slot(s)
-          accessor_name =
-            if collection
-              # If Slot is a collection, set the accessor
-              # name to the pluralized form of the slot name
-              # For example: :tab => :tabs
-              ActiveSupport::Inflector.pluralize(slot_name)
-            else
-              slot_name
-            end
+          self::GeneratedSlotMethods.define_method :"#{slot_name}?" do
+            get_slot(slot_name).present?
+          end
 
-          instance_variable_name = "@#{accessor_name}"
+          define_method :"with_#{slot_name}_content" do |content|
+            send(setter_method_name) { content.to_s }
 
-          # If the slot is a collection, define an accesor that defaults to an empty array
-          if collection
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def #{accessor_name}
-                content unless content_evaluated? # ensure content is loaded so slots will be defined
-                #{instance_variable_name} ||= []
-              end
-            RUBY
-          else
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def #{accessor_name}
-                content unless content_evaluated? # ensure content is loaded so slots will be defined
-                #{instance_variable_name} if defined?(#{instance_variable_name})
+            self
+          end
+
+          register_slot(slot_name, collection: false, callable: callable)
+        end
+      end
+
+      ##
+      # Registers a collection sub-component
+      #
+      # = Example
+      #
+      #   renders_many :items, -> (name:) { ItemComponent.new(name: name }
+      #
+      #   # OR
+      #
+      #   renders_many :items, ItemComponent
+      #
+      # = Rendering sub-components
+      #
+      # The component's sidecar template can access the slot by calling a
+      # helper method with the same name as the slot.
+      #
+      #   <h1>
+      #     <% items.each do |item| %>
+      #       <%= item %>
+      #     <% end %>
+      #   </h1>
+      #
+      # = Setting sub-component content
+      #
+      # Consumers of the component can set the content of a slot by calling a
+      # helper method with the same name as the slot prefixed with `with_`. The
+      # method can be called multiple times to append to the slot.
+      #
+      #   <%= render_inline(MyComponent.new) do |component| %>
+      #     <% component.with_item(name: "Foo") do %>
+      #       <p>One</p>
+      #     <% end %>
+      #
+      #     <% component.with_item(name: "Bar") do %>
+      #       <p>two</p>
+      #     <% end %>
+      #   <% end %>
+      def renders_many(slot_name, callable = nil)
+        validate_plural_slot_name(slot_name)
+
+        if callable.is_a?(Hash) && callable.key?(:types)
+          register_polymorphic_slot(slot_name, callable[:types], collection: true)
+        else
+          singular_name = ActiveSupport::Inflector.singularize(slot_name)
+          validate_singular_slot_name(ActiveSupport::Inflector.singularize(slot_name).to_sym)
+
+          setter_method_name = :"with_#{singular_name}"
+
+          define_method setter_method_name do |*args, &block|
+            set_slot(slot_name, nil, *args, &block)
+          end
+          ruby2_keywords(setter_method_name) if respond_to?(:ruby2_keywords, true)
+
+          define_method :"with_#{singular_name}_content" do |content|
+            send(setter_method_name) { content.to_s }
+
+            self
+          end
+
+          define_method :"with_#{slot_name}" do |collection_args = nil, &block|
+            collection_args.map do |args|
+              if args.respond_to?(:to_hash)
+                set_slot(slot_name, nil, **args, &block)
+              else
+                set_slot(slot_name, nil, *args, &block)
               end
-            RUBY
+            end
+          end
+
+          self::GeneratedSlotMethods.define_method slot_name do
+            get_slot(slot_name)
+          end
+
+          self::GeneratedSlotMethods.define_method :"#{slot_name}?" do
+            get_slot(slot_name).present?
           end
 
-          # Default class_name to ViewComponent::Slot
-          class_name = "ViewComponent::Slot" unless class_name.present?
+          register_slot(slot_name, collection: true, callable: callable)
+        end
+      end
 
-          # Register the slot on the component
-          self.slots[slot_name] = {
-            class_name: class_name,
-            instance_variable_name: instance_variable_name,
-            collection: collection
-          }
+      def slot_type(slot_name)
+        registered_slot = registered_slots[slot_name]
+        if registered_slot
+          registered_slot[:collection] ? :collection : :single
+        else
+          plural_slot_name = ActiveSupport::Inflector.pluralize(slot_name).to_sym
+          plural_registered_slot = registered_slots[plural_slot_name]
+          plural_registered_slot&.fetch(:collection) ? :collection_item : nil
         end
       end
 
       def inherited(child)
         # Clone slot configuration into child class
         # see #test_slots_pollution
-        child.slots = self.slots.clone
+        child.registered_slots = registered_slots.clone
+
+        # Add a module for slot methods, allowing them to be overriden by the component class
+        # see #test_slot_name_can_be_overriden
+        unless child.const_defined?(:GeneratedSlotMethods, false)
+          generated_slot_methods = Module.new
+          child.const_set(:GeneratedSlotMethods, generated_slot_methods)
+          child.include generated_slot_methods
+        end
 
         super
       end
-    end
 
-    # Build a Slot instance on a component,
-    # exposing it for use inside the
-    # component template.
-    #
-    # slot: Name of Slot, in symbol form
-    # **args: Arguments to be passed to Slot initializer
-    #
-    # For example:
-    # <%= render(SlotsComponent.new) do |component| %>
-    #   <% component.slot(:footer, class_names: "footer-class") do %>
-    #     <p>This is my footer!</p>
-    #   <% end %>
-    # <% end %>
-    #
-    def slot(slot_name, **args, &block)
-      # Raise ArgumentError if `slot` doesn't exist
-      unless slots.keys.include?(slot_name)
-        raise ArgumentError.new "Unknown slot '#{slot_name}' - expected one of '#{slots.keys}'"
+      def register_polymorphic_slot(slot_name, types, collection:)
+        self::GeneratedSlotMethods.define_method(slot_name) do
+          get_slot(slot_name)
+        end
+
+        self::GeneratedSlotMethods.define_method(:"#{slot_name}?") do
+          get_slot(slot_name).present?
+        end
+
+        renderable_hash = types.each_with_object({}) do |(poly_type, poly_attributes_or_callable), memo|
+          if poly_attributes_or_callable.is_a?(Hash)
+            poly_callable = poly_attributes_or_callable[:renders]
+            poly_slot_name = poly_attributes_or_callable[:as]
+          else
+            poly_callable = poly_attributes_or_callable
+            poly_slot_name = nil
+          end
+
+          poly_slot_name ||=
+            if collection
+              "#{ActiveSupport::Inflector.singularize(slot_name)}_#{poly_type}"
+            else
+              "#{slot_name}_#{poly_type}"
+            end
+
+          memo[poly_type] = define_slot(
+            poly_slot_name, collection: collection, callable: poly_callable
+          )
+
+          setter_method_name = :"with_#{poly_slot_name}"
+
+          if instance_methods.include?(setter_method_name)
+            raise AlreadyDefinedPolymorphicSlotSetterError.new(setter_method_name, poly_slot_name)
+          end
+
+          define_method(setter_method_name) do |*args, &block|
+            set_polymorphic_slot(slot_name, poly_type, *args, &block)
+          end
+          ruby2_keywords(setter_method_name) if respond_to?(:ruby2_keywords, true)
+
+          define_method :"with_#{poly_slot_name}_content" do |content|
+            send(setter_method_name) { content.to_s }
+
+            self
+          end
+        end
+
+        registered_slots[slot_name] = {
+          collection: collection,
+          renderable_hash: renderable_hash
+        }
+      end
+
+      # Called by the compiler, as instance methods are not defined when slots are first registered
+      def register_default_slots
+        registered_slots.each do |slot_name, config|
+          config[:default_method] = instance_methods.find { |method_name| method_name == :"default_#{slot_name}" }
+
+          registered_slots[slot_name] = config
+        end
+      end
+
+      private
+
+      def register_slot(slot_name, **kwargs)
+        registered_slots[slot_name] = define_slot(slot_name, **kwargs)
+      end
+
+      def define_slot(slot_name, collection:, callable:)
+        slot = {collection: collection}
+        return slot unless callable
+
+        # If callable responds to `render_in`, we set it on the slot as a renderable
+        if callable.respond_to?(:method_defined?) && callable.method_defined?(:render_in)
+          slot[:renderable] = callable
+        elsif callable.is_a?(String)
+          # If callable is a string, we assume it's referencing an internal class
+          slot[:renderable_class_name] = callable
+        elsif callable.respond_to?(:call)
+          # If slot doesn't respond to `render_in`, we assume it's a proc,
+          # define a method, and save a reference to it to call when setting
+          method_name = :"_call_#{slot_name}"
+          define_method method_name, &callable
+          slot[:renderable_function] = instance_method(method_name)
+        else
+          raise(InvalidSlotDefinitionError)
+        end
+
+        slot
+      end
+
+      def validate_plural_slot_name(slot_name)
+        if RESERVED_NAMES[:plural].include?(slot_name.to_sym)
+          raise ReservedPluralSlotNameError.new(name, slot_name)
+        end
+
+        raise_if_slot_name_uncountable(slot_name)
+        raise_if_slot_conflicts_with_call(slot_name)
+        raise_if_slot_ends_with_question_mark(slot_name)
+        raise_if_slot_registered(slot_name)
+      end
+
+      def validate_singular_slot_name(slot_name)
+        if slot_name.to_sym == :content
+          raise ContentSlotNameError.new(name)
+        end
+
+        if RESERVED_NAMES[:singular].include?(slot_name.to_sym)
+          raise ReservedSingularSlotNameError.new(name, slot_name)
+        end
+
+        raise_if_slot_conflicts_with_call(slot_name)
+        raise_if_slot_ends_with_question_mark(slot_name)
+        raise_if_slot_registered(slot_name)
       end
 
-      slot = slots[slot_name]
+      def raise_if_slot_registered(slot_name)
+        if registered_slots.key?(slot_name)
+          raise RedefinedSlotError.new(name, slot_name)
+        end
+      end
 
-      # The class name of the Slot, such as Header
-      slot_class = self.class.const_get(slot[:class_name])
+      def raise_if_slot_ends_with_question_mark(slot_name)
+        raise SlotPredicateNameError.new(name, slot_name) if slot_name.to_s.end_with?("?")
+      end
 
-      unless slot_class <= ViewComponent::Slot
-        raise ArgumentError.new "#{slot[:class_name]} must inherit from ViewComponent::Slot"
+      def raise_if_slot_conflicts_with_call(slot_name)
+        if slot_name.start_with?("call_")
+          raise InvalidSlotNameError, "Slot cannot start with 'call_'. Please rename #{slot_name}"
+        end
       end
 
-      # Instantiate Slot class, accommodating Slots that don't accept arguments
-      slot_instance = args.present? ? slot_class.new(**args) : slot_class.new
+      def raise_if_slot_name_uncountable(slot_name)
+        slot_name = slot_name.to_s
+        if slot_name.pluralize == slot_name.singularize
+          raise UncountableSlotNameError.new(name, slot_name)
+        end
+      end
+    end
+
+    def get_slot(slot_name)
+      content unless content_evaluated? # ensure content is loaded so slots will be defined
+
+      slot = self.class.registered_slots[slot_name]
+      @__vc_set_slots ||= {}
 
-      # Capture block and assign to slot_instance#content
-      # rubocop:disable Rails/OutputSafety
-      slot_instance.content = view_context.capture(&block).to_s.strip.html_safe if block_given?
+      if @__vc_set_slots[slot_name]
+        return @__vc_set_slots[slot_name]
+      end
 
       if slot[:collection]
-        # Initialize instance variable as an empty array
-        # if slot is a collection and has yet to be initialized
-        unless instance_variable_defined?(slot[:instance_variable_name])
-          instance_variable_set(slot[:instance_variable_name], [])
+        []
+      end
+    end
+
+    def set_slot(slot_name, slot_definition = nil, *args, &block)
+      slot_definition ||= self.class.registered_slots[slot_name]
+      slot = Slot.new(self)
+
+      # Passing the block to the sub-component wrapper like this has two
+      # benefits:
+      #
+      # 1. If this is a `content_area` style sub-component, we will render the
+      # block via the `slot`
+      #
+      # 2. Since we have to pass block content to components when calling
+      # `render`, evaluating the block here would require us to call
+      # `view_context.capture` twice, which is slower
+      slot.__vc_content_block = block if block
+
+      # If class
+      if slot_definition[:renderable]
+        slot.__vc_component_instance = slot_definition[:renderable].new(*args)
+      # If class name as a string
+      elsif slot_definition[:renderable_class_name]
+        slot.__vc_component_instance =
+          self.class.const_get(slot_definition[:renderable_class_name]).new(*args)
+      # If passed a lambda
+      elsif slot_definition[:renderable_function]
+        # Use `bind(self)` to ensure lambda is executed in the context of the
+        # current component. This is necessary to allow the lambda to access helper
+        # methods like `content_tag` as well as parent component state.
+        renderable_function = slot_definition[:renderable_function].bind(self)
+        renderable_value =
+          if block
+            renderable_function.call(*args) do |*rargs|
+              view_context.capture(*rargs, &block)
+            end
+          else
+            renderable_function.call(*args)
+          end
+
+        # Function calls can return components, so if it's a component handle it specially
+        if renderable_value.respond_to?(:render_in)
+          slot.__vc_component_instance = renderable_value
+        else
+          slot.__vc_content = renderable_value
         end
+      end
+
+      @__vc_set_slots ||= {}
 
-        # Append Slot instance to collection accessor Array
-        instance_variable_get(slot[:instance_variable_name]) << slot_instance
+      if slot_definition[:collection]
+        @__vc_set_slots[slot_name] ||= []
+        @__vc_set_slots[slot_name].push(slot)
       else
-        # Assign the Slot instance to the slot accessor
-        instance_variable_set(slot[:instance_variable_name], slot_instance)
+        @__vc_set_slots[slot_name] = slot
+      end
+
+      slot
+    end
+    ruby2_keywords(:set_slot) if respond_to?(:ruby2_keywords, true)
+
+    def set_polymorphic_slot(slot_name, poly_type = nil, *args, &block)
+      slot_definition = self.class.registered_slots[slot_name]
+
+      if !slot_definition[:collection] && defined?(@__vc_set_slots) && @__vc_set_slots[slot_name]
+        raise ContentAlreadySetForPolymorphicSlotError.new(slot_name)
       end
 
-      # Return nil, as this method shouldn't output anything to the view itself.
-      nil
+      poly_def = slot_definition[:renderable_hash][poly_type]
+
+      set_slot(slot_name, poly_def, *args, &block)
     end
+    ruby2_keywords(:set_polymorphic_slot) if respond_to?(:ruby2_keywords, true)
   end
 end

data/lib/view_component/slotable_default.rb

@@ -0,0 +1,20 @@
+module ViewComponent
+  module SlotableDefault
+    def get_slot(slot_name)
+      @__vc_set_slots ||= {}
+
+      return super unless !@__vc_set_slots[slot_name] && (default_method = registered_slots[slot_name][:default_method])
+
+      renderable_value = send(default_method)
+      slot = Slot.new(self)
+
+      if renderable_value.respond_to?(:render_in)
+        slot.__vc_component_instance = renderable_value
+      else
+        slot.__vc_content = renderable_value
+      end
+
+      slot
+    end
+  end
+end

data/lib/view_component/system_test_case.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_support/test_case"
+
+module ViewComponent
+  class SystemTestCase < ActionDispatch::SystemTestCase
+    include ViewComponent::SystemTestHelpers
+
+    def page
+      Capybara.current_session
+    end
+  end
+end

data/lib/view_component/system_test_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module SystemTestHelpers
+    include TestHelpers
+
+    #
+    # Returns a block that can be used to visit the path of the inline rendered component.
+    # @param fragment [Nokogiri::Fragment] The fragment returned from `render_inline`.
+    # @param layout [String] The (optional) layout to use.
+    # @return [Proc] A block that can be used to visit the path of the inline rendered component.
+    def with_rendered_component_path(fragment, layout: false, &block)
+      file = Tempfile.new(
+        ["rendered_#{fragment.class.name}", ".html"],
+        ViewComponentsSystemTestController.temp_dir
+      )
+      begin
+        file.write(vc_test_controller.render_to_string(html: fragment.to_html.html_safe, layout: layout))
+        file.rewind
+
+        block.call("/_system_test_entrypoint?file=#{file.path.split("/").last}")
+      ensure
+        file.unlink
+      end
+    end
+  end
+end