view_component 2.31.0 → 2.35.0

data/lib/rails/generators/component/component_generator.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require "rails/generators/abstract_generator"
+
 module Rails
   module Generators
     class ComponentGenerator < Rails::Generators::NamedBase
+      include ViewComponent::AbstractGenerator
+
       source_root File.expand_path("templates", __dir__)
 
       argument :attributes, type: :array, default: [], banner: "attribute"
@@ -10,7 +14,7 @@ module Rails
       class_option :inline, type: :boolean, default: false
 
       def create_component_file
-        template "component.rb", File.join("app/components", class_path, "#{file_name}_component.rb")
+        template "component.rb", File.join(component_path, class_path, "#{file_name}_component.rb")
       end
 
       hook_for :test_framework
@@ -23,10 +27,6 @@ module Rails
 
       private
 
-      def file_name
-        @_file_name ||= super.sub(/_component\z/i, "")
-      end
-
       def parent_class
         defined?(ApplicationComponent) ? "ApplicationComponent" : "ViewComponent::Base"
       end

data/lib/rails/generators/erb/component_generator.rb

@@ -1,32 +1,23 @@
 # frozen_string_literal: true
 
 require "rails/generators/erb"
+require "rails/generators/abstract_generator"
 
 module Erb
   module Generators
     class ComponentGenerator < Base
+      include ViewComponent::AbstractGenerator
+
       source_root File.expand_path("templates", __dir__)
       class_option :sidecar, type: :boolean, default: false
       class_option :inline, type: :boolean, default: false
 
-      def copy_view_file
-        unless options["inline"]
-          template "component.html.erb", destination
-        end
-      end
-
-      private
-
-      def destination
-        if options["sidecar"]
-          File.join("app/components", class_path, "#{file_name}_component", "#{file_name}_component.html.erb")
-        else
-          File.join("app/components", class_path, "#{file_name}_component.html.erb")
-        end
+      def engine_name
+        "erb"
       end
 
-      def file_name
-        @_file_name ||= super.sub(/_component\z/i, "")
+      def copy_view_file
+        super
       end
     end
   end

data/lib/rails/generators/haml/component_generator.rb

@@ -5,27 +5,17 @@ require "rails/generators/erb/component_generator"
 module Haml
   module Generators
     class ComponentGenerator < Erb::Generators::ComponentGenerator
+      include ViewComponent::AbstractGenerator
+
       source_root File.expand_path("templates", __dir__)
       class_option :sidecar, type: :boolean, default: false
 
-      def copy_view_file
-        if !options["inline"]
-          template "component.html.haml", destination
-        end
-      end
-
-      private
-
-      def destination
-        if options["sidecar"]
-          File.join("app/components", class_path, "#{file_name}_component", "#{file_name}_component.html.haml")
-        else
-          File.join("app/components", class_path, "#{file_name}_component.html.haml")
-        end
+      def engine_name
+        "haml"
       end
 
-      def file_name
-        @_file_name ||= super.sub(/_component\z/i, "")
+      def copy_view_file
+        super
       end
     end
   end

data/lib/rails/generators/slim/component_generator.rb

@@ -5,27 +5,17 @@ require "rails/generators/erb/component_generator"
 module Slim
   module Generators
     class ComponentGenerator < Erb::Generators::ComponentGenerator
+      include ViewComponent::AbstractGenerator
+
       source_root File.expand_path("templates", __dir__)
       class_option :sidecar, type: :boolean, default: false
 
-      def copy_view_file
-        if !options["inline"]
-          template "component.html.slim", destination
-        end
-      end
-
-      private
-
-      def destination
-        if options["sidecar"]
-          File.join("app/components", class_path, "#{file_name}_component", "#{file_name}_component.html.slim")
-        else
-          File.join("app/components", class_path, "#{file_name}_component.html.slim")
-        end
+      def engine_name
+        "slim"
       end
 
-      def file_name
-        @_file_name ||= super.sub(/_component\z/i, "")
+      def copy_view_file
+        super
       end
     end
   end

data/lib/view_component.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "action_view"
 require "active_support/dependencies/autoload"
 
@@ -8,6 +9,7 @@ module ViewComponent
   autoload :Base
   autoload :Compiler
   autoload :ComponentError
+  autoload :Instrumentation
   autoload :Preview
   autoload :PreviewTemplateError
   autoload :TestHelpers

data/lib/view_component/base.rb

@@ -4,6 +4,7 @@ require "action_view"
 require "active_support/configurable"
 require "view_component/collection"
 require "view_component/compile_cache"
+require "view_component/content_areas"
 require "view_component/previewable"
 require "view_component/slotable"
 require "view_component/slotable_v2"
@@ -12,6 +13,7 @@ require "view_component/with_content_helper"
 module ViewComponent
   class Base < ActionView::Base
     include ActiveSupport::Configurable
+    include ViewComponent::ContentAreas
     include ViewComponent::Previewable
     include ViewComponent::SlotableV2
     include ViewComponent::WithContentHelper
@@ -30,6 +32,7 @@ module ViewComponent
     # Hook for allowing components to do work as part of the compilation process.
     #
     # For example, one might compile component-specific assets at this point.
+    # @private TODO: add documentation
     def self._after_compile
       # noop
     end
@@ -58,6 +61,7 @@ module ViewComponent
     # returns:
     # <span title="greeting">Hello, world!</span>
     #
+    # @private
     def render_in(view_context, &block)
       self.class.compile(raise_errors: true)
 
@@ -74,22 +78,24 @@ module ViewComponent
       @virtual_path ||= virtual_path
 
       # For template variants (+phone, +desktop, etc.)
-      @variant ||= @lookup_context.variants.first
+      @__vc_variant ||= @lookup_context.variants.first
 
       # For caching, such as #cache_if
       @current_template = nil unless defined?(@current_template)
       old_current_template = @current_template
       @current_template = self
 
-      raise ArgumentError.new("Block provided after calling `with_content`. Use one or the other.") if block && defined?(@_content_set_by_with_content)
+      if block && defined?(@__vc_content_set_by_with_content)
+        raise ArgumentError.new("Block provided after calling `with_content`. Use one or the other.")
+      end
 
-      @_content_evaluated = false
-      @_render_in_block = block
+      @__vc_content_evaluated = false
+      @__vc_render_in_block = block
 
       before_render
 
       if render?
-        render_template_for(@variant)
+        render_template_for(@__vc_variant).to_s + _output_postamble
       else
         ""
       end
@@ -97,18 +103,36 @@ module ViewComponent
       @current_template = old_current_template
     end
 
+    # EXPERIMENTAL: Optional content to be returned after the rendered template.
+    #
+    # @return [String]
+    def _output_postamble
+      ""
+    end
+
+    # Called before rendering the component. Override to perform operations that depend on having access to the view context, such as helpers.
+    #
+    # @return [void]
     def before_render
       before_render_check
     end
 
+    # Called after rendering the component.
+    #
+    # @deprecated Use `#before_render` instead. Will be removed in v3.0.0.
+    # @return [void]
     def before_render_check
       # noop
     end
 
+    # Override to determine whether the ViewComponent should render.
+    #
+    # @return [Boolean]
     def render?
       true
     end
 
+    # @private
     def initialize(*); end
 
     # Re-use original view_context if we're not rendering a component.
@@ -116,6 +140,8 @@ module ViewComponent
     # 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`.
+    #
+    # @private
     def render(options = {}, args = {}, &block)
       if options.is_a? ViewComponent::Base
         super
@@ -124,60 +150,62 @@ module ViewComponent
       end
     end
 
+    # The current controller. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+    #
+    # @return [ActionController::Base]
     def controller
       raise ViewContextCalledBeforeRenderError, "`controller` can only be called at render time." if view_context.nil?
-      @controller ||= view_context.controller
+
+      @__vc_controller ||= view_context.controller
     end
 
-    # Provides a proxy to access helper methods from the context of the current controller
+    # A proxy through which to access helpers. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+    #
+    # @return [ActionView::Base]
     def helpers
       raise ViewContextCalledBeforeRenderError, "`helpers` can only be called at render time." if view_context.nil?
-      @helpers ||= controller.view_context
+
+      @__vc_helpers ||= controller.view_context
     end
 
     # Exposes .virtual_path as an instance method
+    #
+    # @private
     def virtual_path
       self.class.virtual_path
     end
 
     # For caching, such as #cache_if
+    # @private
     def view_cache_dependencies
       []
     end
 
     # For caching, such as #cache_if
+    #
+    # @private
     def format
       # Ruby 2.6 throws a warning without checking `defined?`, 2.7 does not
-      if defined?(@variant)
-        @variant
-      end
-    end
-
-    # Assign the provided content to the content area accessor
-    def with(area, content = nil, &block)
-      unless content_areas.include?(area)
-        raise ArgumentError.new "Unknown content_area '#{area}' - expected one of '#{content_areas}'"
-      end
-
-      if block_given?
-        content = view_context.capture(&block)
+      if defined?(@__vc_variant)
+        @__vc_variant
       end
-
-      instance_variable_set("@#{area}".to_sym, content)
-      nil
     end
 
+    # Use the provided variant instead of the one determined by the current request.
+    #
+    # @param variant [Symbol] The variant to be used by the component.
+    # @return [self]
     def with_variant(variant)
-      @variant = variant
+      @__vc_variant = variant
 
       self
     end
 
-    # Exposes the current request to the component.
-    # Use sparingly as doing so introduces coupling
-    # that inhibits encapsulation & reuse.
+    # The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+    #
+    # @return [ActionDispatch::Request]
     def request
-      @request ||= controller.request
+      @request ||= controller.request if controller.respond_to?(:request)
     end
 
     private
@@ -185,31 +213,54 @@ module ViewComponent
     attr_reader :view_context
 
     def content
-      return @_content if defined?(@_content)
-      @_content_evaluated = true
-
-      @_content = if @view_context && @_render_in_block
-        view_context.capture(self, &@_render_in_block)
-      elsif defined?(@_content_set_by_with_content)
-        @_content_set_by_with_content
-      end
+      @__vc_content_evaluated = true
+      return @__vc_content if defined?(@__vc_content)
+
+      @__vc_content =
+        if @view_context && @__vc_render_in_block
+          view_context.capture(self, &@__vc_render_in_block)
+        elsif defined?(@__vc_content_set_by_with_content)
+          @__vc_content_set_by_with_content
+        end
     end
 
     def content_evaluated?
-      @_content_evaluated
+      @__vc_content_evaluated
     end
 
-    # The controller used for testing components.
-    # Defaults to ApplicationController, but can be configured
-    # on a per-test basis using `with_controller_class`.
-    # This should be set early in the initialization process and should be a string.
+    # Set the controller used for testing components:
+    #
+    #     config.view_component.test_controller = "MyTestController"
+    #
+    # Defaults to ApplicationController. Can also be configured on a per-test
+    # basis using `with_controller_class`.
+    #
     mattr_accessor :test_controller
     @@test_controller = "ApplicationController"
 
-    # Configure if render monkey patches should be included or not in Rails <6.1.
+    # Set if render monkey patches should be included or not in Rails <6.1:
+    #
+    #     config.view_component.render_monkey_patch_enabled = false
+    #
     mattr_accessor :render_monkey_patch_enabled, instance_writer: false, default: true
 
+    # Enable or disable source code previews in component previews:
+    #
+    #     config.view_component.show_previews_source = true
+    #
+    # Defaults to `false`.
+    #
+    mattr_accessor :show_previews_source, instance_writer: false, default: false
+
+    # Path for component files
+    #
+    #     config.view_component.view_component_path = "app/my_components"
+    #
+    # Defaults to "app/components".
+    mattr_accessor :view_component_path, instance_writer: false, default: "app/components"
+
     class << self
+      # @private
       attr_accessor :source_location, :virtual_path
 
       # EXPERIMENTAL: This API is experimental and may be removed at any time.
@@ -219,6 +270,7 @@ module ViewComponent
       # 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
 
@@ -239,11 +291,12 @@ module ViewComponent
         # end
         #
         # Without this, `MyOtherComponent` will not look for `my_component/my_other_component.html.erb`
-        nested_component_files = if name.include?("::") && component_name != filename
-          Dir["#{directory}/#{filename}/#{component_name}.*{#{extensions}}"]
-        else
-          []
-        end
+        nested_component_files =
+          if name.include?("::") && component_name != filename
+            Dir["#{directory}/#{filename}/#{component_name}.*{#{extensions}}"]
+          else
+            []
+          end
 
         # view files in the same directory as the component
         sidecar_files = Dir["#{directory}/#{component_name}.*{#{extensions}}"]
@@ -253,16 +306,24 @@ module ViewComponent
         (sidecar_files - [source_location] + sidecar_directory_files + nested_component_files).uniq
       end
 
-      # Render a component collection.
+      # Render a component for each element in a collection ([documentation](/guide/collections)):
+      #
+      #     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.
       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
       end
 
+      # @private
       def inherited(child)
         # Compile so child will inherit compiled `call_*` template methods that
         # `compile` defines
@@ -280,11 +341,14 @@ module ViewComponent
         child.source_location = caller_locations(1, 10).reject { |l| l.label == "inherited" }[0].absolute_path
 
         # Removes the first part of the path and the extension.
-        child.virtual_path = child.source_location.gsub(%r{(.*app/components)|(\.rb)}, "")
+        child.virtual_path = child.source_location.gsub(
+          %r{(.*#{Regexp.quote(ViewComponent::Base.view_component_path)})|(\.rb)}, ""
+        )
 
         super
       end
 
+      # @private
       def compiled?
         compiler.compiled?
       end
@@ -293,50 +357,39 @@ 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)
       end
 
+      # @private
       def compiler
-        @_compiler ||= Compiler.new(self)
+        @__vc_compiler ||= Compiler.new(self)
       end
 
       # we'll eventually want to update this to support other types
+      # @private
       def type
         "text/html"
       end
 
+      # @private
       def format
         :html
       end
 
+      # @private
       def identifier
         source_location
       end
 
-      def with_content_areas(*areas)
-        ActiveSupport::Deprecation.warn(
-          "`with_content_areas` is deprecated and will be removed in ViewComponent v3.0.0.\n" \
-          "Use slots (https://viewcomponent.org/guide/slots.html) instead."
-        )
-
-        if areas.include?(:content)
-          raise ArgumentError.new ":content is a reserved content area name. Please use another name, such as ':body'"
-        end
-
-        areas.each do |area|
-          define_method area.to_sym do
-            content unless content_evaluated? # ensure content is loaded so content_areas will be defined
-            instance_variable_get(:"@#{area}") if instance_variable_defined?(:"@#{area}")
-          end
-        end
-
-        self.content_areas = areas
-      end
-
-      # Support overriding collection parameter name
-      def with_collection_parameter(param)
-        @provided_collection_parameter = param
+      # Set the parameter name used when rendering elements of a collection ([documentation](/guide/collections)):
+      #
+      #     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
 
       # Ensure the component initializer accepts the
@@ -344,6 +397,7 @@ module ViewComponent
       # validate that the default parameter name
       # is accepted, as support for collection
       # rendering is optional.
+      # @private TODO: add documentation
       def validate_collection_parameter!(validate_default: false)
         parameter = validate_default ? collection_parameter : provided_collection_parameter
 
@@ -368,6 +422,7 @@ module ViewComponent
       # Ensure the component initializer does not define
       # invalid parameters that could override the framework's
       # methods.
+      # @private TODO: add documentation
       def validate_initialization_parameters!
         return unless initialize_parameter_names.include?(RESERVED_PARAMETER)
 
@@ -378,6 +433,7 @@ module ViewComponent
         )
       end
 
+      # @private
       def collection_parameter
         if provided_collection_parameter
           provided_collection_parameter
@@ -386,14 +442,26 @@ module ViewComponent
         end
       end
 
+      # @private
       def collection_counter_parameter
         "#{collection_parameter}_counter".to_sym
       end
 
+      # @private
       def counter_argument_present?
         initialize_parameter_names.include?(collection_counter_parameter)
       end
 
+      # @private
+      def collection_iteration_parameter
+        "#{collection_parameter}_iteration".to_sym
+      end
+
+      # @private
+      def iteration_argument_present?
+        initialize_parameter_names.include?(collection_iteration_parameter)
+      end
+
       private
 
       def initialize_parameter_names