view_component 2.82.0 → 3.1.0

data/lib/view_component/capture_compatibility.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  # CaptureCompatibility is a module that patches #capture to fix issues
+  # related to ViewComponent and functionality that relies on `capture`
+  # like forms, capture itself, turbo frames, etc.
+  #
+  # This underlying incompatibility with ViewComponent and capture is
+  # that several features like forms keep a reference to the primary
+  # `ActionView::Base` instance which has its own @output_buffer. When
+  # `#capture` is called on the original `ActionView::Base` instance while
+  # evaluating a block from a ViewComponent the @output_buffer is overridden
+  # in the ActionView::Base instance, and *not* the component. This results
+  # in a double render due to `#capture` implementation details.
+  #
+  # To resolve the issue, we override `#capture` so that we can delegate
+  # the `capture` logic to the ViewComponent that created the block.
+  module CaptureCompatibility
+    def self.included(base)
+      return if base < InstanceMethods
+
+      base.class_eval do
+        alias_method :original_capture, :capture
+      end
+
+      base.prepend(InstanceMethods)
+    end
+
+    module InstanceMethods
+      def capture(*args, &block)
+        # Handle blocks that originate from C code and raise, such as `&:method`
+        return original_capture(*args, &block) if block.source_location.nil?
+
+        block_context = block.binding.receiver
+
+        if block_context != self && block_context.class < ActionView::Base
+          block_context.original_capture(*args, &block)
+        else
+          original_capture(*args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/view_component/collection.rb

@@ -53,16 +53,13 @@ module ViewComponent
       if object.respond_to?(:to_ary)
         object.to_ary
       else
-        raise ArgumentError.new(
-          "The value of the first argument passed to `with_collection` isn't a valid collection. " \
-          "Make sure it responds to `to_ary`."
-        )
+        raise InvalidCollectionArgumentError
       end
     end
 
     def component_options(item, iterator)
       item_options = {component.collection_parameter => item}
-      item_options[component.collection_counter_parameter] = iterator.index + 1 if component.counter_argument_present?
+      item_options[component.collection_counter_parameter] = iterator.index if component.counter_argument_present?
       item_options[component.collection_iteration_parameter] = iterator.dup if component.iteration_argument_present?
 
       @options.merge(item_options)

data/lib/view_component/compiler.rb

@@ -31,50 +31,58 @@ 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)
-
-      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
+        raise TemplateError.new(template_errors) if raise_errors
 
         return false
       end
 
-      if subclass_instance_methods.include?(:before_render_check)
-        ViewComponent::Deprecation.deprecation_warning(
-          "`before_render_check`", :"`before_render`"
-        )
-      end
-
       if raise_errors
         component_class.validate_initialization_parameters!
         component_class.validate_collection_parameter!
       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 has_inline_template?
+        template = component_class.inline_template
 
         redefinition_lock.synchronize do
-          component_class.silence_redefinition_of_method(method_name)
+          component_class.silence_redefinition_of_method("call")
           # rubocop:disable Style/EvalWithLocation
-          component_class.class_eval <<-RUBY, template[:path], 0
-          def #{method_name}
-            #{compiled_template(template[:path])}
+          component_class.class_eval <<-RUBY, template.path, template.lineno
+          def call
+            #{compiled_inline_template(template)}
           end
           RUBY
           # rubocop:enable Style/EvalWithLocation
+
+          component_class.silence_redefinition_of_method("render_template_for")
+          component_class.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def render_template_for(variant = nil)
+            call
+          end
+          RUBY
+        end
+      else
+        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}
+              #{compiled_template(template[:path])}
+            end
+            RUBY
+            # rubocop:enable Style/EvalWithLocation
+          end
         end
-      end
 
-      define_render_template_for
+        define_render_template_for
+      end
 
       component_class.build_i18n_backend
 
@@ -109,12 +117,16 @@ module ViewComponent
       end
     end
 
+    def has_inline_template?
+      component_class.respond_to?(:inline_template) && component_class.inline_template.present?
+    end
+
     def template_errors
       @__vc_template_errors ||=
         begin
           errors = []
 
-          if (templates + inline_calls).empty?
+          if (templates + inline_calls).empty? && !has_inline_template?
             errors << "Couldn't find a template file or inline render method for #{component_class}."
           end
 
@@ -222,9 +234,21 @@ module ViewComponent
       end
     end
 
+    def compiled_inline_template(template)
+      handler = ActionView::Template.handler_for_extension(template.language)
+      template.rstrip! if component_class.strip_trailing_whitespace?
+
+      compile_template(template.source, handler)
+    end
+
     def compiled_template(file_path)
       handler = ActionView::Template.handler_for_extension(File.extname(file_path).delete("."))
       template = File.read(file_path)
+
+      compile_template(template, handler)
+    end
+
+    def compile_template(template, handler)
       template.rstrip! if component_class.strip_trailing_whitespace?
 
       if handler.method(:call).parameters.length > 1
@@ -253,8 +277,7 @@ module ViewComponent
     end
 
     def should_compile_superclass?
-      development? &&
-        templates.empty? &&
+      development? && templates.empty? && !has_inline_template? &&
         !(
           component_class.instance_methods(false).include?(:call) ||
             component_class.private_instance_methods(false).include?(:call)

data/lib/view_component/config.rb

@@ -23,7 +23,8 @@ module ViewComponent
           show_previews: Rails.env.development? || Rails.env.test?,
           preview_paths: default_preview_paths,
           test_controller: "ApplicationController",
-          default_preview_layout: nil
+          default_preview_layout: nil,
+          capture_compatibility_patch_enabled: false
         })
       end
 
@@ -126,9 +127,6 @@ module ViewComponent
       # 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.
@@ -141,6 +139,13 @@ module ViewComponent
       # previews.
       # Defaults to `nil`. If this is falsy, `"component_preview"` is used.
 
+      # @!attribute capture_compatibility_patch_enabled
+      # @return [Boolean]
+      # Enables the experimental capture compatibility patch that makes ViewComponent
+      # compatible with forms, capture, and other built-ins.
+      # previews.
+      # Defaults to `false`.
+
       def default_preview_paths
         return [] unless defined?(Rails.root) && Dir.exist?("#{Rails.root}/test/components/previews")
 
@@ -158,15 +163,6 @@ module ViewComponent
       @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

data/lib/view_component/deprecation.rb

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

data/lib/view_component/docs_builder_component.html.erb

@@ -12,7 +12,11 @@ nav_order: 3
 ## <%= section.heading %>
 
 <% section.methods.each do |method| %>
-### <%== render ViewComponent::DocsBuilderComponent::MethodDoc.new(method) %>
+### <%== render ViewComponent::DocsBuilderComponent::MethodDoc.new(method, section.show_types) %>
+
+<% end %>
+<% section.error_klasses.each do |error_klass| %>
+### <%== render ViewComponent::DocsBuilderComponent::ErrorKlassDoc.new(error_klass, section.show_types) %>
 
 <% end %>
 <% end %>

data/lib/view_component/docs_builder_component.rb

@@ -2,21 +2,40 @@
 
 module ViewComponent
   class DocsBuilderComponent < Base
-    class Section < Struct.new(:heading, :methods, :show_types, keyword_init: true)
-      def initialize(heading: nil, methods: [], show_types: true)
+    class Section < Struct.new(:heading, :methods, :error_klasses, :show_types, keyword_init: true)
+      def initialize(heading: nil, methods: [], error_klasses: [], show_types: true)
         methods.sort_by! { |method| method[:name] }
+        error_klasses.sort!
         super
       end
     end
 
-    class MethodDoc < ViewComponent::Base
-      def initialize(method, section: Section.new(show_types: true))
-        @method = method
-        @section = section
+    class ErrorKlassDoc < ViewComponent::Base
+      def initialize(error_klass, _show_types)
+        @error_klass = error_klass
+      end
+
+      def klass_name
+        @error_klass.gsub("ViewComponent::", "").gsub("::MESSAGE", "")
       end
 
-      def show_types?
-        @section.show_types
+      def error_message
+        ViewComponent.const_get(@error_klass)
+      end
+
+      def call
+        <<~DOCS.chomp
+          `#{klass_name}`
+
+          #{error_message}
+        DOCS
+      end
+    end
+
+    class MethodDoc < ViewComponent::Base
+      def initialize(method, show_types = true)
+        @method = method
+        @show_types = show_types
       end
 
       def deprecated?
@@ -28,7 +47,7 @@ module ViewComponent
       end
 
       def types
-        " → [#{@method.tag(:return).types.join(",")}]" if @method.tag(:return)&.types && show_types?
+        " → [#{@method.tag(:return).types.join(",")}]" if @method.tag(:return)&.types && @show_types
       end
 
       def signature_or_name

data/lib/view_component/engine.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 require "rails"
-require "view_component/base"
+require "view_component/config"
 
 module ViewComponent
   class Engine < Rails::Engine # :nodoc:
-    config.view_component = ViewComponent::Base.config
+    config.view_component = ViewComponent::Config.defaults
 
     rake_tasks do
       load "view_component/rails/tasks/view_component.rake"
@@ -14,9 +14,6 @@ module ViewComponent
     initializer "view_component.set_configs" do |app|
       options = app.config.view_component
 
-      %i[generate preview_controller preview_route show_previews_source].each do |config_option|
-        options[config_option] ||= ViewComponent::Base.public_send(config_option)
-      end
       options.instrumentation_enabled = false if options.instrumentation_enabled.nil?
       options.render_monkey_patch_enabled = true if options.render_monkey_patch_enabled.nil?
       options.show_previews = (Rails.env.development? || Rails.env.test?) if options.show_previews.nil?
@@ -39,6 +36,8 @@ module ViewComponent
 
     initializer "view_component.enable_instrumentation" do |app|
       ActiveSupport.on_load(:view_component) do
+        Base.config = app.config.view_component
+
         if app.config.view_component.instrumentation_enabled.present?
           # :nocov:
           ViewComponent::Base.prepend(ViewComponent::Instrumentation)
@@ -47,6 +46,14 @@ module ViewComponent
       end
     end
 
+    # :nocov:
+    initializer "view_component.enable_capture_patch" do |app|
+      ActiveSupport.on_load(:view_component) do
+        ActionView::Base.include(ViewComponent::CaptureCompatibility) if app.config.view_component.capture_compatibility_patch_enabled
+      end
+    end
+    # :nocov:
+
     initializer "view_component.set_autoload_paths" do |app|
       options = app.config.view_component
 
@@ -143,20 +150,3 @@ module ViewComponent
     end
   end
 end
-
-if RUBY_VERSION < "2.7.0"
-  ViewComponent::Deprecation.deprecation_warning("Support for Ruby versions < 2.7.0")
-end
-
-# :nocov:
-unless defined?(ViewComponent::Base)
-  require "view_component/deprecation"
-
-  ViewComponent::Deprecation.deprecation_warning(
-    "Manually loading the engine",
-    "remove `require \"view_component/engine\"`"
-  )
-
-  require "view_component"
-end
-# :nocov:

data/lib/view_component/errors.rb

@@ -0,0 +1,223 @@
+module ViewComponent
+  class BaseError < StandardError
+    def initialize
+      super(self.class::MESSAGE)
+    end
+  end
+
+  class DuplicateSlotContentError < StandardError
+    MESSAGE =
+      "It looks like a block was provided after calling `with_content` on COMPONENT, " \
+      "which means that ViewComponent doesn't know which content to use.\n\n" \
+      "To fix this issue, use either `with_content` or a block."
+
+    def initialize(klass_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s))
+    end
+  end
+
+  class TemplateError < StandardError
+    def initialize(errors)
+      super(errors.join(", "))
+    end
+  end
+
+  class MultipleInlineTemplatesError < BaseError
+    MESSAGE = "Inline templates can only be defined once per-component."
+  end
+
+  class MissingPreviewTemplateError < StandardError
+    MESSAGE =
+      "A preview template for example EXAMPLE doesn't exist.\n\n" \
+      "To fix this issue, create a template for the example."
+
+    def initialize(example)
+      super(MESSAGE.gsub("EXAMPLE", example))
+    end
+  end
+
+  class DuplicateContentError < StandardError
+    MESSAGE =
+      "It looks like a block was provided after calling `with_content` on COMPONENT, " \
+      "which means that ViewComponent doesn't know which content to use.\n\n" \
+      "To fix this issue, use either `with_content` or a block."
+
+    def initialize(klass_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s))
+    end
+  end
+
+  class EmptyOrInvalidInitializerError < StandardError
+    MESSAGE =
+      "The COMPONENT 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 [the collections docs](https://viewcomponent.org/guide/collections.html) for more information on rendering collections."
+
+    def initialize(klass_name, parameter)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("PARAMETER", parameter.to_s))
+    end
+  end
+
+  class MissingCollectionArgumentError < StandardError
+    MESSAGE =
+      "The initializer for COMPONENT doesn't accept the parameter `PARAMETER`, " \
+      "which is required to render it as a collection.\n\n" \
+      "To fix this issue, update the initializer to accept `PARAMETER`.\n\n" \
+      "See [the collections docs](https://viewcomponent.org/guide/collections.html) for more information on rendering collections."
+
+    def initialize(klass_name, parameter)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("PARAMETER", parameter.to_s))
+    end
+  end
+
+  class ReservedParameterError < StandardError
+    MESSAGE =
+      "COMPONENT initializer can't accept the parameter `PARAMETER`, as it will override a " \
+      "public ViewComponent method. To fix this issue, rename the parameter."
+
+    def initialize(klass_name, parameter)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("PARAMETER", parameter.to_s))
+    end
+  end
+
+  class InvalidCollectionArgumentError < BaseError
+    MESSAGE =
+      "The value of the first argument passed to `with_collection` isn't a valid collection. " \
+      "Make sure it responds to `to_ary`."
+  end
+
+  class ContentSlotNameError < StandardError
+    MESSAGE =
+      "COMPONENT declares a slot named content, which is a reserved word in ViewComponent.\n\n" \
+      "Content passed to a ViewComponent as a block is captured and assigned to the `content` accessor without having to create an explicit slot.\n\n" \
+      "To fix this issue, either use the `content` accessor directly or choose a different slot name."
+
+    def initialize(klass_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s))
+    end
+  end
+
+  class InvalidSlotDefinitionError < BaseError
+    MESSAGE =
+      "Invalid slot definition. Please pass a class, " \
+      "string, or callable (that is proc, lambda, etc)"
+  end
+
+  class SlotPredicateNameError < StandardError
+    MESSAGE =
+      "COMPONENT declares a slot named SLOT_NAME, which ends with a question mark.\n\n" \
+      "This isn't allowed because the ViewComponent framework already provides predicate " \
+      "methods ending in `?`.\n\n" \
+      "To fix this issue, choose a different name."
+
+    def initialize(klass_name, slot_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("SLOT_NAME", slot_name.to_s))
+    end
+  end
+
+  class RedefinedSlotError < StandardError
+    MESSAGE =
+      "COMPONENT declares the SLOT_NAME slot multiple times.\n\n" \
+      "To fix this issue, choose a different slot name."
+
+    def initialize(klass_name, slot_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("SLOT_NAME", slot_name.to_s))
+    end
+  end
+
+  class ReservedSingularSlotNameError < StandardError
+    MESSAGE =
+      "COMPONENT declares a slot named SLOT_NAME, which is a reserved word in the ViewComponent framework.\n\n" \
+      "To fix this issue, choose a different name."
+
+    def initialize(klass_name, slot_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("SLOT_NAME", slot_name.to_s))
+    end
+  end
+
+  class ReservedPluralSlotNameError < StandardError
+    MESSAGE =
+      "COMPONENT declares a slot named SLOT_NAME, which is a reserved word in the ViewComponent framework.\n\n" \
+      "To fix this issue, choose a different name."
+
+    def initialize(klass_name, slot_name)
+      super(MESSAGE.gsub("COMPONENT", klass_name.to_s).gsub("SLOT_NAME", slot_name.to_s))
+    end
+  end
+
+  class ContentAlreadySetForPolymorphicSlotError < StandardError
+    MESSAGE = "Content for slot SLOT_NAME has already been provided."
+
+    def initialize(slot_name)
+      super(MESSAGE.gsub("SLOT_NAME", slot_name.to_s))
+    end
+  end
+
+  class NilWithContentError < BaseError
+    MESSAGE =
+      "No content provided to `#with_content` for #{self}.\n\n" \
+      "To fix this issue, pass a value."
+  end
+
+  class TranslateCalledBeforeRenderError < BaseError
+    MESSAGE =
+      "`#translate` can't be used during initialization as it depends " \
+      "on the view context that only exists once a ViewComponent is passed to " \
+      "the Rails render pipeline.\n\n" \
+      "It's sometimes possible to fix this issue by moving code dependent on " \
+      "`#translate` to a [`#before_render` method](https://viewcomponent.org/api.html#before_render--void)."
+  end
+
+  class HelpersCalledBeforeRenderError < BaseError
+    MESSAGE =
+      "`#helpers` can't be used during initialization as it depends " \
+      "on the view context that only exists once a ViewComponent is passed to " \
+      "the Rails render pipeline.\n\n" \
+      "It's sometimes possible to fix this issue by moving code dependent on " \
+      "`#helpers` to a [`#before_render` method](https://viewcomponent.org/api.html#before_render--void)."
+  end
+
+  class ControllerCalledBeforeRenderError < BaseError
+    MESSAGE =
+      "`#controller` can't be used during initialization, as it depends " \
+      "on the view context that only exists once a ViewComponent is passed to " \
+      "the Rails render pipeline.\n\n" \
+      "It's sometimes possible to fix this issue by moving code dependent on " \
+      "`#controller` to a [`#before_render` method](https://viewcomponent.org/api.html#before_render--void)."
+  end
+
+  class NoMatchingTemplatesForPreviewError < StandardError
+    MESSAGE = "Found 0 matches for templates for TEMPLATE_IDENTIFIER."
+
+    def initialize(template_identifier)
+      super(MESSAGE.gsub("TEMPLATE_IDENTIFIER", template_identifier))
+    end
+  end
+
+  class MultipleMatchingTemplatesForPreviewError < StandardError
+    MESSAGE = "Found multiple templates for TEMPLATE_IDENTIFIER."
+
+    def initialize(template_identifier)
+      super(MESSAGE.gsub("TEMPLATE_IDENTIFIER", template_identifier))
+    end
+  end
+
+  class SystemTestControllerOnlyAllowedInTestError < BaseError
+    MESSAGE = "ViewComponent SystemTest controller must only be called in a test environment for security reasons."
+  end
+
+  class SystemTestControllerNefariousPathError < BaseError
+    MESSAGE = "ViewComponent SystemTest controller attempted to load a file outside of the expected directory."
+  end
+
+  class AlreadyDefinedPolymorphicSlotSetterError < StandardError
+    MESSAGE =
+      "A method called 'SETTER_METHOD_NAME' already exists and would be overwritten by the 'SETTER_NAME' polymorphic " \
+      "slot setter.\n\nPlease choose a different setter name."
+
+    def initialize(setter_method_name, setter_name)
+      super(MESSAGE.gsub("SETTER_METHOD_NAME", setter_method_name.to_s).gsub("SETTER_NAME", setter_name.to_s))
+    end
+  end
+end

data/lib/view_component/inline_template.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ViewComponent # :nodoc:
+  module InlineTemplate
+    extend ActiveSupport::Concern
+    Template = Struct.new(:source, :language, :path, :lineno)
+
+    class_methods do
+      def method_missing(method, *args)
+        return super if !method.end_with?("_template")
+
+        if defined?(@__vc_inline_template_defined) && @__vc_inline_template_defined
+          raise MultipleInlineTemplatesError
+        end
+
+        if args.size != 1
+          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1)"
+        end
+
+        ext = method.to_s.gsub("_template", "")
+        template = args.first
+
+        @__vc_inline_template_language = ext
+
+        caller = caller_locations(1..1)[0]
+        @__vc_inline_template = Template.new(
+          template,
+          ext,
+          caller.absolute_path || caller.path,
+          caller.lineno
+        )
+
+        @__vc_inline_template_defined = true
+      end
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+
+      def respond_to_missing?(method, include_all = false)
+        method.end_with?("_template") || super
+      end
+
+      def inline_template
+        @__vc_inline_template
+      end
+
+      def inline_template_language
+        @__vc_inline_template_language if defined?(@__vc_inline_template_language)
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@__vc_inline_template_language, inline_template_language)
+      end
+    end
+  end
+end