view_component 2.83.0 → 3.21.0

data/lib/view_component/collection.rb

@@ -7,7 +7,6 @@ module ViewComponent
     include Enumerable
     attr_reader :component
 
-    delegate :format, to: :component
     delegate :size, to: :@collection
 
     attr_accessor :__vc_original_view_context
@@ -20,7 +19,7 @@ module ViewComponent
       components.map do |component|
         component.set_original_view_context(__vc_original_view_context)
         component.render_in(view_context, &block)
-      end.join.html_safe
+      end.join(rendered_spacer(view_context)).html_safe
     end
 
     def components
@@ -41,11 +40,18 @@ module ViewComponent
       components.each(&block)
     end
 
+    # Rails expects us to define `format` on all renderables,
+    # but we do not know the `format` of a ViewComponent until runtime.
+    def format
+      nil
+    end
+
     private
 
-    def initialize(component, object, **options)
+    def initialize(component, object, spacer_component, **options)
       @component = component
       @collection = collection_variable(object || [])
+      @spacer_component = spacer_component
       @options = options
     end
 
@@ -53,19 +59,25 @@ 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)
     end
+
+    def rendered_spacer(view_context)
+      if @spacer_component
+        @spacer_component.set_original_view_context(__vc_original_view_context)
+        @spacer_component.render_in(view_context)
+      else
+        ""
+      end
+    end
   end
 end

data/lib/view_component/compiler.rb

@@ -4,267 +4,226 @@ require "concurrent-ruby"
 
 module ViewComponent
   class Compiler
-    # Compiler mode. Can be either:
-    # * development (a blocking mode which ensures thread safety when redefining the `call` method for components,
+    # Compiler development mode. Can be either:
+    # * true (a blocking mode which ensures thread safety when redefining the `call` method for components,
     #                default in Rails development and test mode)
-    # * production (a non-blocking mode, default in Rails production mode)
-    DEVELOPMENT_MODE = :development
-    PRODUCTION_MODE = :production
+    # * false(a non-blocking mode, default in Rails production mode)
+    class_attribute :development_mode, default: false
 
-    class_attribute :mode, default: PRODUCTION_MODE
-
-    def initialize(component_class)
-      @component_class = component_class
-      @redefinition_lock = Mutex.new
-      @variants_rendering_templates = Set.new
+    def initialize(component)
+      @component = component
+      @lock = Mutex.new
     end
 
     def compiled?
-      CompileCache.compiled?(component_class)
-    end
-
-    def development?
-      self.class.mode == DEVELOPMENT_MODE
+      CompileCache.compiled?(@component)
     end
 
     def compile(raise_errors: false, force: false)
       return if compiled? && !force
-      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)
+      return if @component == ViewComponent::Base
 
-      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
+      @lock.synchronize do
+        # this check is duplicated so that concurrent compile calls can still
+        # early exit
+        return if compiled? && !force
 
-        return false
-      end
+        gather_templates
 
-      if subclass_instance_methods.include?(:before_render_check)
-        ViewComponent::Deprecation.deprecation_warning(
-          "`before_render_check`", :"`before_render`"
-        )
-      end
+        if self.class.development_mode && @templates.any?(&:requires_compiled_superclass?)
+          @component.superclass.compile(raise_errors: raise_errors)
+        end
 
-      if raise_errors
-        component_class.validate_initialization_parameters!
-        component_class.validate_collection_parameter!
-      end
+        if template_errors.present?
+          raise TemplateError.new(template_errors) if raise_errors
 
-      templates.each do |template|
-        # Remove existing compiled template methods,
-        # as Ruby warns when redefining a method.
-        method_name = call_method_name(template[:variant])
-        @variants_rendering_templates << 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
+          # this return is load bearing, and prevents the component from being considered "compiled?"
+          return false
         end
-      end
 
-      define_render_template_for
+        if raise_errors
+          @component.validate_initialization_parameters!
+          @component.validate_collection_parameter!
+        end
 
-      component_class.build_i18n_backend
+        define_render_template_for
 
-      CompileCache.register(component_class)
-    end
+        @component.register_default_slots
+        @component.build_i18n_backend
 
-    def renders_template_for_variant?(variant)
-      @variants_rendering_templates.include?(variant)
+        CompileCache.register(@component)
+      end
     end
 
     private
 
-    attr_reader :component_class, :redefinition_lock
+    attr_reader :templates
 
     def define_render_template_for
-      variant_elsifs = variants.compact.uniq.map do |variant|
-        "elsif variant.to_sym == :'#{variant}'\n    #{call_method_name(variant)}"
-      end.join("\n")
-
-      body = <<-RUBY
-        if variant.nil?
-          call
-        #{variant_elsifs}
+      @templates.each do |template|
+        template.compile_to_component
+      end
+
+      method_body =
+        if @templates.one?
+          @templates.first.safe_method_name_call
+        elsif (template = @templates.find(&:inline?))
+          template.safe_method_name_call
         else
-          call
-        end
-      RUBY
+          branches = []
+
+          @templates.each do |template|
+            conditional =
+              if template.inline_call?
+                "variant&.to_sym == #{template.variant.inspect}"
+              else
+                [
+                  template.default_format? ? "(format == #{ViewComponent::Base::VC_INTERNAL_DEFAULT_FORMAT.inspect} || format.nil?)" : "format == #{template.format.inspect}",
+                  template.variant.nil? ? "variant.nil?" : "variant&.to_sym == #{template.variant.inspect}"
+                ].join(" && ")
+              end
+
+            branches << [conditional, template.safe_method_name_call]
+          end
 
-      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}
+          out = branches.each_with_object(+"") do |(conditional, branch_body), memo|
+            memo << "#{(!memo.present?) ? "if" : "elsif"} #{conditional}\n  #{branch_body}\n"
+          end
+          out << "else\n  #{templates.find { _1.variant.nil? && _1.default_format? }.safe_method_name_call}\nend"
         end
-        RUBY
+
+      @component.silence_redefinition_of_method(:render_template_for)
+      @component.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+      def render_template_for(variant = nil, format = nil)
+        #{method_body}
       end
+      RUBY
     end
 
     def template_errors
-      @__vc_template_errors ||=
-        begin
-          errors = []
+      @_template_errors ||= begin
+        errors = []
 
-          if (templates + inline_calls).empty?
-            errors << "Couldn't find a template file or inline render method for #{component_class}."
-          end
+        errors << "Couldn't find a template file or inline render method for #{@component}." if @templates.empty?
 
-          if templates.count { |template| template[:variant].nil? } > 1
-            errors <<
-              "More than one template found for #{component_class}. " \
-              "There can only be one default template file per component."
-          end
+        # We currently allow components to have both an inline call method and a template for a variant, with the
+        # inline call method overriding the template. We should aim to change this in v4 to instead
+        # raise an error.
+        @templates.reject(&:inline_call?)
+          .map { |template| [template.variant, template.format] }
+          .tally
+          .select { |_, count| count > 1 }
+          .each do |tally|
+          variant, this_format = tally.first
 
-          invalid_variants =
-            templates
-              .group_by { |template| template[:variant] }
-              .map { |variant, grouped| variant if grouped.length > 1 }
-              .compact
-              .sort
-
-          unless invalid_variants.empty?
-            errors <<
-              "More than one template found for #{"variant".pluralize(invalid_variants.count)} " \
-              "#{invalid_variants.map { |v| "'#{v}'" }.to_sentence} in #{component_class}. " \
-              "There can only be one template file per variant."
-          end
+          variant_string = " for variant `#{variant}`" if variant.present?
 
-          if templates.find { |template| template[:variant].nil? } && inline_calls_defined_on_self.include?(:call)
-            errors <<
-              "Template file and inline render method found for #{component_class}. " \
-              "There can only be a template file or inline render method per component."
-          end
+          errors << "More than one #{this_format.upcase} template found#{variant_string} for #{@component}. "
+        end
 
-          duplicate_template_file_and_inline_variant_calls =
-            templates.pluck(:variant) & variants_from_inline_calls(inline_calls_defined_on_self)
+        default_template_types = @templates.each_with_object(Set.new) do |template, memo|
+          next if template.variant
 
-          unless duplicate_template_file_and_inline_variant_calls.empty?
-            count = duplicate_template_file_and_inline_variant_calls.count
+          memo << :template_file if !template.inline_call?
+          memo << :inline_render if template.inline_call? && template.defined_on_self?
 
-            errors <<
-              "Template #{"file".pluralize(count)} and inline render #{"method".pluralize(count)} " \
-              "found for #{"variant".pluralize(count)} " \
-              "#{duplicate_template_file_and_inline_variant_calls.map { |v| "'#{v}'" }.to_sentence} " \
-              "in #{component_class}. " \
-              "There can only be a template file or inline render method per variant."
-          end
+          memo
+        end
 
-          uniq_variants = variants.compact.uniq
-          normalized_variants = uniq_variants.map { |variant| normalized_variant_name(variant) }
+        if default_template_types.length > 1
+          errors <<
+            "Template file and inline render method found for #{@component}. " \
+            "There can only be a template file or inline render method per component."
+        end
 
-          colliding_variants = uniq_variants.select do |variant|
-            normalized_variants.count(normalized_variant_name(variant)) > 1
-          end
+        # If a template has inline calls, they can conflict with template files the component may use
+        # to render. This attempts to catch and raise that issue before run time. For example,
+        # `def render_mobile` would conflict with a sidecar template of `component.html+mobile.erb`
+        duplicate_template_file_and_inline_call_variants =
+          @templates.reject(&:inline_call?).map(&:variant) &
+          @templates.select { _1.inline_call? && _1.defined_on_self? }.map(&:variant)
+
+        unless duplicate_template_file_and_inline_call_variants.empty?
+          count = duplicate_template_file_and_inline_call_variants.count
+
+          errors <<
+            "Template #{"file".pluralize(count)} and inline render #{"method".pluralize(count)} " \
+            "found for #{"variant".pluralize(count)} " \
+            "#{duplicate_template_file_and_inline_call_variants.map { |v| "'#{v}'" }.to_sentence} " \
+            "in #{@component}. There can only be a template file or inline render method per variant."
+        end
 
-          unless colliding_variants.empty?
-            errors <<
-              "Colliding templates #{colliding_variants.sort.map { |v| "'#{v}'" }.to_sentence} " \
-              "found in #{component_class}."
-          end
+        @templates.select(&:variant).each_with_object(Hash.new { |h, k| h[k] = Set.new }) do |template, memo|
+          memo[template.normalized_variant_name] << template.variant
+          memo
+        end.each do |_, variant_names|
+          next unless variant_names.length > 1
 
-          errors
+          errors << "Colliding templates #{variant_names.sort.map { |v| "'#{v}'" }.to_sentence} found in #{@component}."
         end
+
+        errors
+      end
     end
 
-    def templates
+    def gather_templates
       @templates ||=
         begin
-          extensions = ActionView::Template.template_handler_extensions
-
-          component_class.sidecar_files(extensions).each_with_object([]) do |path, memo|
-            pieces = File.basename(path).split(".")
-            memo << {
+          templates = @component.sidecar_files(
+            ActionView::Template.template_handler_extensions
+          ).map do |path|
+            # Extract format and variant from template filename
+            this_format, variant =
+              File
+                .basename(path)     # "variants_component.html+mini.watch.erb"
+                .split(".")[1..-2]  # ["html+mini", "watch"]
+                .join(".")          # "html+mini.watch"
+                .split("+")         # ["html", "mini.watch"]
+                .map(&:to_sym)      # [:html, :"mini.watch"]
+
+            out = Template.new(
+              component: @component,
+              type: :file,
               path: path,
-              variant: pieces[1..-2].join(".").split("+").second&.to_sym,
-              handler: pieces.last
-            }
+              lineno: 0,
+              extension: path.split(".").last,
+              this_format: this_format.to_s.split(".").last&.to_sym, # strip locale from this_format, see #2113
+              variant: variant
+            )
+
+            out
           end
-        end
-    end
 
-    def inline_calls
-      @inline_calls ||=
-        begin
-          # Fetch only ViewComponent ancestor classes to limit the scope of
-          # finding inline calls
-          view_component_ancestors =
-            (
-              component_class.ancestors.take_while { |ancestor| ancestor != ViewComponent::Base } -
-              component_class.included_modules
+          component_instance_methods_on_self = @component.instance_methods(false)
+
+          (
+            @component.ancestors.take_while { |ancestor| ancestor != ViewComponent::Base } - @component.included_modules
+          ).flat_map { |ancestor| ancestor.instance_methods(false).grep(/^call(_|$)/) }
+            .uniq
+            .each do |method_name|
+              templates << Template.new(
+                component: @component,
+                type: :inline_call,
+                this_format: ViewComponent::Base::VC_INTERNAL_DEFAULT_FORMAT,
+                variant: method_name.to_s.include?("call_") ? method_name.to_s.sub("call_", "").to_sym : nil,
+                method_name: method_name,
+                defined_on_self: component_instance_methods_on_self.include?(method_name)
+              )
+            end
+
+          if @component.inline_template.present?
+            templates << Template.new(
+              component: @component,
+              type: :inline,
+              path: @component.inline_template.path,
+              lineno: @component.inline_template.lineno,
+              source: @component.inline_template.source.dup,
+              extension: @component.inline_template.language
             )
+          end
 
-          view_component_ancestors.flat_map { |ancestor| ancestor.instance_methods(false).grep(/^call/) }.uniq
+          templates
         end
     end
-
-    def inline_calls_defined_on_self
-      @inline_calls_defined_on_self ||= component_class.instance_methods(false).grep(/^call/)
-    end
-
-    def variants
-      @__vc_variants = (
-        templates.map { |template| template[:variant] } + variants_from_inline_calls(inline_calls)
-      ).compact.uniq
-    end
-
-    def variants_from_inline_calls(calls)
-      calls.reject { |call| call == :call }.map do |variant_call|
-        variant_call.to_s.sub("call_", "").to_sym
-      end
-    end
-
-    def compiled_template(file_path)
-      handler = ActionView::Template.handler_for_extension(File.extname(file_path).delete("."))
-      template = File.read(file_path)
-      template.rstrip! if component_class.strip_trailing_whitespace?
-
-      if handler.method(:call).parameters.length > 1
-        handler.call(component_class, template)
-      else
-        handler.call(
-          OpenStruct.new(
-            source: template,
-            identifier: component_class.identifier,
-            type: component_class.type
-          )
-        )
-      end
-    end
-
-    def call_method_name(variant)
-      if variant.present? && variants.include?(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? &&
-        !(
-          component_class.instance_methods(false).include?(:call) ||
-            component_class.private_instance_methods(false).include?(:call)
-        )
-    end
   end
 end

data/lib/view_component/config.rb

@@ -17,13 +17,15 @@ module ViewComponent
           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
+          default_preview_layout: nil,
+          capture_compatibility_patch_enabled: false
         })
       end
 
@@ -46,6 +48,12 @@ module ViewComponent
       #
       #     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:
@@ -77,6 +85,19 @@ module ViewComponent
       # 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]
@@ -98,6 +119,13 @@ module ViewComponent
       # 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 default to `false` 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
@@ -124,10 +152,7 @@ module ViewComponent
       # @!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.
+      # Defaults to `['test/components/previews']` relative to your Rails root.
 
       # @!attribute test_controller
       # @return [String]
@@ -141,12 +166,37 @@ 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
+        (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 = ""
@@ -154,19 +204,18 @@ module ViewComponent
       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
 
-    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 %>