view_component 2.49.1 → 3.23.2

data/lib/view_component/base.rb

@@ -4,40 +4,68 @@ require "action_view"
 require "active_support/configurable"
 require "view_component/collection"
 require "view_component/compile_cache"
-require "view_component/content_areas"
-require "view_component/polymorphic_slots"
-require "view_component/previewable"
+require "view_component/compiler"
+require "view_component/config"
+require "view_component/errors"
+require "view_component/inline_template"
+require "view_component/preview"
 require "view_component/slotable"
-require "view_component/slotable_v2"
+require "view_component/slotable_default"
+require "view_component/template"
+require "view_component/translatable"
 require "view_component/with_content_helper"
+require "view_component/use_helpers"
 
 module ViewComponent
   class Base < ActionView::Base
-    include ActiveSupport::Configurable
-    include ViewComponent::ContentAreas
-    include ViewComponent::Previewable
-    include ViewComponent::SlotableV2
-    include ViewComponent::WithContentHelper
+    class << self
+      delegate(*ViewComponent::Config.defaults.keys, to: :config)
+
+      # Returns the current config.
+      #
+      # @return [ActiveSupport::OrderedOptions]
+      def config
+        module_parents.each do |module_parent|
+          next unless module_parent.respond_to?(:config)
+          module_parent_config = module_parent.config.try(:view_component)
+          return module_parent_config if module_parent_config
+        end
+        ViewComponent::Config.current
+      end
+    end
 
-    ViewContextCalledBeforeRenderError = Class.new(StandardError)
+    include ViewComponent::InlineTemplate
+    include ViewComponent::UseHelpers
+    include ViewComponent::Slotable
+    include ViewComponent::Translatable
+    include ViewComponent::WithContentHelper
 
     RESERVED_PARAMETER = :content
+    VC_INTERNAL_DEFAULT_FORMAT = :html
 
     # For CSRF authenticity tokens in forms
     delegate :form_authenticity_token, :protect_against_forgery?, :config, to: :helpers
 
-    class_attribute :content_areas
-    self.content_areas = [] # class_attribute:default doesn't work until Rails 5.2
+    # For Content Security Policy nonces
+    delegate :content_security_policy_nonce, to: :helpers
+
+    # Config option that strips trailing whitespace in templates before compiling them.
+    class_attribute :__vc_strip_trailing_whitespace, instance_accessor: false, instance_predicate: false
+    self.__vc_strip_trailing_whitespace = false # class_attribute:default doesn't work until Rails 5.2
 
     attr_accessor :__vc_original_view_context
 
-    # EXPERIMENTAL: This API is experimental and may be removed at any time.
-    # Hook for allowing components to do work as part of the compilation process.
+    # Components render in their own view context. Helpers and other functionality
+    # require a reference to the original Rails view context, an instance of
+    # `ActionView::Base`. Use this method to set a reference to the original
+    # view context. Objects that implement this method will render in the component's
+    # view context, while objects that don't will render in the original view context
+    # so helpers, etc work as expected.
     #
-    # For example, one might compile component-specific assets at this point.
-    # @private TODO: add documentation
-    def self._after_compile
-      # noop
+    # @param view_context [ActionView::Base] The original view context.
+    # @return [void]
+    def set_original_view_context(view_context)
+      self.__vc_original_view_context = view_context
     end
 
     # Entrypoint for rendering components.
@@ -54,6 +82,8 @@ module ViewComponent
       @view_context = view_context
       self.__vc_original_view_context ||= view_context
 
+      @output_buffer = ActionView::OutputBuffer.new
+
       @lookup_context ||= view_context.lookup_context
 
       # required for path helpers in older Rails versions
@@ -74,11 +104,7 @@ module ViewComponent
       @current_template = self
 
       if block && defined?(@__vc_content_set_by_with_content)
-        raise ArgumentError.new(
-          "It looks like a block was provided after calling `with_content` on #{self.class.name}, " \
-          "which means that ViewComponent doesn't know which content to use.\n\n" \
-          "To fix this issue, use either `with_content` or a block."
-        )
+        raise DuplicateContentError.new(self.class.name)
       end
 
       @__vc_content_evaluated = false
@@ -87,7 +113,14 @@ module ViewComponent
       before_render
 
       if render?
-        render_template_for(@__vc_variant).to_s + _output_postamble
+        rendered_template = render_template_for(@__vc_variant, __vc_request&.format&.to_sym).to_s
+
+        # Avoid allocating new string when output_preamble and output_postamble are blank
+        if output_preamble.blank? && output_postamble.blank?
+          rendered_template
+        else
+          safe_output_preamble + rendered_template + safe_output_postamble
+        end
       else
         ""
       end
@@ -95,26 +128,64 @@ module ViewComponent
       @current_template = old_current_template
     end
 
-    # EXPERIMENTAL: Optional content to be returned after the rendered template.
+    # Subclass components that call `super` inside their template code will cause a
+    # double render if they emit the result.
+    #
+    # ```erb
+    # <%= super %> # double-renders
+    # <% super %> # doesn't double-render
+    # ```
+    #
+    # `super` also doesn't consider the current variant. `render_parent` renders the
+    # parent template considering the current variant and emits the result without
+    # double-rendering.
+    def render_parent
+      render_parent_to_string
+      nil
+    end
+
+    # Renders the parent component to a string and returns it. This method is meant
+    # to be used inside custom #call methods when a string result is desired, eg.
+    #
+    # ```ruby
+    # def call
+    #   "<div>#{render_parent_to_string}</div>"
+    # end
+    # ```
+    #
+    # When rendering the parent inside an .erb template, use `#render_parent` instead.
+    def render_parent_to_string
+      @__vc_parent_render_level ||= 0 # ensure a good starting value
+
+      begin
+        target_render = self.class.instance_variable_get(:@__vc_ancestor_calls)[@__vc_parent_render_level]
+        @__vc_parent_render_level += 1
+
+        target_render.bind_call(self, @__vc_variant)
+      ensure
+        @__vc_parent_render_level -= 1
+      end
+    end
+
+    # Optional content to be returned before the rendered template.
     #
     # @return [String]
-    def _output_postamble
-      ""
+    def output_preamble
+      @@default_output_preamble ||= "".html_safe
     end
 
-    # Called before rendering the component. Override to perform operations that
-    # depend on having access to the view context, such as helpers.
+    # Optional content to be returned after the rendered template.
     #
-    # @return [void]
-    def before_render
-      before_render_check
+    # @return [String]
+    def output_postamble
+      @@default_output_postamble ||= "".html_safe
     end
 
-    # Called after rendering the component.
+    # Called before rendering the component. Override to perform operations that
+    # depend on having access to the view context, such as helpers.
     #
-    # @deprecated Use `#before_render` instead. Will be removed in v3.0.0.
     # @return [void]
-    def before_render_check
+    def before_render
       # noop
     end
 
@@ -125,8 +196,11 @@ module ViewComponent
       true
     end
 
+    # Override the ActionView::Base initializer so that components
+    # do not need to define their own initializers.
     # @private
-    def initialize(*); end
+    def initialize(*)
+    end
 
     # Re-use original view_context if we're not rendering a component.
     #
@@ -136,8 +210,8 @@ module ViewComponent
     #
     # @private
     def render(options = {}, args = {}, &block)
-      if options.is_a? ViewComponent::Base
-        options.__vc_original_view_context = __vc_original_view_context
+      if options.respond_to?(:set_original_view_context)
+        options.set_original_view_context(self.__vc_original_view_context)
         super
       else
         __vc_original_view_context.render(options, args, &block)
@@ -149,16 +223,7 @@ module ViewComponent
     #
     # @return [ActionController::Base]
     def controller
-      if view_context.nil?
-        raise(
-          ViewContextCalledBeforeRenderError,
-          "`#controller` can't be used during initialization, as it depends " \
-          "on the view context that only exists once a ViewComponent is passed to " \
-          "the Rails render pipeline.\n\n" \
-          "It's sometimes possible to fix this issue by moving code dependent on " \
-          "`#controller` to a `#before_render` method: https://viewcomponent.org/api.html#before_render--void."
-        )
-      end
+      raise ControllerCalledBeforeRenderError if view_context.nil?
 
       @__vc_controller ||= view_context.controller
     end
@@ -168,16 +233,7 @@ module ViewComponent
     #
     # @return [ActionView::Base]
     def helpers
-      if view_context.nil?
-        raise(
-          ViewContextCalledBeforeRenderError,
-          "`#helpers` can't be used during initialization, as it depends " \
-          "on the view context that only exists once a ViewComponent is passed to " \
-          "the Rails render pipeline.\n\n" \
-          "It's sometimes possible to fix this issue by moving code dependent on " \
-          "`#helpers` to a `#before_render` method: https://viewcomponent.org/api.html#before_render--void."
-        )
-      end
+      raise HelpersCalledBeforeRenderError if view_context.nil?
 
       # Attempt to re-use the original view_context passed to the first
       # component rendered in the rendering pipeline. This prevents the
@@ -189,6 +245,22 @@ module ViewComponent
       @__vc_helpers ||= __vc_original_view_context || controller.view_context
     end
 
+    if ::Rails.env.development? || ::Rails.env.test?
+      # @private
+      def method_missing(method_name, *args) # rubocop:disable Style/MissingRespondToMissing
+        super
+      rescue => e # rubocop:disable Style/RescueStandardError
+        e.set_backtrace e.backtrace.tap(&:shift)
+        raise e, <<~MESSAGE.chomp if view_context && e.is_a?(NameError) && helpers.respond_to?(method_name)
+          #{e.message}
+
+          You may be trying to call a method provided as a view helper. Did you mean `helpers.#{method_name}`?
+        MESSAGE
+
+        raise
+      end
+    end
+
     # Exposes .virtual_path as an instance method
     #
     # @private
@@ -206,25 +278,7 @@ module ViewComponent
     #
     # @private
     def format
-      # Ruby 2.6 throws a warning without checking `defined?`, 2.7 doesn't
-      if defined?(@__vc_variant)
-        @__vc_variant
-      end
-    end
-
-    # Use the provided variant instead of the one determined by the current request.
-    #
-    # @deprecated Will be removed in v3.0.0.
-    # @param variant [Symbol] The variant to be used by the component.
-    # @return [self]
-    def with_variant(variant)
-      ActiveSupport::Deprecation.warn(
-        "`with_variant` is deprecated and will be removed in ViewComponent v3.0.0."
-      )
-
-      @__vc_variant = variant
-
-      self
+      @__vc_variant if defined?(@__vc_variant)
     end
 
     # The current request. Use sparingly as doing so introduces coupling that
@@ -232,116 +286,199 @@ module ViewComponent
     #
     # @return [ActionDispatch::Request]
     def request
-      @request ||= controller.request if controller.respond_to?(:request)
+      __vc_request
     end
 
-    private
-
-    attr_reader :view_context
+    # Enables consumers to override request/@request
+    #
+    # @private
+    def __vc_request
+      @__vc_request ||= controller.request if controller.respond_to?(:request)
+    end
 
+    # The content passed to the component instance as a block.
+    #
+    # @return [String]
     def content
       @__vc_content_evaluated = true
       return @__vc_content if defined?(@__vc_content)
 
       @__vc_content =
-        if @view_context && @__vc_render_in_block
+        if __vc_render_in_block_provided?
           view_context.capture(self, &@__vc_render_in_block)
-        elsif defined?(@__vc_content_set_by_with_content)
+        elsif __vc_content_set_by_with_content_defined?
           @__vc_content_set_by_with_content
         end
     end
 
+    # Whether `content` has been passed to the component.
+    #
+    # @return [Boolean]
+    def content?
+      __vc_render_in_block_provided? || __vc_content_set_by_with_content_defined?
+    end
+
+    private
+
+    attr_reader :view_context
+
+    def __vc_render_in_block_provided?
+      defined?(@view_context) && @view_context && @__vc_render_in_block
+    end
+
+    def __vc_content_set_by_with_content_defined?
+      defined?(@__vc_content_set_by_with_content)
+    end
+
     def content_evaluated?
-      @__vc_content_evaluated
+      defined?(@__vc_content_evaluated) && @__vc_content_evaluated
+    end
+
+    def maybe_escape_html(text)
+      return text if __vc_request && !__vc_request.format.html?
+      return text if text.blank?
+
+      if text.html_safe?
+        text
+      else
+        yield
+        html_escape(text)
+      end
+    end
+
+    def safe_output_preamble
+      maybe_escape_html(output_preamble) do
+        Kernel.warn("WARNING: The #{self.class} component was provided an HTML-unsafe preamble. The preamble will be automatically escaped, but you may want to investigate.")
+      end
+    end
+
+    def safe_output_postamble
+      maybe_escape_html(output_postamble) do
+        Kernel.warn("WARNING: The #{self.class} component was provided an HTML-unsafe postamble. The postamble will be automatically escaped, but you may want to investigate.")
+      end
     end
 
     # Set the controller used for testing components:
     #
-    #     config.view_component.test_controller = "MyTestController"
+    # ```ruby
+    # config.view_component.test_controller = "MyTestController"
+    # ```
     #
-    # Defaults to ApplicationController. Can also be configured on a per-test
-    # basis using `with_controller_class`.
+    # Defaults to `nil`. If this is falsy, `"ApplicationController"` is used. Can also be
+    # configured on a per-test basis using `with_controller_class`.
     #
-    mattr_accessor :test_controller
-    @@test_controller = "ApplicationController"
 
     # Set if render monkey patches should be included or not in Rails <6.1:
     #
-    #     config.view_component.render_monkey_patch_enabled = false
+    # ```ruby
+    # config.view_component.render_monkey_patch_enabled = false
+    # ```
     #
-    mattr_accessor :render_monkey_patch_enabled, instance_writer: false, default: true
 
-    # Always generate a Stimulus controller alongside the component:
+    # Path for component files
     #
-    #     config.view_component.generate_stimulus_controller = true
+    # ```ruby
+    # config.view_component.view_component_path = "app/my_components"
+    # ```
     #
-    # Defaults to `false`.
+    # Defaults to `nil`. If this is falsy, `app/components` is used.
     #
-    mattr_accessor :generate_stimulus_controller, instance_writer: false, default: false
 
-    # Always generate translations file alongside the component:
+    # Parent class for generated components
     #
-    #     config.view_component.generate_locale = true
+    # ```ruby
+    # config.view_component.component_parent_class = "MyBaseComponent"
+    # ```
     #
-    # Defaults to `false`.
+    # Defaults to nil. If this is falsy, generators will use
+    # "ApplicationComponent" if defined, "ViewComponent::Base" otherwise.
     #
-    mattr_accessor :generate_locale, instance_writer: false, default: false
 
-    # Always generate as many translations files as available locales:
+    # Configuration for generators.
     #
-    #     config.view_component.generate_distinct_locale_files = true
+    # All options under this namespace default to `false` unless otherwise
+    # stated.
     #
-    # Defaults to `false`.
+    # #### #sidecar
     #
-    # One file will be generated for each configured `I18n.available_locales`.
-    # Fallback on `[:en]` when no available_locales is defined.
+    # Always generate a component with a sidecar directory:
     #
-    mattr_accessor :generate_distinct_locale_files, instance_writer: false, default: false
-
-    # Path for component files
+    # ```ruby
+    # config.view_component.generate.sidecar = true
+    # ```
     #
-    #     config.view_component.view_component_path = "app/my_components"
+    # #### #stimulus_controller
     #
-    # Defaults to `app/components`.
+    # Always generate a Stimulus controller alongside the component:
     #
-    mattr_accessor :view_component_path, instance_writer: false, default: "app/components"
-
-    # Parent class for generated components
+    # ```ruby
+    # config.view_component.generate.stimulus_controller = true
+    # ```
     #
-    #     config.view_component.component_parent_class = "MyBaseComponent"
+    # #### `#typescript`
     #
-    # Defaults to "ApplicationComponent" if defined, "ViewComponent::Base" otherwise.
+    # Generate TypeScript files instead of JavaScript files:
     #
-    mattr_accessor :component_parent_class, instance_writer: false
-
-    # Always generate a component with a sidecar directory:
+    # ```ruby
+    # config.view_component.generate.typescript = true
+    # ```
+    #
+    # #### #locale
+    #
+    # Always generate translations file alongside the component:
+    #
+    # ```ruby
+    # config.view_component.generate.locale = true
+    # ```
+    #
+    # #### #distinct_locale_files
+    #
+    # Always generate as many translations files as available locales:
     #
-    #     config.view_component.generate_sidecar = true
+    # ```ruby
+    # config.view_component.generate.distinct_locale_files = true
+    # ```
     #
-    # Defaults to `false`.
+    # One file will be generated for each configured `I18n.available_locales`,
+    # falling back to `[:en]` when no `available_locales` is defined.
     #
-    mattr_accessor :generate_sidecar, instance_writer: false, default: false
+    # #### #preview
+    #
+    # Always generate preview alongside the component:
+    #
+    # ```ruby
+    # config.view_component.generate.preview = true
+    # ```
+    #
+    #  Defaults to `false`.
 
     class << self
+      # The file path of the component Ruby file.
+      #
+      # @return [String]
+      attr_reader :identifier
+
       # @private
-      attr_accessor :source_location, :virtual_path
+      attr_writer :identifier
+
+      # @private
+      attr_accessor :virtual_path
 
-      # EXPERIMENTAL: This API is experimental and may be removed at any time.
       # Find sidecar files for the given extensions.
       #
       # The provided array of extensions is expected to contain
-      # strings starting without the "dot", example: `["erb", "haml"]`.
+      # strings starting without the dot, example: `["erb", "haml"]`.
       #
       # For example, one might collect sidecar CSS files that need to be compiled.
-      # @private TODO: add documentation
-      def _sidecar_files(extensions)
-        return [] unless source_location
+      # @param extensions [Array<String>] Extensions of which to return matching sidecar files.
+      def sidecar_files(extensions)
+        return [] unless identifier
 
         extensions = extensions.join(",")
 
         # view files in a directory named like the component
-        directory = File.dirname(source_location)
-        filename = File.basename(source_location, ".rb")
+        directory = File.dirname(identifier)
+        filename = File.basename(identifier, ".rb")
         component_name = name.demodulize.underscore
 
         # Add support for nested components defined in the same file.
@@ -366,24 +503,20 @@ module ViewComponent
 
         sidecar_directory_files = Dir["#{directory}/#{component_name}/#{filename}.*{#{extensions}}"]
 
-        (sidecar_files - [source_location] + sidecar_directory_files + nested_component_files).uniq
+        (sidecar_files - [identifier] + sidecar_directory_files + nested_component_files).uniq
       end
 
       # Render a component for each element in a collection ([documentation](/guide/collections)):
       #
-      #     render(ProductsComponent.with_collection(@products, foo: :bar))
+      # ```ruby
+      # render(ProductsComponent.with_collection(@products, foo: :bar))
+      # ```
       #
       # @param collection [Enumerable] A list of items to pass the ViewComponent one at a time.
+      # @param spacer_component [ViewComponent::Base] Component instance to be rendered between items.
       # @param args [Arguments] Arguments to pass to the ViewComponent every time.
-      def with_collection(collection, **args)
-        Collection.new(self, collection, **args)
-      end
-
-      # Provide identifier for ActionView template annotations
-      #
-      # @private
-      def short_identifier
-        @short_identifier ||= defined?(Rails.root) ? source_location.sub("#{Rails.root}/", "") : source_location
+      def with_collection(collection, spacer_component: nil, **args)
+        Collection.new(self, collection, spacer_component, **args)
       end
 
       # @private
@@ -392,25 +525,52 @@ module ViewComponent
         # `compile` defines
         compile
 
+        # Give the child its own personal #render_template_for to protect against the case when
+        # eager loading is disabled and the parent component is rendered before the child. In
+        # such a scenario, the parent will override ViewComponent::Base#render_template_for,
+        # meaning it will not be called for any children and thus not compile their templates.
+        if !child.instance_methods(false).include?(:render_template_for) && !child.compiled?
+          child.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def render_template_for(variant = nil, format = nil)
+              # Force compilation here so the compiler always redefines render_template_for.
+              # This is mostly a safeguard to prevent infinite recursion.
+              self.class.compile(raise_errors: true, force: true)
+              # .compile replaces this method; call the new one
+              render_template_for(variant, format)
+            end
+          RUBY
+        end
+
         # If Rails application is loaded, add application url_helpers to the component context
         # we need to check this to use this gem as a dependency
-        if defined?(Rails) && Rails.application
-          child.include Rails.application.routes.url_helpers unless child < Rails.application.routes.url_helpers
+        if defined?(Rails) && Rails.application && !(child < Rails.application.routes.url_helpers)
+          child.include Rails.application.routes.url_helpers
         end
 
         # Derive the source location of the component Ruby file from the call stack.
         # We need to ignore `inherited` frames here as they indicate that `inherited`
         # has been re-defined by the consuming application, likely in ApplicationComponent.
-        child.source_location = caller_locations(1, 10).reject { |l| l.label == "inherited" }[0].path
+        # We use `base_label` method here instead of `label` to avoid cases where the method
+        # owner is included in a prefix like `ApplicationComponent.inherited`.
+        child.identifier = caller_locations(1, 10).reject { |l| l.base_label == "inherited" }[0].path
 
-        # Removes the first part of the path and the extension.
-        child.virtual_path = child.source_location.gsub(
-          %r{(.*#{Regexp.quote(ViewComponent::Base.view_component_path)})|(\.rb)}, ""
-        )
+        # If Rails application is loaded, removes the first part of the path and the extension.
+        if defined?(Rails) && Rails.application
+          child.virtual_path = child.identifier.gsub(
+            /(.*#{Regexp.quote(ViewComponent::Base.config.view_component_path)})|(\.rb)/, ""
+          )
+        end
 
         # Set collection parameter to the extended component
         child.with_collection_parameter provided_collection_parameter
 
+        if instance_methods(false).include?(:render_template_for)
+          vc_ancestor_calls = defined?(@__vc_ancestor_calls) ? @__vc_ancestor_calls.dup : []
+
+          vc_ancestor_calls.unshift(instance_method(:render_template_for))
+          child.instance_variable_set(:@__vc_ancestor_calls, vc_ancestor_calls)
+        end
+
         super
       end
 
@@ -419,43 +579,51 @@ module ViewComponent
         compiler.compiled?
       end
 
-      # Compile templates to instance methods, assuming they haven't been compiled already.
-      #
-      # Do as much work as possible in this step, as doing so reduces the amount
-      # of work done each time a component is rendered.
-      # @private
-      def compile(raise_errors: false)
-        compiler.compile(raise_errors: raise_errors)
-      end
-
-      # @private
-      def compiler
-        @__vc_compiler ||= Compiler.new(self)
-      end
-
-      # we'll eventually want to update this to support other types
       # @private
-      def type
-        "text/html"
+      def ensure_compiled
+        compile unless compiled?
       end
 
       # @private
-      def format
-        :html
+      def compile(raise_errors: false, force: false)
+        compiler.compile(raise_errors: raise_errors, force: force)
       end
 
       # @private
-      def identifier
-        source_location
+      def compiler
+        @__vc_compiler ||= Compiler.new(self)
       end
 
       # Set the parameter name used when rendering elements of a collection ([documentation](/guide/collections)):
       #
-      #     with_collection_parameter :item
+      # ```ruby
+      # with_collection_parameter :item
+      # ```
       #
       # @param parameter [Symbol] The parameter name used when rendering elements of a collection.
       def with_collection_parameter(parameter)
         @provided_collection_parameter = parameter
+        @initialize_parameters = nil
+      end
+
+      # Strips trailing whitespace from templates before compiling them.
+      #
+      # ```ruby
+      # class MyComponent < ViewComponent::Base
+      #   strip_trailing_whitespace
+      # end
+      # ```
+      #
+      # @param value [Boolean] Whether to strip newlines.
+      def strip_trailing_whitespace(value = true)
+        self.__vc_strip_trailing_whitespace = value
+      end
+
+      # Whether trailing whitespace will be stripped before compilation.
+      #
+      # @return [Boolean]
+      def strip_trailing_whitespace?
+        __vc_strip_trailing_whitespace
       end
 
       # Ensure the component initializer accepts the
@@ -463,58 +631,41 @@ module ViewComponent
       # validate that the default parameter name
       # is accepted, as support for collection
       # rendering is optional.
-      # @private TODO: add documentation
+      # @private
       def validate_collection_parameter!(validate_default: false)
         parameter = validate_default ? collection_parameter : provided_collection_parameter
 
         return unless parameter
-        return if initialize_parameter_names.include?(parameter)
+        return if initialize_parameter_names.include?(parameter) || splatted_keyword_argument_present?
 
-        # If Ruby can't parse the component class, then the initalize
+        # If Ruby can't parse the component class, then the initialize
         # parameters will be empty and ViewComponent will not be able to render
         # the component.
         if initialize_parameters.empty?
-          raise ArgumentError.new(
-            "The #{self} initializer is empty or invalid." \
-            "It must accept the parameter `#{parameter}` to render it as a collection.\n\n" \
-            "To fix this issue, update the initializer to accept `#{parameter}`.\n\n" \
-            "See https://viewcomponent.org/guide/collections.html for more information on rendering collections."
-          )
+          raise EmptyOrInvalidInitializerError.new(name, parameter)
         end
 
-        raise ArgumentError.new(
-          "The initializer for #{self} doesn't accept the parameter `#{parameter}`, " \
-          "which is required in order to render it as a collection.\n\n" \
-          "To fix this issue, update the initializer to accept `#{parameter}`.\n\n" \
-          "See https://viewcomponent.org/guide/collections.html for more information on rendering collections."
-        )
+        raise MissingCollectionArgumentError.new(name, parameter)
       end
 
       # Ensure the component initializer doesn't define
       # invalid parameters that could override the framework's
       # methods.
-      # @private TODO: add documentation
+      # @private
       def validate_initialization_parameters!
         return unless initialize_parameter_names.include?(RESERVED_PARAMETER)
 
-        raise ViewComponent::ComponentError.new(
-          "#{self} initializer can't accept the parameter `#{RESERVED_PARAMETER}`, as it will override a " \
-          "public ViewComponent method. To fix this issue, rename the parameter."
-        )
+        raise ReservedParameterError.new(name, RESERVED_PARAMETER)
       end
 
       # @private
       def collection_parameter
-        if provided_collection_parameter
-          provided_collection_parameter
-        else
-          name && name.demodulize.underscore.chomp("_component").to_sym
-        end
+        provided_collection_parameter || name && name.demodulize.underscore.chomp("_component").to_sym
       end
 
       # @private
       def collection_counter_parameter
-        "#{collection_parameter}_counter".to_sym
+        :"#{collection_parameter}_counter"
       end
 
       # @private
@@ -524,7 +675,7 @@ module ViewComponent
 
       # @private
       def collection_iteration_parameter
-        "#{collection_parameter}_iteration".to_sym
+        :"#{collection_parameter}_iteration"
       end
 
       # @private
@@ -534,6 +685,11 @@ module ViewComponent
 
       private
 
+      def splatted_keyword_argument_present?
+        initialize_parameters.flatten.include?(:keyrest) &&
+          !initialize_parameters.include?([:keyrest, :**]) # Un-named splatted keyword args don't count!
+      end
+
       def initialize_parameter_names
         return attribute_names.map(&:to_sym) if respond_to?(:attribute_names)
 
@@ -543,7 +699,7 @@ module ViewComponent
       end
 
       def initialize_parameters
-        instance_method(:initialize).parameters
+        @initialize_parameters ||= instance_method(:initialize).parameters
       end
 
       def provided_collection_parameter