view_component 2.83.0 → 3.21.0

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,14 +1,29 @@
 # frozen_string_literal: true
 
 require "rails"
-require "view_component/base"
+require "view_component/config"
+require "view_component/deprecation"
 
 module ViewComponent
   class Engine < Rails::Engine # :nodoc:
-    config.view_component = ViewComponent::Base.config
+    config.view_component = ViewComponent::Config.current
 
-    rake_tasks do
-      load "view_component/rails/tasks/view_component.rake"
+    if Rails.version.to_f < 8.0
+      rake_tasks do
+        load "view_component/rails/tasks/view_component.rake"
+      end
+    else
+      initializer "view_component.stats_directories" do |app|
+        require "rails/code_statistics"
+
+        if Rails.root.join(ViewComponent::Base.view_component_path).directory?
+          Rails::CodeStatistics.register_directory("ViewComponents", ViewComponent::Base.view_component_path)
+        end
+
+        if Rails.root.join("test/components").directory?
+          Rails::CodeStatistics.register_directory("ViewComponent tests", "test/components", test_directory: true)
+        end
+      end
     end
 
     initializer "view_component.set_configs" do |app|
@@ -40,13 +55,27 @@ module ViewComponent
     initializer "view_component.enable_instrumentation" do |app|
       ActiveSupport.on_load(:view_component) do
         if app.config.view_component.instrumentation_enabled.present?
-          # :nocov:
+          # :nocov: Re-executing the below in tests duplicates initializers and causes order-dependent failures.
           ViewComponent::Base.prepend(ViewComponent::Instrumentation)
+          if app.config.view_component.use_deprecated_instrumentation_name
+            ViewComponent::Deprecation.deprecation_warning(
+              "!render.view_component",
+              "Use the new instrumentation key `render.view_component` instead. See https://viewcomponent.org/guide/instrumentation.html"
+            )
+          end
           # :nocov:
         end
       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
 
@@ -65,6 +94,9 @@ module ViewComponent
     initializer "view_component.monkey_patch_render" do |app|
       next if Rails.version.to_f >= 6.1 || !app.config.view_component.render_monkey_patch_enabled
 
+      # :nocov:
+      ViewComponent::Deprecation.deprecation_warning("Monkey patching `render`", "ViewComponent 4.0 will remove the `render` monkey patch")
+
       ActiveSupport.on_load(:action_view) do
         require "view_component/render_monkey_patch"
         ActionView::Base.prepend ViewComponent::RenderMonkeyPatch
@@ -76,11 +108,15 @@ module ViewComponent
         ActionController::Base.prepend ViewComponent::RenderingMonkeyPatch
         ActionController::Base.prepend ViewComponent::RenderToStringMonkeyPatch
       end
+      # :nocov:
     end
 
     initializer "view_component.include_render_component" do |_app|
       next if Rails.version.to_f >= 6.1
 
+      # :nocov:
+      ViewComponent::Deprecation.deprecation_warning("using `render_component`", "ViewComponent 4.0 will remove `render_component`")
+
       ActiveSupport.on_load(:action_view) do
         require "view_component/render_component_helper"
         ActionView::Base.include ViewComponent::RenderComponentHelper
@@ -92,20 +128,21 @@ module ViewComponent
         ActionController::Base.include ViewComponent::RenderingComponentHelper
         ActionController::Base.include ViewComponent::RenderComponentToStringHelper
       end
+      # :nocov:
     end
 
     initializer "static assets" do |app|
-      if app.config.view_component.show_previews
+      if serve_static_preview_assets?(app.config)
         app.middleware.use(::ActionDispatch::Static, "#{root}/app/assets/vendor")
       end
     end
 
+    def serve_static_preview_assets?(app_config)
+      app_config.view_component.show_previews && app_config.public_file_server.enabled
+    end
+
     initializer "compiler mode" do |_app|
-      ViewComponent::Compiler.mode = if Rails.env.development? || Rails.env.test?
-        ViewComponent::Compiler::DEVELOPMENT_MODE
-      else
-        ViewComponent::Compiler::PRODUCTION_MODE
-      end
+      ViewComponent::Compiler.development_mode = (Rails.env.development? || Rails.env.test?)
     end
 
     config.after_initialize do |app|
@@ -137,26 +174,19 @@ module ViewComponent
         end
       end
 
+      # :nocov:
+      if RUBY_VERSION < "3.2.0"
+        ViewComponent::Deprecation.deprecation_warning("Support for Ruby versions < 3.2.0", "ViewComponent v4 will remove support for Ruby versions < 3.2.0 no earlier than April 1, 2025")
+      end
+
+      if Rails.version.to_f < 7.1
+        ViewComponent::Deprecation.deprecation_warning("Support for Rails versions < 7.1", "ViewComponent v4 will remove support for Rails versions < 7.1 no earlier than April 1, 2025")
+      end
+      # :nocov:
+
       app.executor.to_run :before do
         CompileCache.invalidate! unless ActionView::Base.cache_template_loading
       end
     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,240 @@
+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, templates = nil)
+      message = errors.join("\n")
+
+      super(message)
+    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 InvalidSlotNameError < StandardError
+  end
+
+  class SlotPredicateNameError < InvalidSlotNameError
+    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 < InvalidSlotNameError
+    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 < InvalidSlotNameError
+    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 UncountableSlotNameError < InvalidSlotNameError
+    MESSAGE =
+      "COMPONENT declares a slot named SLOT_NAME, which is an uncountable word\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
+
+  # :nocov:
+  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
+  # :nocov:
+
+  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 if defined?(@__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

data/lib/view_component/instrumentation.rb

@@ -10,14 +10,22 @@ module ViewComponent # :nodoc:
 
     def render_in(view_context, &block)
       ActiveSupport::Notifications.instrument(
-        "!render.view_component",
+        notification_name,
         {
           name: self.class.name,
           identifier: self.class.identifier
         }
       ) do
-        super(view_context, &block)
+        super
       end
     end
+
+    private
+
+    def notification_name
+      return "!render.view_component" if ViewComponent::Base.config.use_deprecated_instrumentation_name
+
+      "render.view_component"
+    end
   end
 end

data/lib/view_component/preview.rb

@@ -4,6 +4,11 @@ require "active_support/descendants_tracker"
 
 module ViewComponent # :nodoc:
   class Preview
+    if defined?(Rails.application.routes.url_helpers)
+      # Workaround from https://stackoverflow.com/questions/20853526/make-yard-ignore-certain-class-extensions to appease YARD
+      send(:include, Rails.application.routes.url_helpers)
+    end
+
     include ActionView::Helpers::TagHelper
     include ActionView::Helpers::AssetTagHelper
     extend ActiveSupport::DescendantsTracker
@@ -80,13 +85,7 @@ module ViewComponent # :nodoc:
             Dir["#{path}/#{preview_name}_preview/#{example}.html.*"].first
           end
 
-        if preview_path.nil?
-          raise(
-            PreviewTemplateError,
-            "A preview template for example #{example} doesn't exist.\n\n" \
-            "To fix this issue, create a template for the example."
-          )
-        end
+        raise MissingPreviewTemplateError.new(example) if preview_path.nil?
 
         path = Dir["#{preview_path}/#{preview_name}_preview/#{example}.html.*"].first
         Pathname.new(path)
@@ -103,7 +102,7 @@ module ViewComponent # :nodoc:
 
       def load_previews
         Array(preview_paths).each do |preview_path|
-          Dir["#{preview_path}/**/*_preview.rb"].sort.each { |file| require_dependency file }
+          Dir["#{preview_path}/**/*preview.rb"].sort.each { |file| require_dependency file }
         end
       end
 

data/lib/view_component/rails/tasks/view_component.rake

@@ -3,9 +3,18 @@
 task stats: "view_component:statsetup"
 
 namespace :view_component do
-  task statsetup: :environment do
+  task :statsetup do
+    # :nocov:
     require "rails/code_statistics"
 
-    ::STATS_DIRECTORIES << ["ViewComponents", ViewComponent::Base.view_component_path]
+    if Rails.root.join(ViewComponent::Base.view_component_path).directory?
+      ::STATS_DIRECTORIES << ["ViewComponents", ViewComponent::Base.view_component_path]
+    end
+
+    if Rails.root.join("test/components").directory?
+      ::STATS_DIRECTORIES << ["ViewComponent tests", "test/components"]
+      CodeStatistics::TEST_TYPES << "ViewComponent tests"
+    end
+    # :nocov:
   end
 end