view_component 2.62.0 → 2.82.0

data/lib/view_component/base.rb

@@ -4,9 +4,11 @@ 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"
@@ -14,10 +16,23 @@ require "view_component/with_content_helper"
 
 module ViewComponent
   class Base < ActionView::Base
-    include ActiveSupport::Configurable
+    class << self
+      delegate(*ViewComponent::Config.defaults.keys, to: :config)
+
+      # Returns the current config.
+      #
+      # @return [ViewComponent::Config]
+      def config
+        @config ||= ViewComponent::Config.defaults
+      end
+
+      # Replaces the entire config. You shouldn't need to use this directly
+      # unless you're building a `ViewComponent::Config` elsewhere.
+      attr_writer :config
+    end
+
     include ViewComponent::ContentAreas
     include ViewComponent::PolymorphicSlots
-    include ViewComponent::Previewable
     include ViewComponent::SlotableV2
     include ViewComponent::Translatable
     include ViewComponent::WithContentHelper
@@ -51,15 +66,6 @@ module ViewComponent
       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.
-    #
-    # For example, one might compile component-specific assets at this point.
-    # @private TODO: add documentation
-    def self._after_compile
-      # noop
-    end
-
     # @!macro [attach] deprecated_generate_mattr_accessor
     #   @method generate_$1
     #   @deprecated Use `#generate.$1` instead. Will be removed in v3.0.0.
@@ -113,11 +119,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
@@ -126,7 +130,7 @@ module ViewComponent
       before_render
 
       if render?
-        render_template_for(@__vc_variant).to_s + _output_postamble
+        render_template_for(@__vc_variant).to_s + output_postamble
       else
         ""
       end
@@ -149,10 +153,10 @@ module ViewComponent
       nil
     end
 
-    # EXPERIMENTAL: Optional content to be returned after the rendered template.
+    # Optional content to be returned after the rendered template.
     #
     # @return [String]
-    def _output_postamble
+    def output_postamble
       ""
     end
 
@@ -262,9 +266,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.
@@ -313,11 +315,9 @@ module ViewComponent
     # 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:
     #
@@ -325,7 +325,6 @@ module ViewComponent
     # config.view_component.render_monkey_patch_enabled = false
     # ```
     #
-    mattr_accessor :render_monkey_patch_enabled, instance_writer: false, default: true
 
     # Path for component files
     #
@@ -333,9 +332,8 @@ module ViewComponent
     # config.view_component.view_component_path = "app/my_components"
     # ```
     #
-    # Defaults to `app/components`.
+    # Defaults to `nil`. If this is falsy, `app/components` is used.
     #
-    mattr_accessor :view_component_path, instance_writer: false, default: "app/components"
 
     # Parent class for generated components
     #
@@ -346,7 +344,6 @@ module ViewComponent
     # 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.
     #
@@ -397,21 +394,19 @@ module ViewComponent
     # ```
     #
     #  Defaults to `false`.
-    mattr_accessor :generate, instance_writer: false, default: ActiveSupport::OrderedOptions.new(false)
 
     class << self
       # @private
       attr_accessor :source_location, :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)
+      # @param extensions [Array<String>] Extensions of which to return matching sidecar files.
+      def sidecar_files(extensions)
         return [] unless source_location
 
         extensions = extensions.join(",")
@@ -489,8 +484,8 @@ module ViewComponent
 
         # 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.
@@ -500,7 +495,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
@@ -585,26 +580,22 @@ module ViewComponent
         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
         # 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
@@ -614,10 +605,8 @@ 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
@@ -647,6 +636,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)
 

data/lib/view_component/compiler.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
+require "concurrent-ruby"
+
 module ViewComponent
   class Compiler
-    # Lock required to be obtained before compiling the component
-    attr_reader :__vc_compiler_lock
-
     # Compiler mode. Can be either:
     # * development (a blocking mode which ensures thread safety when redefining the `call` method for components,
     #                default in Rails development and test mode)
@@ -16,7 +15,7 @@ module ViewComponent
 
     def initialize(component_class)
       @component_class = component_class
-      @__vc_compiler_lock = Monitor.new
+      @redefinition_lock = Mutex.new
     end
 
     def compiled?
@@ -32,46 +31,39 @@ module ViewComponent
       return if component_class == ViewComponent::Base
 
       component_class.superclass.compile(raise_errors: raise_errors) if should_compile_superclass?
+      subclass_instance_methods = component_class.instance_methods(false)
 
-      with_lock do
-        CompileCache.invalidate_class!(component_class)
-
-        subclass_instance_methods = component_class.instance_methods(false)
-
-        if subclass_instance_methods.include?(:with_content) && raise_errors
-          raise ViewComponent::ComponentError.new(
-            "#{component_class} implements a reserved method, `#with_content`.\n\n" \
-            "To fix this issue, change the name of the method."
-          )
-        end
-
-        if template_errors.present?
-          raise ViewComponent::TemplateError.new(template_errors) if raise_errors
+      if subclass_instance_methods.include?(:with_content) && raise_errors
+        raise ViewComponent::ComponentError.new(
+          "#{component_class} implements a reserved method, `#with_content`.\n\n" \
+          "To fix this issue, change the name of the method."
+        )
+      end
 
-          return false
-        end
+      if template_errors.present?
+        raise ViewComponent::TemplateError.new(template_errors) if raise_errors
 
-        if subclass_instance_methods.include?(:before_render_check)
-          ViewComponent::Deprecation.warn(
-            "`#before_render_check` will be removed in v3.0.0.\n\n" \
-            "To fix this issue, use `#before_render` instead."
-          )
-        end
+        return false
+      end
 
-        if raise_errors
-          component_class.validate_initialization_parameters!
-          component_class.validate_collection_parameter!
-        end
+      if subclass_instance_methods.include?(:before_render_check)
+        ViewComponent::Deprecation.deprecation_warning(
+          "`before_render_check`", :"`before_render`"
+        )
+      end
 
-        templates.each do |template|
-          # Remove existing compiled template methods,
-          # as Ruby warns when redefining a method.
-          method_name = call_method_name(template[:variant])
+      if raise_errors
+        component_class.validate_initialization_parameters!
+        component_class.validate_collection_parameter!
+      end
 
-          if component_class.instance_methods.include?(method_name.to_sym)
-            component_class.send(:undef_method, method_name.to_sym)
-          end
+      templates.each do |template|
+        # Remove existing compiled template methods,
+        # as Ruby warns when redefining a method.
+        method_name = call_method_name(template[:variant])
 
+        redefinition_lock.synchronize do
+          component_class.silence_redefinition_of_method(method_name)
           # rubocop:disable Style/EvalWithLocation
           component_class.class_eval <<-RUBY, template[:path], 0
           def #{method_name}
@@ -80,35 +72,22 @@ module ViewComponent
           RUBY
           # rubocop:enable Style/EvalWithLocation
         end
+      end
 
-        define_render_template_for
-
-        component_class.build_i18n_backend
-        component_class._after_compile
+      define_render_template_for
 
-        CompileCache.register(component_class)
-      end
-    end
+      component_class.build_i18n_backend
 
-    def with_lock(&block)
-      if development?
-        __vc_compiler_lock.synchronize(&block)
-      else
-        block.call
-      end
+      CompileCache.register(component_class)
     end
 
     private
 
-    attr_reader :component_class
+    attr_reader :component_class, :redefinition_lock
 
     def define_render_template_for
-      if component_class.instance_methods.include?(:render_template_for)
-        component_class.send(:undef_method, :render_template_for)
-      end
-
       variant_elsifs = variants.compact.uniq.map do |variant|
-        "elsif variant.to_sym == :#{variant}\n    #{call_method_name(variant)}"
+        "elsif variant.to_sym == :'#{variant}'\n    #{call_method_name(variant)}"
       end.join("\n")
 
       body = <<-RUBY
@@ -120,15 +99,8 @@ module ViewComponent
         end
       RUBY
 
-      if development?
-        component_class.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def render_template_for(variant = nil)
-          self.class.compiler.with_lock do
-            #{body}
-          end
-        end
-        RUBY
-      else
+      redefinition_lock.synchronize do
+        component_class.silence_redefinition_of_method(:render_template_for)
         component_class.class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def render_template_for(variant = nil)
           #{body}
@@ -186,6 +158,19 @@ module ViewComponent
               "There can only be a template file or inline render method per variant."
           end
 
+          uniq_variants = variants.compact.uniq
+          normalized_variants = uniq_variants.map { |variant| normalized_variant_name(variant) }
+
+          colliding_variants = uniq_variants.select do |variant|
+            normalized_variants.count(normalized_variant_name(variant)) > 1
+          end
+
+          unless colliding_variants.empty?
+            errors <<
+              "Colliding templates #{colliding_variants.sort.map { |v| "'#{v}'" }.to_sentence} " \
+              "found in #{component_class}."
+          end
+
           errors
         end
     end
@@ -195,11 +180,11 @@ module ViewComponent
         begin
           extensions = ActionView::Template.template_handler_extensions
 
-          component_class._sidecar_files(extensions).each_with_object([]) do |path, memo|
+          component_class.sidecar_files(extensions).each_with_object([]) do |path, memo|
             pieces = File.basename(path).split(".")
             memo << {
               path: path,
-              variant: pieces.second.split("+").second&.to_sym,
+              variant: pieces[1..-2].join(".").split("+").second&.to_sym,
               handler: pieces.last
             }
           end
@@ -257,12 +242,16 @@ module ViewComponent
 
     def call_method_name(variant)
       if variant.present? && variants.include?(variant)
-        "call_#{variant}"
+        "call_#{normalized_variant_name(variant)}"
       else
         "call"
       end
     end
 
+    def normalized_variant_name(variant)
+      variant.to_s.gsub("-", "__").gsub(".", "___")
+    end
+
     def should_compile_superclass?
       development? &&
         templates.empty? &&

data/lib/view_component/config.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "view_component/deprecation"
+
+module ViewComponent
+  class Config
+    class << self
+      # `new` without any arguments initializes the default configuration, but
+      # it's important to differentiate in case that's no longer the case in
+      # future.
+      alias_method :default, :new
+
+      def defaults
+        ActiveSupport::OrderedOptions.new.merge!({
+          generate: default_generate_options,
+          preview_controller: "ViewComponentsController",
+          preview_route: "/rails/view_components",
+          show_previews_source: false,
+          instrumentation_enabled: false,
+          render_monkey_patch_enabled: true,
+          view_component_path: "app/components",
+          component_parent_class: nil,
+          show_previews: Rails.env.development? || Rails.env.test?,
+          preview_paths: default_preview_paths,
+          test_controller: "ApplicationController",
+          default_preview_layout: nil
+        })
+      end
+
+      # @!attribute generate
+      # @return [ActiveSupport::OrderedOptions]
+      # The subset of configuration options relating to generators.
+      #
+      # All options under this namespace default to `false` unless otherwise
+      # stated.
+      #
+      # #### `#sidecar`
+      #
+      # Always generate a component with a sidecar directory:
+      #
+      #     config.view_component.generate.sidecar = true
+      #
+      # #### `#stimulus_controller`
+      #
+      # Always generate a Stimulus controller alongside the component:
+      #
+      #     config.view_component.generate.stimulus_controller = true
+      #
+      # #### `#locale`
+      #
+      # Always generate translations file alongside the component:
+      #
+      #     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
+      #
+      # One file will be generated for each configured `I18n.available_locales`,
+      # falling back to `[:en]` when no `available_locales` is defined.
+      #
+      # #### `#preview`
+      #
+      # Always generate a preview alongside the component:
+      #
+      #      config.view_component.generate.preview = true
+      #
+      # #### #preview_path
+      #
+      # Path to generate preview:
+      #
+      #      config.view_component.generate.preview_path = "test/components/previews"
+      #
+      # Required when there is more than one path defined in preview_paths.
+      # Defaults to `""`. If this is blank, the generator will use
+      # `ViewComponent.config.preview_paths` if defined,
+      # `"test/components/previews"` otherwise
+
+      # @!attribute preview_controller
+      # @return [String]
+      # The controller used for previewing components.
+      # Defaults to `ViewComponentsController`.
+
+      # @!attribute preview_route
+      # @return [String]
+      # The entry route for component previews.
+      # Defaults to `"/rails/view_components"`.
+
+      # @!attribute show_previews_source
+      # @return [Boolean]
+      # Whether to display source code previews in component previews.
+      # Defaults to `false`.
+
+      # @!attribute instrumentation_enabled
+      # @return [Boolean]
+      # Whether ActiveSupport notifications are enabled.
+      # Defaults to `false`.
+
+      # @!attribute render_monkey_patch_enabled
+      # @return [Boolean] Whether the #render method should be monkey patched.
+      # If this is disabled, use `#render_component` or
+      # `#render_component_to_string` instead.
+      # Defaults to `true`.
+
+      # @!attribute view_component_path
+      # @return [String]
+      # The path in which components, their templates, and their sidecars should
+      # be stored.
+      # Defaults to `"app/components"`.
+
+      # @!attribute component_parent_class
+      # @return [String]
+      # The parent class from which generated components will inherit.
+      # Defaults to `nil`. If this is falsy, generators will use
+      # `"ApplicationComponent"` if defined, `"ViewComponent::Base"` otherwise.
+
+      # @!attribute show_previews
+      # @return [Boolean]
+      # Whether component previews are enabled.
+      # Defaults to `true` in development and test environments.
+
+      # @!attribute preview_paths
+      # @return [Array<String>]
+      # The locations in which component previews will be looked up.
+      # Defaults to `['test/component/previews']` relative to your Rails root.
+
+      # @!attribute preview_path
+      # @deprecated Use #preview_paths instead. Will be removed in v3.0.0.
+
+      # @!attribute test_controller
+      # @return [String]
+      # The controller used for testing components.
+      # Can also be configured on a per-test basis using `#with_controller_class`.
+      # Defaults to `ApplicationController`.
+
+      # @!attribute default_preview_layout
+      # @return [String]
+      # A custom default layout used for the previews index page and individual
+      # previews.
+      # Defaults to `nil`. If this is falsy, `"component_preview"` is used.
+
+      def default_preview_paths
+        return [] unless defined?(Rails.root) && Dir.exist?("#{Rails.root}/test/components/previews")
+
+        ["#{Rails.root}/test/components/previews"]
+      end
+
+      def default_generate_options
+        options = ActiveSupport::OrderedOptions.new(false)
+        options.preview_path = ""
+        options
+      end
+    end
+
+    def initialize
+      @config = self.class.defaults
+    end
+
+    def preview_path
+      preview_paths
+    end
+
+    def preview_path=(new_value)
+      ViewComponent::Deprecation.deprecation_warning("`preview_path`", :"`preview_paths`")
+      self.preview_paths = Array.wrap(new_value)
+    end
+
+    delegate_missing_to :config
+
+    private
+
+    attr_reader :config
+  end
+end

data/lib/view_component/content_areas.rb

@@ -31,9 +31,8 @@ module ViewComponent
 
     class_methods do
       def with_content_areas(*areas)
-        ViewComponent::Deprecation.warn(
-          "`with_content_areas` is deprecated and will be removed in ViewComponent v3.0.0.\n\n" \
-          "Use slots (https://viewcomponent.org/guide/slots.html) instead."
+        ViewComponent::Deprecation.deprecation_warning(
+          "`with_content_areas`", "use slots (https://viewcomponent.org/guide/slots.html) instead"
         )
 
         if areas.include?(:content)

data/lib/view_component/deprecation.rb

@@ -3,6 +3,6 @@
 require "active_support/deprecation"
 
 module ViewComponent
-  DEPRECATION_HORIZON = 3
-  Deprecation = ActiveSupport::Deprecation.new(DEPRECATION_HORIZON.to_s, "ViewComponent")
+  DEPRECATION_HORIZON = "3.0.0"
+  Deprecation = ActiveSupport::Deprecation.new(DEPRECATION_HORIZON, "ViewComponent")
 end

data/lib/view_component/docs_builder_component.html.erb

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: API
+title: API reference
 nav_order: 3
 ---
 

data/lib/view_component/docs_builder_component.rb

@@ -57,7 +57,7 @@ module ViewComponent
 
       def call
         <<~DOCS.chomp
-          #{separator}#{signature_or_name}#{types}#{suffix}
+          `#{separator}#{signature_or_name}`#{types}#{suffix}
 
           #{docstring_and_deprecation_text}
         DOCS