view_component 2.49.1 → 3.23.2

data/lib/view_component/config.rb

@@ -0,0 +1,225 @@
+# 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,
+          use_deprecated_instrumentation_name: true,
+          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,
+          capture_compatibility_patch_enabled: false
+        })
+      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
+      #
+      # #### `#typescript`
+      #
+      # Generate TypeScript files instead of JavaScript files:
+      #
+      #     config.view_component.generate.typescript = 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
+      #
+      # #### `#use_component_path_for_rspec_tests`
+      #
+      # Whether to use the `config.view_component_path` when generating new
+      # RSpec component tests:
+      #
+      #     config.view_component.generate.use_component_path_for_rspec_tests = true
+      #
+      # When set to `true`, the generator will use the `view_component_path` to
+      # decide where to generate the new RSpec component test.
+      # For example, if the `view_component_path` is
+      # `app/views/components`, then the generator will create a new spec file
+      # in `spec/views/components/` rather than the default `spec/components/`.
+
+      # @!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 use_deprecated_instrumentation_name
+      # @return [Boolean]
+      # Whether ActiveSupport Notifications use the private name `"!render.view_component"`
+      # or are made more publicly available via `"render.view_component"`.
+      # Will be removed in next major version.
+      # Defaults to `true`.
+
+      # @!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/components/previews']` relative to your Rails root.
+
+      # @!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.
+
+      # @!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
+        (default_rails_preview_paths + default_rails_engines_preview_paths).uniq
+      end
+
+      def default_rails_preview_paths
+        return [] unless defined?(Rails.root) && Dir.exist?("#{Rails.root}/test/components/previews")
+
+        ["#{Rails.root}/test/components/previews"]
+      end
+
+      def default_rails_engines_preview_paths
+        return [] unless defined?(Rails::Engine)
+
+        registered_rails_engines_with_previews.map do |descendant|
+          "#{descendant.root}/test/components/previews"
+        end
+      end
+
+      def registered_rails_engines_with_previews
+        Rails::Engine.descendants.select do |descendant|
+          defined?(descendant.root) && Dir.exist?("#{descendant.root}/test/components/previews")
+        end
+      end
+
+      def default_generate_options
+        options = ActiveSupport::OrderedOptions.new(false)
+        options.preview_path = ""
+        options
+      end
+    end
+
+    # @!attribute current
+    # @return [ViewComponent::Config]
+    # Returns the current ViewComponent::Config. This is persisted against this
+    # class so that config options remain accessible before the rest of
+    # ViewComponent has loaded. Defaults to an instance of ViewComponent::Config
+    # with all other documented defaults set.
+    class_attribute :current, default: defaults, instance_predicate: false
+
+    def initialize
+      @config = self.class.defaults
+    end
+
+    delegate_missing_to :config
+
+    private
+
+    attr_reader :config
+  end
+end

data/lib/view_component/configurable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Configurable
+    extend ActiveSupport::Concern
+
+    included do
+      next if respond_to?(:config) && config.respond_to?(:view_component) && config.respond_to_missing?(:test_controller)
+
+      include ActiveSupport::Configurable
+
+      configure do |config|
+        config.view_component ||= ActiveSupport::InheritableOptions.new
+      end
+    end
+  end
+end

data/lib/view_component/deprecation.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "active_support/deprecation"
+
+module ViewComponent
+  DEPRECATION_HORIZON = "4.0.0"
+  Deprecation = ActiveSupport::Deprecation.new(DEPRECATION_HORIZON, "ViewComponent")
+end

data/lib/view_component/engine.rb

@@ -1,38 +1,47 @@
 # frozen_string_literal: true
 
 require "rails"
+require "view_component/config"
+require "view_component/deprecation"
 
 module ViewComponent
   class Engine < Rails::Engine # :nodoc:
-    config.view_component = ActiveSupport::OrderedOptions.new
-    config.view_component.preview_paths ||= []
+    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|
       options = app.config.view_component
 
-      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?
-      options.show_previews_source ||= ViewComponent::Base.show_previews_source
+      %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.preview_route ||= ViewComponent::Base.preview_route
-      options.preview_controller ||= ViewComponent::Base.preview_controller
+      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?
 
       if options.show_previews
+        # This is still necessary because when `config.view_component` is declared, `Rails.root` is unspecified.
         options.preview_paths << "#{Rails.root}/test/components/previews" if defined?(Rails.root) && Dir.exist?(
           "#{Rails.root}/test/components/previews"
         )
 
-        if options.preview_path.present?
-          ActiveSupport::Deprecation.warn(
-            "`preview_path` will be removed in v3.0.0. Use `preview_paths` instead."
-          )
-          options.preview_paths << options.preview_path
-        end
-
         if options.show_previews_source
           require "method_source"
 
@@ -41,27 +50,38 @@ module ViewComponent
           end
         end
       end
-
-      ActiveSupport.on_load(:view_component) do
-        options.each { |k, v| send("#{k}=", v) if respond_to?("#{k}=") }
-      end
     end
 
     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
 
       if options.show_previews && !options.preview_paths.empty?
-        ActiveSupport::Dependencies.autoload_paths.concat(options.preview_paths)
+        paths_to_add = options.preview_paths - ActiveSupport::Dependencies.autoload_paths
+        ActiveSupport::Dependencies.autoload_paths.concat(paths_to_add) if paths_to_add.any?
       end
     end
 
@@ -71,15 +91,12 @@ module ViewComponent
       end
     end
 
-    initializer "view_component.compile_config_methods" do
-      ActiveSupport.on_load(:view_component) do
-        config.compile_methods! if config.respond_to?(:compile_methods!)
-      end
-    end
-
     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
@@ -91,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|
+    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
@@ -107,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
 
-    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
+    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.development_mode = (Rails.env.development? || Rails.env.test?)
     end
 
     config.after_initialize do |app|
@@ -146,20 +168,25 @@ module ViewComponent
         end
       end
 
+      if Rails.env.test?
+        app.routes.prepend do
+          get("_system_test_entrypoint", to: "view_components_system_test#system_test_entrypoint")
+        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
-
-# :nocov:
-unless defined?(ViewComponent::Base)
-  ActiveSupport::Deprecation.warn(
-    "This manually engine loading is deprecated and will be removed in v3.0.0. " \
-    "Remove `require \"view_component/engine\"`."
-  )
-
-  require "view_component"
-end
-# :nocov: