view_component 2.82.0 → 3.0.0.rc2

data/lib/view_component/slotable.rb

@@ -1,145 +1,396 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
-
 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)
-        ViewComponent::Deprecation.deprecation_warning(
-          "`with_slot`", "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 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 %>
+      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)
+
+          define_method :"with_#{slot_name}" do |*args, &block|
+            set_slot(slot_name, nil, *args, &block)
           end
+          ruby2_keywords(:"with_#{slot_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'"
+          define_method slot_name do |*args, &block|
+            get_slot(slot_name)
           end
+          ruby2_keywords(slot_name.to_sym) if respond_to?(:ruby2_keywords, true)
 
-          # 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
+          define_method "#{slot_name}?" do
+            get_slot(slot_name).present?
+          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)
+
+          define_method :"with_#{singular_name}" do |*args, &block|
+            set_slot(slot_name, nil, *args, &block)
+          end
+          ruby2_keywords(:"with_#{singular_name}") if respond_to?(:ruby2_keywords, true)
+
+          define_method :"with_#{slot_name}" do |collection_args = nil, &block|
+            collection_args.map do |args|
+              set_slot(slot_name, nil, **args, &block)
             end
+          end
 
-          instance_variable_name = "@#{accessor_name}"
+          define_method slot_name do |collection_args = nil, &block|
+            get_slot(slot_name)
+          end
 
-          # 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})
-              end
-            RUBY
+          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
-          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
 
+      # Clone slot configuration into child class
+      # see #test_slots_pollution
       def inherited(child)
-        # Clone slot configuration into child class
-        # see #test_slots_pollution
-        child.slots = slots.clone
-
+        child.registered_slots = registered_slots.clone
         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.key?(slot_name)
-        raise ArgumentError.new "Unknown slot '#{slot_name}' - expected one of '#{slots.keys}'"
+      def register_polymorphic_slot(slot_name, types, collection:)
+        unless types.empty?
+          getter_name = slot_name
+
+          define_method(getter_name) do
+            get_slot(slot_name)
+          end
+
+          define_method("#{getter_name}?") do
+            get_slot(slot_name).present?
+          end
+        end
+
+        renderable_hash = types.each_with_object({}) do |(poly_type, poly_callable), memo|
+          memo[poly_type] = define_slot(
+            "#{slot_name}_#{poly_type}", collection: collection, callable: poly_callable
+          )
+
+          setter_name =
+            if collection
+              "#{ActiveSupport::Inflector.singularize(slot_name)}_#{poly_type}"
+            else
+              "#{slot_name}_#{poly_type}"
+            end
+
+          define_method("with_#{setter_name}") do |*args, &block|
+            set_polymorphic_slot(slot_name, poly_type, *args, &block)
+          end
+          ruby2_keywords(:"with_#{setter_name}") if respond_to?(:ruby2_keywords, true)
+        end
+
+        registered_slots[slot_name] = {
+          collection: collection,
+          renderable_hash: renderable_hash
+        }
+      end
+
+      private
+
+      def register_slot(slot_name, **kwargs)
+        registered_slots[slot_name] = define_slot(slot_name, **kwargs)
       end
 
-      slot = slots[slot_name]
+      def define_slot(slot_name, collection:, callable:)
+        # Setup basic slot data
+        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(
+            ArgumentError,
+            "invalid slot definition. Please pass a class, string, or callable (i.e. proc, lambda, etc)"
+          )
+        end
+
+        slot
+      end
 
-      # The class name of the Slot, such as Header
-      slot_class = self.class.const_get(slot[:class_name])
+      def validate_plural_slot_name(slot_name)
+        if RESERVED_NAMES[:plural].include?(slot_name.to_sym)
+          raise ArgumentError.new(
+            "#{self} declares a slot named #{slot_name}, which is a reserved word in the ViewComponent framework.\n\n" \
+            "To fix this issue, choose a different name."
+          )
+        end
 
-      unless slot_class <= ViewComponent::Slot
-        raise ArgumentError.new "#{slot[:class_name]} must inherit from ViewComponent::Slot"
+        raise_if_slot_ends_with_question_mark(slot_name)
+        raise_if_slot_registered(slot_name)
       end
 
-      # Instantiate Slot class, accommodating Slots that don't accept arguments
-      slot_instance = args.present? ? slot_class.new(**args) : slot_class.new
+      def validate_singular_slot_name(slot_name)
+        if slot_name.to_sym == :content
+          raise ArgumentError.new(
+            "#{self} declares a slot named content, which is a reserved word in ViewComponent.\n\n" \
+            "Content passed to a ViewComponent as a block is captured and assigned to the `content` accessor without having to create an explicit slot.\n\n" \
+            "To fix this issue, either use the `content` accessor directly or choose a different slot name."
+          )
+        end
 
-      # Capture block and assign to slot_instance#content
-      slot_instance.content = view_context.capture(&block).to_s.strip.html_safe if block
+        if RESERVED_NAMES[:singular].include?(slot_name.to_sym)
+          raise ArgumentError.new(
+            "#{self} declares a slot named #{slot_name}, which is a reserved word in the ViewComponent framework.\n\n" \
+            "To fix this issue, choose a different name."
+          )
+        end
+
+        raise_if_slot_ends_with_question_mark(slot_name)
+        raise_if_slot_registered(slot_name)
+      end
+
+      def raise_if_slot_registered(slot_name)
+        if registered_slots.key?(slot_name)
+          # TODO remove? This breaks overriding slots when slots are inherited
+          raise ArgumentError.new(
+            "#{self} declares the #{slot_name} slot multiple times.\n\n" \
+            "To fix this issue, choose a different slot name."
+          )
+        end
+      end
+
+      def raise_if_slot_ends_with_question_mark(slot_name)
+        if slot_name.to_s.ends_with?("?")
+          raise ArgumentError.new(
+            "#{self} declares a slot named #{slot_name}, which ends with a question mark.\n\n" \
+            "This is not allowed because the ViewComponent framework already provides predicate " \
+            "methods ending in `?`.\n\n" \
+            "To fix this issue, choose a different 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 ||= {}
+
+      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've 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
 
-      # Return nil, as this method shouldn't output anything to the view itself.
-      nil
+      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 ArgumentError, "content for slot '#{slot_name}' has already been provided"
+      end
+
+      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/system_test_helpers.rb

@@ -15,7 +15,7 @@ module ViewComponent
 
       file = Tempfile.new(["rendered_#{fragment.class.name}", ".html"], "tmp/view_components/")
       begin
-        file.write(controller.render_to_string(html: fragment.to_html.html_safe, layout: layout))
+        file.write(__vc_test_helpers_controller.render_to_string(html: fragment.to_html.html_safe, layout: layout))
         file.rewind
 
         block.call("/_system_test_entrypoint?file=#{file.path.split("/").last}")

data/lib/view_component/test_helpers.rb

@@ -28,17 +28,10 @@ module ViewComponent
       # :nocov:
     end
 
-    # @private
-    attr_reader :rendered_content
-
     # Returns the result of a render_inline call.
     #
-    # @return [String]
-    def rendered_component
-      ViewComponent::Deprecation.deprecation_warning("`rendered_component`", :"`page`")
-
-      rendered_content
-    end
+    # @return [ActionView::OutputBuffer]
+    attr_reader :rendered_content
 
     # Render a component inline. Internally sets `page` to be a `Capybara::Node::Simple`,
     # allowing for Capybara assertions to be used:
@@ -54,9 +47,9 @@ module ViewComponent
       @page = nil
       @rendered_content =
         if Rails.version.to_f >= 6.1
-          controller.view_context.render(component, args, &block)
+          __vc_test_helpers_controller.view_context.render(component, args, &block)
         else
-          controller.view_context.render_component(component, &block)
+          __vc_test_helpers_controller.view_context.render_component(component, &block)
         end
 
       Nokogiri::HTML.fragment(@rendered_content)
@@ -81,8 +74,8 @@ module ViewComponent
     # @param from [ViewComponent::Preview] The class of the preview to be rendered.
     # @param params [Hash] Parameters to be passed to the preview.
     # @return [Nokogiri::HTML]
-    def render_preview(name, from: preview_class, params: {})
-      previews_controller = build_controller(Rails.application.config.view_component.preview_controller.constantize)
+    def render_preview(name, from: __vc_test_helpers_preview_class, params: {})
+      previews_controller = __vc_test_helpers_build_controller(Rails.application.config.view_component.preview_controller.constantize)
 
       # From what I can tell, it's not possible to overwrite all request parameters
       # at once, so we set them individually here.
@@ -112,26 +105,11 @@ module ViewComponent
     # ```
     def render_in_view_context(*args, &block)
       @page = nil
-      @rendered_content = controller.view_context.instance_exec(*args, &block)
+      @rendered_content = __vc_test_helpers_controller.view_context.instance_exec(*args, &block)
       Nokogiri::HTML.fragment(@rendered_content)
     end
     ruby2_keywords(:render_in_view_context) if respond_to?(:ruby2_keywords, true)
 
-    # @private
-    def controller
-      @controller ||= build_controller(Base.test_controller.constantize)
-    end
-
-    # @private
-    def request
-      @request ||=
-        begin
-          request = ActionDispatch::TestRequest.create
-          request.session = ActionController::TestSession.new
-          request
-        end
-    end
-
     # Set the Action Pack request variant for the given block:
     #
     # ```ruby
@@ -142,12 +120,12 @@ module ViewComponent
     #
     # @param variant [Symbol] The variant to be set for the provided block.
     def with_variant(variant)
-      old_variants = controller.view_context.lookup_context.variants
+      old_variants = __vc_test_helpers_controller.view_context.lookup_context.variants
 
-      controller.view_context.lookup_context.variants = variant
+      __vc_test_helpers_controller.view_context.lookup_context.variants = variant
       yield
     ensure
-      controller.view_context.lookup_context.variants = old_variants
+      __vc_test_helpers_controller.view_context.lookup_context.variants = old_variants
     end
 
     # Set the controller to be used while executing the given block,
@@ -161,12 +139,12 @@ module ViewComponent
     #
     # @param klass [ActionController::Base] The controller to be used.
     def with_controller_class(klass)
-      old_controller = defined?(@controller) && @controller
+      old_controller = defined?(@__vc_test_helpers_controller) && @__vc_test_helpers_controller
 
-      @controller = build_controller(klass)
+      @__vc_test_helpers_controller = __vc_test_helpers_build_controller(klass)
       yield
     ensure
-      @controller = old_controller
+      @__vc_test_helpers_controller = old_controller
     end
 
     # Set the URL of the current request (such as when using request-dependent path helpers):
@@ -179,34 +157,47 @@ module ViewComponent
     #
     # @param path [String] The path to set for the current request.
     def with_request_url(path)
-      old_request_path_info = request.path_info
-      old_request_path_parameters = request.path_parameters
-      old_request_query_parameters = request.query_parameters
-      old_request_query_string = request.query_string
-      old_controller = defined?(@controller) && @controller
+      old_request_path_info = __vc_test_helpers_request.path_info
+      old_request_path_parameters = __vc_test_helpers_request.path_parameters
+      old_request_query_parameters = __vc_test_helpers_request.query_parameters
+      old_request_query_string = __vc_test_helpers_request.query_string
+      old_controller = defined?(@__vc_test_helpers_controller) && @__vc_test_helpers_controller
 
       path, query = path.split("?", 2)
-      request.path_info = path
-      request.path_parameters = Rails.application.routes.recognize_path_with_request(request, path, {})
-      request.set_header("action_dispatch.request.query_parameters", Rack::Utils.parse_nested_query(query))
-      request.set_header(Rack::QUERY_STRING, query)
+      __vc_test_helpers_request.path_info = path
+      __vc_test_helpers_request.path_parameters = Rails.application.routes.recognize_path_with_request(__vc_test_helpers_request, path, {})
+      __vc_test_helpers_request.set_header("action_dispatch.request.query_parameters", Rack::Utils.parse_nested_query(query))
+      __vc_test_helpers_request.set_header(Rack::QUERY_STRING, query)
       yield
     ensure
-      request.path_info = old_request_path_info
-      request.path_parameters = old_request_path_parameters
-      request.set_header("action_dispatch.request.query_parameters", old_request_query_parameters)
-      request.set_header(Rack::QUERY_STRING, old_request_query_string)
-      @controller = old_controller
+      __vc_test_helpers_request.path_info = old_request_path_info
+      __vc_test_helpers_request.path_parameters = old_request_path_parameters
+      __vc_test_helpers_request.set_header("action_dispatch.request.query_parameters", old_request_query_parameters)
+      __vc_test_helpers_request.set_header(Rack::QUERY_STRING, old_request_query_string)
+      @__vc_test_helpers_controller = old_controller
     end
 
-    # @private
-    def build_controller(klass)
-      klass.new.tap { |c| c.request = request }.extend(Rails.application.routes.url_helpers)
+    # Note: We prefix private methods here to prevent collisions in consumer's tests.
+    private
+
+    def __vc_test_helpers_controller
+      @__vc_test_helpers_controller ||= __vc_test_helpers_build_controller(Base.test_controller.constantize)
     end
 
-    private
+    def __vc_test_helpers_request
+      @__vc_test_helpers_request ||=
+        begin
+          out = ActionDispatch::TestRequest.create
+          out.session = ActionController::TestSession.new
+          out
+        end
+    end
+
+    def __vc_test_helpers_build_controller(klass)
+      klass.new.tap { |c| c.request = __vc_test_helpers_request }.extend(Rails.application.routes.url_helpers)
+    end
 
-    def preview_class
+    def __vc_test_helpers_preview_class
       result = if respond_to?(:described_class)
         raise "`render_preview` expected a described_class, but it is nil." if described_class.nil?