view_component 3.23.2 → 4.12.0

data/lib/view_component/base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "action_view"
-require "active_support/configurable"
+require "action_view/base"
 require "view_component/collection"
 require "view_component/compile_cache"
 require "view_component/compiler"
@@ -9,15 +9,27 @@ require "view_component/config"
 require "view_component/errors"
 require "view_component/inline_template"
 require "view_component/preview"
+require "view_component/request_details"
 require "view_component/slotable"
-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 ActionView
+  class OutputBuffer
+    def with_buffer(buf = nil)
+      new_buffer = buf || +""
+      old_buffer, @raw_buffer = @raw_buffer, new_buffer
+      yield
+      new_buffer
+    ensure
+      @raw_buffer = old_buffer
+    end
+  end
+end
 
 module ViewComponent
-  class Base < ActionView::Base
+  class Base
     class << self
       delegate(*ViewComponent::Config.defaults.keys, to: :config)
 
@@ -34,26 +46,33 @@ module ViewComponent
       end
     end
 
+    include ActionView::Helpers
+    include Rails.application.routes.url_helpers if defined?(Rails.application.routes)
+    include ERB::Escape
+    include ActiveSupport::CoreExt::ERBUtil
+
     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
 
+    # HTML construction methods
+    delegate :output_buffer, :lookup_context, :view_renderer, :view_flow, to: :helpers
+
+    # For Turbo::StreamsHelper
+    delegate :formats, :formats=, to: :helpers
+
     # 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
+    class_attribute :__vc_strip_trailing_whitespace, instance_accessor: false, instance_predicate: false, default: false
 
     attr_accessor :__vc_original_view_context
+    attr_reader :current_template
 
     # Components render in their own view context. Helpers and other functionality
     # require a reference to the original Rails view context, an instance of
@@ -63,9 +82,17 @@ module ViewComponent
     # so helpers, etc work as expected.
     #
     # @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
+      # noop
+    end
+
+    using RequestDetails
+
+    # Including `Rails.application.routes.url_helpers` defines an initializer that accepts (...),
+    # so we have to define our own empty initializer to overwrite it.
+    def initialize
     end
 
     # Entrypoint for rendering components.
@@ -76,55 +103,82 @@ module ViewComponent
     # Returns HTML that has been escaped by the respective template handler.
     #
     # @return [String]
-    def render_in(view_context, &block)
-      self.class.compile(raise_errors: true)
+    def render_in(view_context, **_, &block)
+      self.class.__vc_compile(raise_errors: true)
 
-      @view_context = view_context
-      self.__vc_original_view_context ||= view_context
+      __vc_reset_render_state!
 
-      @output_buffer = ActionView::OutputBuffer.new
+      @view_context = view_context
+      @old_virtual_path = view_context.instance_variable_get(:@virtual_path)
+      self.__vc_original_view_context = view_context
 
-      @lookup_context ||= view_context.lookup_context
+      @output_buffer = view_context.output_buffer
 
-      # required for path helpers in older Rails versions
-      @view_renderer ||= view_context.view_renderer
+      @lookup_context = view_context.lookup_context
 
       # For content_for
-      @view_flow ||= view_context.view_flow
+      @view_flow = view_context.view_flow
 
       # For i18n
       @virtual_path ||= virtual_path
 
-      # For template variants (+phone, +desktop, etc.)
-      @__vc_variant ||= @lookup_context.variants.first
+      # Describes the inferred request constraints (locales, formats, variants)
+      @__vc_requested_details = @lookup_context.vc_requested_details
 
       # For caching, such as #cache_if
       @current_template = nil unless defined?(@current_template)
       old_current_template = @current_template
-      @current_template = self
 
       if block && defined?(@__vc_content_set_by_with_content)
         raise DuplicateContentError.new(self.class.name)
       end
 
       @__vc_content_evaluated = false
+      remove_instance_variable(:@__vc_content) if defined?(@__vc_content)
       @__vc_render_in_block = block
+      @view_context.instance_variable_set(:@virtual_path, virtual_path)
 
       before_render
 
       if render?
-        rendered_template = render_template_for(@__vc_variant, __vc_request&.format&.to_sym).to_s
+        value = nil
+
+        @output_buffer.with_buffer do
+          inner_rendered_template = nil
+          around_rendered_template = around_render do
+            inner_rendered_template = render_template_for(@__vc_requested_details).to_s
+          end
+
+          # If `around_render` returned the same object the block yielded, the inner
+          # template's escaping is authoritative and we can trust the result. If the
+          # user replaced/wrapped the value, re-check HTML safety to prevent
+          # bypassing the escaping applied to normal `#call` return values
+          # (GHSA-97jw-64cj-jc58).
+          rendered_template = if around_rendered_template.equal?(inner_rendered_template)
+            around_rendered_template
+          else
+            __vc_safe_around_render_output(around_rendered_template)
+          end
+
+          # Avoid allocating new string when output_preamble and output_postamble are blank
+          value = if output_preamble.blank? && output_postamble.blank?
+            rendered_template
+          else
+            __vc_safe_output_preamble + rendered_template + __vc_safe_output_postamble
+          end
+        end
 
-        # 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
+        if ActionView::Base.annotate_rendered_view_with_filenames && current_template.inline_call? && request&.format == :html
+          identifier = defined?(Rails.root) ? self.class.identifier.sub("#{Rails.root}/", "") : self.class.identifier
+          value = "<!-- BEGIN #{identifier} -->".html_safe + value + "<!-- END #{identifier} -->".html_safe
         end
+
+        value
       else
-        ""
+        "".html_safe
       end
     ensure
+      view_context.instance_variable_set(:@virtual_path, @old_virtual_path)
       @current_template = old_current_template
     end
 
@@ -161,7 +215,7 @@ module ViewComponent
         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)
+        target_render.bind_call(self, @__vc_requested_details)
       ensure
         @__vc_parent_render_level -= 1
       end
@@ -189,6 +243,14 @@ module ViewComponent
       # noop
     end
 
+    # Called around rendering the component. Override to wrap the rendering of a
+    # component in custom instrumentation, etc.
+    #
+    # @return [void]
+    def around_render
+      yield
+    end
+
     # Override to determine whether the ViewComponent should render.
     #
     # @return [Boolean]
@@ -196,28 +258,56 @@ module ViewComponent
       true
     end
 
-    # Override the ActionView::Base initializer so that components
-    # do not need to define their own initializers.
-    # @private
-    def initialize(*)
-    end
-
     # Re-use original view_context if we're not rendering a component.
     #
-    # This prevents an exception when rendering a partial inside of a component that has also been rendered outside
-    # of the component. This is due to the partials compiled template method existing in the parent `view_context`,
-    #  and not the component's `view_context`.
+    # As of v4, ViewComponent::Base re-uses the existing view context created
+    # by ActionView, meaning the current view context and the original view
+    # context are the same object. set_original_view_context is still called
+    # to maintain backwards compatibility.
     #
     # @private
     def render(options = {}, args = {}, &block)
       if options.respond_to?(:set_original_view_context)
-        options.set_original_view_context(self.__vc_original_view_context)
-        super
+        options.set_original_view_context(__vc_original_view_context)
+
+        # We assume options is a component, so there's no need to evaluate the
+        # block in the view context as we do below.
+        @view_context.render(options, args, &block)
+      elsif block
+        __vc_original_view_context.render(options, args) do
+          # capture the block output in the view context of the component
+          output = capture(&block)
+
+          # Partials are rendered to their own buffer and do not append to the
+          # original @output_buffer we retain a reference to in #render_in. This
+          # is a problem since the block passed to us here in the #render method
+          # is evaluated within the context of ViewComponent::Base, and thus
+          # appends to the original @output_buffer. To avoid this, we evaluate the
+          # block in the view context instead, which will append to the output buffer
+          # created for the partial.
+          __vc_original_view_context.capture { output }
+        end
       else
-        __vc_original_view_context.render(options, args, &block)
+        __vc_original_view_context.render(options, args)
       end
     end
 
+    # Sync @output_buffer with the view context's current output buffer before
+    # capturing. Form helpers create builders with @template_object pointing to
+    # the component. When those builders later call capture inside a partial
+    # (whose _run allocated a fresh OutputBuffer on the view context), the
+    # component's stale @output_buffer would capture from the wrong buffer.
+    # Temporarily switching to the view context's buffer keeps both in sync.
+    #
+    # @private
+    def capture(...)
+      old_output_buffer = @output_buffer
+      @output_buffer = view_context.output_buffer if view_context
+      super
+    ensure
+      @output_buffer = old_output_buffer
+    end
+
     # The current controller. Use sparingly as doing so introduces coupling
     # that inhibits encapsulation & reuse, often making testing difficult.
     #
@@ -245,7 +335,7 @@ module ViewComponent
       @__vc_helpers ||= __vc_original_view_context || controller.view_context
     end
 
-    if ::Rails.env.development? || ::Rails.env.test?
+    if defined?(Rails.env) && (::Rails.env.development? || ::Rails.env.test?)
       # @private
       def method_missing(method_name, *args) # rubocop:disable Style/MissingRespondToMissing
         super
@@ -274,11 +364,12 @@ module ViewComponent
       []
     end
 
-    # For caching, such as #cache_if
-    #
-    # @private
-    def format
-      @__vc_variant if defined?(@__vc_variant)
+    if defined?(Rails::VERSION) && Rails::VERSION::MAJOR == 7 && Rails::VERSION::MINOR == 1
+      # Rails expects us to define `format` on all renderables,
+      # but we do not know the `format` of a ViewComponent until runtime.
+      def format
+        nil
+      end
     end
 
     # The current request. Use sparingly as doing so introduces coupling that
@@ -289,10 +380,9 @@ module ViewComponent
       __vc_request
     end
 
-    # Enables consumers to override request/@request
-    #
     # @private
     def __vc_request
+      # The current request (if present, as mailers/jobs/etc do not have a request)
       @__vc_request ||= controller.request if controller.respond_to?(:request)
     end
 
@@ -305,7 +395,9 @@ module ViewComponent
 
       @__vc_content =
         if __vc_render_in_block_provided?
-          view_context.capture(self, &@__vc_render_in_block)
+          with_captured_virtual_path(@old_virtual_path) do
+            view_context.capture(self, &@__vc_render_in_block)
+          end
         elsif __vc_content_set_by_with_content_defined?
           @__vc_content_set_by_with_content
         end
@@ -318,6 +410,17 @@ module ViewComponent
       __vc_render_in_block_provided? || __vc_content_set_by_with_content_defined?
     end
 
+    # @private
+    # Temporarily sets the virtual path to the captured value, then restores it.
+    # This ensures translations and other path-dependent code execute with the correct scope.
+    def with_captured_virtual_path(captured_path)
+      old_virtual_path = @view_context.instance_variable_get(:@virtual_path)
+      @view_context.instance_variable_set(:@virtual_path, captured_path)
+      yield
+    ensure
+      @view_context.instance_variable_set(:@virtual_path, old_virtual_path)
+    end
+
     private
 
     attr_reader :view_context
@@ -330,12 +433,8 @@ module ViewComponent
       defined?(@__vc_content_set_by_with_content)
     end
 
-    def content_evaluated?
-      defined?(@__vc_content_evaluated) && @__vc_content_evaluated
-    end
-
-    def maybe_escape_html(text)
-      return text if __vc_request && !__vc_request.format.html?
+    def __vc_maybe_escape_html(text)
+      return text if @current_template && !@current_template.html?
       return text if text.blank?
 
       if text.html_safe?
@@ -346,53 +445,39 @@ module ViewComponent
       end
     end
 
-    def safe_output_preamble
-      maybe_escape_html(output_preamble) do
+    def __vc_safe_output_preamble
+      __vc_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
+    def __vc_safe_output_postamble
+      __vc_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:
-    #
-    # ```ruby
-    # config.view_component.test_controller = "MyTestController"
-    # ```
-    #
-    # Defaults to `nil`. If this is falsy, `"ApplicationController"` is used. Can also be
-    # configured on a per-test basis using `with_controller_class`.
-    #
-
-    # Set if render monkey patches should be included or not in Rails <6.1:
-    #
-    # ```ruby
-    # config.view_component.render_monkey_patch_enabled = false
-    # ```
-    #
-
-    # Path for component files
-    #
-    # ```ruby
-    # config.view_component.view_component_path = "app/my_components"
-    # ```
-    #
-    # Defaults to `nil`. If this is falsy, `app/components` is used.
-    #
+    def __vc_safe_around_render_output(output)
+      __vc_maybe_escape_html(output) do
+        Kernel.warn("WARNING: The #{self.class} component's around_render returned an HTML-unsafe string. The output will be automatically escaped, but you may want to investigate.")
+      end
+    end
 
-    # Parent class for generated components
-    #
-    # ```ruby
-    # config.view_component.component_parent_class = "MyBaseComponent"
-    # ```
-    #
-    # Defaults to nil. If this is falsy, generators will use
-    # "ApplicationComponent" if defined, "ViewComponent::Base" otherwise.
-    #
+    # Resets every render-scoped instance variable derived from the calling view
+    # context so a reused instance cannot leak controller/helper/request/format
+    # state from a previous render. Slot state (`@__vc_set_slots`,
+    # `@__vc_content_set_by_with_content`) is intentionally preserved because it
+    # is populated by callers _before_ `render_in` runs (e.g. via `with_*`
+    # slot setters or `with_content`).
+    def __vc_reset_render_state!
+      %i[
+        @__vc_controller
+        @__vc_helpers
+        @__vc_request
+      ].each do |ivar|
+        remove_instance_variable(ivar) if instance_variable_defined?(ivar)
+      end
+    end
 
     # Configuration for generators.
     #
@@ -451,6 +536,18 @@ module ViewComponent
     # ```
     #
     #  Defaults to `false`.
+    #
+    # #### ßparent_class
+    #
+    # Parent class for generated components
+    #
+    # ```ruby
+    # config.view_component.generate.parent_class = "MyBaseComponent"
+    # ```
+    #
+    # Defaults to nil. If this is falsy, generators will use
+    # "ApplicationComponent" if defined, "ViewComponent::Base" otherwise.
+    #
 
     class << self
       # The file path of the component Ruby file.
@@ -473,6 +570,7 @@ module ViewComponent
       # @param extensions [Array<String>] Extensions of which to return matching sidecar files.
       def sidecar_files(extensions)
         return [] unless identifier
+        return [] unless name
 
         extensions = extensions.join(",")
 
@@ -519,52 +617,45 @@ module ViewComponent
         Collection.new(self, collection, spacer_component, **args)
       end
 
+      # @private
+      def __vc_compile(raise_errors: false, force: false)
+        __vc_compiler.compile(raise_errors: raise_errors, force: force)
+      end
+
       # @private
       def inherited(child)
         # Compile so child will inherit compiled `call_*` template methods that
         # `compile` defines
-        compile
+        __vc_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?
+        if !child.method_defined?(:render_template_for, false) && !child.__vc_compiled?
           child.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-            def render_template_for(variant = nil, format = nil)
+            def render_template_for(requested_details)
               # 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)
+              self.class.__vc_compile(raise_errors: true, force: true)
+              # .__vc_compile replaces this method; call the new one
+              render_template_for(requested_details)
             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 < 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.
         # 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
-
-        # 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
+        child.virtual_path = child.name&.underscore
 
         # Set collection parameter to the extended component
-        child.with_collection_parameter provided_collection_parameter
+        child.with_collection_parameter(__vc_provided_collection_parameter)
 
-        if instance_methods(false).include?(:render_template_for)
+        if method_defined?(:render_template_for, false)
           vc_ancestor_calls = defined?(@__vc_ancestor_calls) ? @__vc_ancestor_calls.dup : []
 
           vc_ancestor_calls.unshift(instance_method(:render_template_for))
@@ -575,22 +666,27 @@ module ViewComponent
       end
 
       # @private
-      def compiled?
-        compiler.compiled?
+      def __vc_compiled?
+        __vc_compiler.compiled?
       end
 
-      # @private
-      def ensure_compiled
-        compile unless compiled?
+      # Hook called by the compiler after a component is compiled.
+      #
+      # Extensions can override this class method to run logic after
+      # compilation (e.g., generate helpers, register metadata, etc.).
+      #
+      # By default, this is a no-op.
+      def after_compile
+        # no-op by default
       end
 
       # @private
-      def compile(raise_errors: false, force: false)
-        compiler.compile(raise_errors: raise_errors, force: force)
+      def __vc_ensure_compiled
+        __vc_compile unless __vc_compiled?
       end
 
       # @private
-      def compiler
+      def __vc_compiler
         @__vc_compiler ||= Compiler.new(self)
       end
 
@@ -602,8 +698,8 @@ module ViewComponent
       #
       # @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
+        @__vc_provided_collection_parameter = parameter
+        @__vc_initialize_parameters = nil
       end
 
       # Strips trailing whitespace from templates before compiling them.
@@ -632,18 +728,11 @@ module ViewComponent
       # is accepted, as support for collection
       # rendering is optional.
       # @private
-      def validate_collection_parameter!(validate_default: false)
-        parameter = validate_default ? collection_parameter : provided_collection_parameter
+      def __vc_validate_collection_parameter!(validate_default: false)
+        parameter = validate_default ? __vc_collection_parameter : __vc_provided_collection_parameter
 
         return unless parameter
-        return if initialize_parameter_names.include?(parameter) || splatted_keyword_argument_present?
-
-        # 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 EmptyOrInvalidInitializerError.new(name, parameter)
-        end
+        return if __vc_initialize_parameter_names.include?(parameter) || __vc_splatted_keyword_argument_present?
 
         raise MissingCollectionArgumentError.new(name, parameter)
       end
@@ -652,58 +741,58 @@ module ViewComponent
       # invalid parameters that could override the framework's
       # methods.
       # @private
-      def validate_initialization_parameters!
-        return unless initialize_parameter_names.include?(RESERVED_PARAMETER)
+      def __vc_validate_initialization_parameters!
+        return unless __vc_initialize_parameter_names.include?(:content)
 
-        raise ReservedParameterError.new(name, RESERVED_PARAMETER)
+        raise ReservedParameterError.new(name, :content)
       end
 
       # @private
-      def collection_parameter
-        provided_collection_parameter || name && name.demodulize.underscore.chomp("_component").to_sym
+      def __vc_collection_parameter
+        @__vc_provided_collection_parameter ||= name && name.demodulize.underscore.chomp("_component").to_sym
       end
 
       # @private
-      def collection_counter_parameter
-        :"#{collection_parameter}_counter"
+      def __vc_collection_counter_parameter
+        @__vc_collection_counter_parameter ||= :"#{__vc_collection_parameter}_counter"
       end
 
       # @private
-      def counter_argument_present?
-        initialize_parameter_names.include?(collection_counter_parameter)
+      def __vc_counter_argument_present?
+        __vc_initialize_parameter_names.include?(__vc_collection_counter_parameter)
       end
 
       # @private
-      def collection_iteration_parameter
-        :"#{collection_parameter}_iteration"
+      def __vc_collection_iteration_parameter
+        @__vc_collection_iteration_parameter ||= :"#{__vc_collection_parameter}_iteration"
       end
 
       # @private
-      def iteration_argument_present?
-        initialize_parameter_names.include?(collection_iteration_parameter)
+      def __vc_iteration_argument_present?
+        __vc_initialize_parameter_names.include?(__vc_collection_iteration_parameter)
       end
 
       private
 
-      def splatted_keyword_argument_present?
-        initialize_parameters.flatten.include?(:keyrest) &&
-          !initialize_parameters.include?([:keyrest, :**]) # Un-named splatted keyword args don't count!
+      def __vc_splatted_keyword_argument_present?
+        __vc_initialize_parameters.flatten.include?(:keyrest)
       end
 
-      def initialize_parameter_names
-        return attribute_names.map(&:to_sym) if respond_to?(:attribute_names)
-
-        return attribute_types.keys.map(&:to_sym) if Rails::VERSION::MAJOR <= 5 && respond_to?(:attribute_types)
-
-        initialize_parameters.map(&:last)
+      def __vc_initialize_parameter_names
+        @__vc_initialize_parameter_names ||=
+          if respond_to?(:attribute_names)
+            attribute_names.map(&:to_sym)
+          else
+            __vc_initialize_parameters.map(&:last)
+          end
       end
 
-      def initialize_parameters
-        @initialize_parameters ||= instance_method(:initialize).parameters
+      def __vc_initialize_parameters
+        @__vc_initialize_parameters ||= instance_method(:initialize).parameters
       end
 
-      def provided_collection_parameter
-        @provided_collection_parameter ||= nil
+      def __vc_provided_collection_parameter
+        @__vc_provided_collection_parameter ||= nil
       end
     end