view_component 2.50.0 → 2.69.0

data/lib/view_component/base.rb

@@ -4,19 +4,30 @@ require "action_view"
 require "active_support/configurable"
 require "view_component/collection"
 require "view_component/compile_cache"
+require "view_component/compiler"
+require "view_component/config"
 require "view_component/content_areas"
 require "view_component/polymorphic_slots"
-require "view_component/previewable"
+require "view_component/preview"
 require "view_component/slotable"
 require "view_component/slotable_v2"
+require "view_component/translatable"
 require "view_component/with_content_helper"
 
 module ViewComponent
   class Base < ActionView::Base
-    include ActiveSupport::Configurable
+    class << self
+      delegate(*ViewComponent::Config.defaults.keys, to: :config)
+
+      def config
+        @config ||= ViewComponent::Config.defaults
+      end
+    end
+
     include ViewComponent::ContentAreas
-    include ViewComponent::Previewable
+    include ViewComponent::PolymorphicSlots
     include ViewComponent::SlotableV2
+    include ViewComponent::Translatable
     include ViewComponent::WithContentHelper
 
     ViewContextCalledBeforeRenderError = Class.new(StandardError)
@@ -29,8 +40,25 @@ module ViewComponent
     class_attribute :content_areas
     self.content_areas = [] # class_attribute:default doesn't work until Rails 5.2
 
+    # 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
 
+    # 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.
+    #
+    # @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
+
     # 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.
     #
@@ -71,6 +99,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
@@ -91,11 +121,9 @@ 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}, " \
+        raise ArgumentError, "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."
-        )
       end
 
       @__vc_content_evaluated = false
@@ -104,6 +132,11 @@ module ViewComponent
       before_render
 
       if render?
+        # Ensure `content` is evaluated before rendering the template, this is
+        # needed so slots and other side-effects are performed before the
+        # component template is evaluated.
+        content if self.class.use_consistent_rendering_lifecycle
+
         render_template_for(@__vc_variant).to_s + _output_postamble
       else
         ""
@@ -112,6 +145,21 @@ module ViewComponent
       @current_template = old_current_template
     end
 
+    # Subclass components that call `super` inside their template code will cause a
+    # double render if they emit the result:
+    #
+    # ```erb
+    # <%= super %> # double-renders
+    # <% super %> # does not double-render
+    # ```
+    #
+    # Calls `super`, returning `nil` to avoid rendering the result twice.
+    def render_parent
+      mtd = @__vc_variant ? "call_#{@__vc_variant}" : "call"
+      method(mtd).super_method.call
+      nil
+    end
+
     # EXPERIMENTAL: Optional content to be returned after the rendered template.
     #
     # @return [String]
@@ -143,7 +191,8 @@ module ViewComponent
     end
 
     # @private
-    def initialize(*); end
+    def initialize(*)
+    end
 
     # Re-use original view_context if we're not rendering a component.
     #
@@ -153,8 +202,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)
@@ -224,9 +273,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
+      @__vc_variant if defined?(@__vc_variant)
     end
 
     # Use the provided variant instead of the one determined by the current request.
@@ -271,36 +318,51 @@ module ViewComponent
 
     # 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
 
     # Path for component files
     #
-    #     config.view_component.view_component_path = "app/my_components"
+    # ```ruby
+    # config.view_component.view_component_path = "app/my_components"
+    # ```
+    #
+    # Defaults to `nil`. If this is falsy, `app/components` is used.
+    #
+
+    # Evaluate `#content` before `#call` to ensure side-effects are present
+    # during component renders. This will be the default behavior in a future
+    # release.
+    #
+    # ```ruby
+    # config.view_component.use_consistent_rendering_lifecycle = true
+    # ```
     #
-    # Defaults to `app/components`.
+    # Defaults to `false`
     #
-    mattr_accessor :view_component_path, instance_writer: false, default: "app/components"
+    mattr_accessor :use_consistent_rendering_lifecycle, instance_writer: false, default: false
 
     # Parent class for generated components
     #
-    #     config.view_component.component_parent_class = "MyBaseComponent"
+    # ```ruby
+    # config.view_component.component_parent_class = "MyBaseComponent"
+    # ```
     #
     # Defaults to nil. If this is falsy, generators will use
     # "ApplicationComponent" if defined, "ViewComponent::Base" otherwise.
     #
-    mattr_accessor :component_parent_class, instance_writer: false
 
     # Configuration for generators.
     #
@@ -311,25 +373,33 @@ module ViewComponent
     #
     # Always generate a component with a sidecar directory:
     #
-    #     config.view_component.generate.sidecar = true
+    # ```ruby
+    # config.view_component.generate.sidecar = true
+    # ```
     #
     # #### #stimulus_controller
     #
     # Always generate a Stimulus controller alongside the component:
     #
-    #     config.view_component.generate.stimulus_controller = true
+    # ```ruby
+    # config.view_component.generate.stimulus_controller = true
+    # ```
     #
     # #### #locale
     #
     # Always generate translations file alongside the component:
     #
-    #     config.view_component.generate.locale = true
+    # ```ruby
+    # config.view_component.generate.locale = true
+    # ```
     #
     # #### #distinct_locale_files
     #
     # Always generate as many translations files as available locales:
     #
-    #     config.view_component.generate.distinct_locale_files = true
+    # ```ruby
+    # config.view_component.generate.distinct_locale_files = true
+    # ```
     #
     # One file will be generated for each configured `I18n.available_locales`,
     # falling back to `[:en]` when no `available_locales` is defined.
@@ -338,10 +408,11 @@ module ViewComponent
     #
     # Always generate preview alongside the component:
     #
-    #      config.view_component.generate.preview = true
+    # ```ruby
+    # config.view_component.generate.preview = true
+    # ```
     #
     #  Defaults to `false`.
-    mattr_accessor :generate, instance_writer: false, default: ActiveSupport::OrderedOptions.new(false)
 
     class << self
       # @private
@@ -392,7 +463,9 @@ module ViewComponent
 
       # 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 args [Arguments] Arguments to pass to the ViewComponent every time.
@@ -413,10 +486,26 @@ 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)
+              # 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)
+            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.
@@ -426,7 +515,7 @@ module ViewComponent
 
         # 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)}, ""
+          /(.*#{Regexp.quote(ViewComponent::Base.config.view_component_path)})|(\.rb)/, ""
         )
 
         # Set collection parameter to the extended component
@@ -445,8 +534,8 @@ module ViewComponent
       # 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)
+      def compile(raise_errors: false, force: false)
+        compiler.compile(raise_errors: raise_errors, force: force)
       end
 
       # @private
@@ -472,13 +561,35 @@ module ViewComponent
 
       # 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
       end
 
+      # Strips trailing whitespace from templates before compiling them.
+      #
+      # ```ruby
+      # class MyComponent < ViewComponent::Base
+      #   strip_trailing_whitespace
+      # end
+      # ```
+      #
+      # @param value [Boolean] Whether or not 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
       # collection parameter. By default, we don't
       # validate that the default parameter name
@@ -495,20 +606,16 @@ module ViewComponent
         # 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." \
+          raise ArgumentError, "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."
-          )
         end
 
-        raise ArgumentError.new(
-          "The initializer for #{self} doesn't accept the parameter `#{parameter}`, " \
+        raise ArgumentError, "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."
-        )
       end
 
       # Ensure the component initializer doesn't define
@@ -518,19 +625,13 @@ module ViewComponent
       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 " \
+        raise ViewComponent::ComponentError, "#{self} initializer can't accept the parameter `#{RESERVED_PARAMETER}`, as it will override a " \
           "public ViewComponent method. To fix this issue, rename the 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

data/lib/view_component/collection.rb

@@ -10,10 +10,17 @@ module ViewComponent
     delegate :format, to: :component
     delegate :size, to: :@collection
 
+    attr_accessor :__vc_original_view_context
+
+    def set_original_view_context(view_context)
+      self.__vc_original_view_context = view_context
+    end
+
     def render_in(view_context, &block)
       components.map do |component|
+        component.set_original_view_context(__vc_original_view_context)
         component.render_in(view_context, &block)
-      end.join.html_safe # rubocop:disable Rails/OutputSafety
+      end.join.html_safe
     end
 
     def components
@@ -54,7 +61,7 @@ module ViewComponent
     end
 
     def component_options(item, iterator)
-      item_options = { component.collection_parameter => item }
+      item_options = {component.collection_parameter => item}
       item_options[component.collection_counter_parameter] = iterator.index + 1 if component.counter_argument_present?
       item_options[component.collection_iteration_parameter] = iterator.dup if component.iteration_argument_present?
 

data/lib/view_component/compiler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "concurrent-ruby"
+
 module ViewComponent
   class Compiler
     # Lock required to be obtained before compiling the component
@@ -16,7 +18,7 @@ module ViewComponent
 
     def initialize(component_class)
       @component_class = component_class
-      @__vc_compiler_lock = Monitor.new
+      @__vc_compiler_lock = Concurrent::ReadWriteLock.new
     end
 
     def compiled?
@@ -27,10 +29,13 @@ module ViewComponent
       self.class.mode == DEVELOPMENT_MODE
     end
 
-    def compile(raise_errors: false)
-      return if compiled?
+    def compile(raise_errors: false, force: false)
+      return if compiled? && !force
+      return if component_class == ViewComponent::Base
+
+      component_class.superclass.compile(raise_errors: raise_errors) if should_compile_superclass?
 
-      with_lock do
+      with_write_lock do
         CompileCache.invalidate_class!(component_class)
 
         subclass_instance_methods = component_class.instance_methods(false)
@@ -69,30 +74,36 @@ module ViewComponent
             component_class.send(:undef_method, method_name.to_sym)
           end
 
-          component_class.class_eval <<-RUBY, template[:path], -1
+          # rubocop:disable Style/EvalWithLocation
+          component_class.class_eval <<-RUBY, template[:path], 0
           def #{method_name}
-            @output_buffer = ActionView::OutputBuffer.new
             #{compiled_template(template[:path])}
           end
           RUBY
+          # rubocop:enable Style/EvalWithLocation
         end
 
         define_render_template_for
 
+        component_class.build_i18n_backend
         component_class._after_compile
 
         CompileCache.register(component_class)
       end
     end
 
-    def with_lock(&block)
+    def with_write_lock(&block)
       if development?
-        __vc_compiler_lock.synchronize(&block)
+        __vc_compiler_lock.with_write_lock(&block)
       else
         block.call
       end
     end
 
+    def with_read_lock(&block)
+      __vc_compiler_lock.with_read_lock(&block)
+    end
+
     private
 
     attr_reader :component_class
@@ -118,7 +129,7 @@ module ViewComponent
       if development?
         component_class.class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def render_template_for(variant = nil)
-          self.class.compiler.with_lock do
+          self.class.compiler.with_read_lock do
             #{body}
           end
         end
@@ -148,15 +159,15 @@ module ViewComponent
           end
 
           invalid_variants =
-            templates.
-            group_by { |template| template[:variant] }.
-            map { |variant, grouped| variant if grouped.length > 1 }.
-            compact.
-            sort
+            templates
+              .group_by { |template| template[:variant] }
+              .map { |variant, grouped| variant if grouped.length > 1 }
+              .compact
+              .sort
 
           unless invalid_variants.empty?
             errors <<
-              "More than one template found for #{'variant'.pluralize(invalid_variants.count)} " \
+              "More than one template found for #{"variant".pluralize(invalid_variants.count)} " \
               "#{invalid_variants.map { |v| "'#{v}'" }.to_sentence} in #{component_class}. " \
               "There can only be one template file per variant."
           end
@@ -174,8 +185,8 @@ module ViewComponent
             count = duplicate_template_file_and_inline_variant_calls.count
 
             errors <<
-              "Template #{'file'.pluralize(count)} and inline render #{'method'.pluralize(count)} " \
-              "found for #{'variant'.pluralize(count)} " \
+              "Template #{"file".pluralize(count)} and inline render #{"method".pluralize(count)} " \
+              "found for #{"variant".pluralize(count)} " \
               "#{duplicate_template_file_and_inline_variant_calls.map { |v| "'#{v}'" }.to_sentence} " \
               "in #{component_class}. " \
               "There can only be a template file or inline render method per variant."
@@ -233,8 +244,9 @@ module ViewComponent
     end
 
     def compiled_template(file_path)
-      handler = ActionView::Template.handler_for_extension(File.extname(file_path).gsub(".", ""))
+      handler = ActionView::Template.handler_for_extension(File.extname(file_path).delete("."))
       template = File.read(file_path)
+      template.rstrip! if component_class.strip_trailing_whitespace?
 
       if handler.method(:call).parameters.length > 1
         handler.call(component_class, template)
@@ -256,5 +268,14 @@ module ViewComponent
         "call"
       end
     end
+
+    def should_compile_superclass?
+      development? &&
+        templates.empty? &&
+        !(
+          component_class.instance_methods(false).include?(:call) ||
+            component_class.private_instance_methods(false).include?(:call)
+        )
+    end
   end
 end