view_component 3.0.0.rc1 → 3.0.0.rc3

data/lib/view_component/slotable.rb

@@ -1,80 +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
-      def inherited(child)
-        # Clone slot configuration into child class
-        # see #test_slots_pollution
-        child.slots = slots.clone
+      ##
+      # 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)
+
+          define_method slot_name do |*args, &block|
+            get_slot(slot_name)
+          end
+          ruby2_keywords(slot_name.to_sym) if respond_to?(:ruby2_keywords, true)
+
+          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
 
+          define_method slot_name do |collection_args = nil, &block|
+            get_slot(slot_name)
+          end
+
+          define_method "#{slot_name}?" do
+            get_slot(slot_name).present?
+          end
+
+          register_slot(slot_name, collection: true, callable: callable)
+        end
+      end
+
+      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)
+        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
 
-      slot = slots[slot_name]
+      private
+
+      def register_slot(slot_name, **kwargs)
+        registered_slots[slot_name] = define_slot(slot_name, **kwargs)
+      end
 
-      # The class name of the Slot, such as Header
-      slot_class = self.class.const_get(slot[:class_name])
+      def define_slot(slot_name, collection:, callable:)
+        # Setup basic slot data
+        slot = {
+          collection: collection
+        }
+        return slot unless callable
 
-      unless slot_class <= ViewComponent::Slot
-        raise ArgumentError.new "#{slot[:class_name]} must inherit from ViewComponent::Slot"
+        # 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
+
+      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
+
+        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 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
+
+        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
 
-      # Instantiate Slot class, accommodating Slots that don't accept arguments
-      slot_instance = args.present? ? slot_class.new(**args) : slot_class.new
+      slot = self.class.registered_slots[slot_name]
+      @__vc_set_slots ||= {}
 
-      # Capture block and assign to slot_instance#content
-      slot_instance.content = view_context.capture(&block).to_s.strip.html_safe if block
+      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
+
+      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
 
-      # 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/system_test_helpers.rb

@@ -10,12 +10,12 @@ module ViewComponent
     # @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)
-      # Add './tmp/view_components/' directory if it doesn't exist to store the rendered component HTML
-      FileUtils.mkdir_p("./tmp/view_components/") unless Dir.exist?("./tmp/view_components/")
-
-      file = Tempfile.new(["rendered_#{fragment.class.name}", ".html"], "tmp/view_components/")
+      file = Tempfile.new(
+        ["rendered_#{fragment.class.name}", ".html"],
+        ViewComponentsSystemTestController::TEMP_DIR
+      )
       begin
-        file.write(controller.render_to_string(html: fragment.to_html.html_safe, layout: layout))
+        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}")

data/lib/view_component/test_helpers.rb

@@ -28,7 +28,9 @@ module ViewComponent
       # :nocov:
     end
 
-    # @private
+    # Returns the result of a render_inline call.
+    #
+    # @return [ActionView::OutputBuffer]
     attr_reader :rendered_content
 
     # Render a component inline. Internally sets `page` to be a `Capybara::Node::Simple`,
@@ -45,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_controller.view_context.render(component, args, &block)
         else
-          controller.view_context.render_component(component, &block)
+          vc_test_controller.view_context.render_component(component, &block)
         end
 
       Nokogiri::HTML.fragment(@rendered_content)
@@ -72,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.
@@ -103,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_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
@@ -133,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_controller.view_context.lookup_context.variants
 
-      controller.view_context.lookup_context.variants = variant
+      vc_test_controller.view_context.lookup_context.variants = variant
       yield
     ensure
-      controller.view_context.lookup_context.variants = old_variants
+      vc_test_controller.view_context.lookup_context.variants = old_variants
     end
 
     # Set the controller to be used while executing the given block,
@@ -152,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_controller) && @vc_test_controller
 
-      @controller = build_controller(klass)
+      @vc_test_controller = __vc_test_helpers_build_controller(klass)
       yield
     ensure
-      @controller = old_controller
+      @vc_test_controller = old_controller
     end
 
     # Set the URL of the current request (such as when using request-dependent path helpers):
@@ -170,34 +157,58 @@ 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_controller) && @vc_test_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_controller = old_controller
     end
 
-    # @private
-    def build_controller(klass)
-      klass.new.tap { |c| c.request = request }.extend(Rails.application.routes.url_helpers)
+    # Access the controller used by `render_inline`:
+    #
+    # ```ruby
+    # test "logged out user sees login link" do
+    #   vc_test_controller.expects(:logged_in?).at_least_once.returns(false)
+    #   render_inline(LoginComponent.new)
+    #   assert_selector("[aria-label='You must be signed in']")
+    # end
+    # ```
+    #
+    # @return [ActionController::Base]
+    def vc_test_controller
+      @vc_test_controller ||= __vc_test_helpers_build_controller(Base.test_controller.constantize)
     end
 
+    # Note: We prefix private methods here to prevent collisions in consumer's tests.
     private
 
-    def preview_class
+    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 __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?