view_component 3.21.0 → 4.0.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24be9824d2f5208831e8de57930415019c781a1245224659efb9258372dcafbc
-  data.tar.gz: 33182c814b14959c85370e274619a3da70ea19906dd40c8d0be0cd12c9f16a2b
+  metadata.gz: e8c0d5be4a21f5c14ed5447caeaffb8d6e51397a1ec786f573bc58d9486fc747
+  data.tar.gz: 332de180e52e1b5eae806fb47e9d1dea4a32374cdf63a0642ca69d3661e4c802
 SHA512:
-  metadata.gz: 0d856adb4c86acc808277c7fcc17291b41328b932b53991db003dccab6e23f2a02177e200065e78d3004f8233df98b0926202138b8b536f67c8f848f876231e2
-  data.tar.gz: a7c6b583fd6eaf4bdb20cdc9d7ca86ed0a5e818e90d1099c5fd799d2127122c058d5d58285251ea0713aeb73d719cabad8ab971e994e0f658767235089953dfd
+  metadata.gz: e298e8e18d147034b30fb60f32a7bbf5d5f42d1235d5947cfeba4e3e1b8ad65a57379f3a3fb361ba7ffdec727687689ceb98b4b893e038a16ea5496663d4423a
+  data.tar.gz: f6e8f8956abde8eac1e4825c09a2554dde1dd80efac74ba541210e2fe663e23399ddc01289ca44dee21e6c3551b32117b88444d9795fbb450b02639ebc9fadbf

data/app/controllers/concerns/view_component/preview_actions.rb

@@ -10,7 +10,7 @@ module ViewComponent
       around_action :set_locale, only: :previews
       before_action :require_local!, unless: :show_previews?
 
-      content_security_policy(false) if respond_to?(:content_security_policy)
+      content_security_policy(false)
 
       # Including helpers here ensures that we're loading the
       # latest version of helpers if code-reloading is enabled

data/app/controllers/view_components_system_test_controller.rb

@@ -1,30 +1,27 @@
 # frozen_string_literal: true
 
 class ViewComponentsSystemTestController < ActionController::Base # :nodoc:
-  before_action :validate_test_env
-  before_action :validate_file_path
+  if Rails.env.test?
+    before_action :validate_file_path
 
-  def self.temp_dir
-    @_tmpdir ||= FileUtils.mkdir_p("./tmp/view_components/").first
-  end
-
-  def system_test_entrypoint
-    render file: @path
-  end
+    def self.temp_dir
+      @_tmpdir ||= FileUtils.mkdir_p("./tmp/view_components/").first
+    end
 
-  private
+    def system_test_entrypoint
+      render file: @path
+    end
 
-  def validate_test_env
-    raise ViewComponent::SystemTestControllerOnlyAllowedInTestError unless Rails.env.test?
-  end
+    private
 
-  # Ensure that the file path is valid and doesn't target files outside
-  # the expected directory (e.g. via a path traversal or symlink attack)
-  def validate_file_path
-    base_path = ::File.realpath(self.class.temp_dir)
-    @path = ::File.realpath(params.permit(:file)[:file], base_path)
-    unless @path.start_with?(base_path)
-      raise ViewComponent::SystemTestControllerNefariousPathError
+    # Ensure that the file path is valid and doesn't target files outside
+    # the expected directory (e.g. via a path traversal or symlink attack)
+    def validate_file_path
+      base_path = ::File.realpath(self.class.temp_dir)
+      @path = ::File.realpath(params.permit(:file)[:file], base_path)
+      unless @path.start_with?(base_path)
+        raise ViewComponent::SystemTestControllerNefariousPathError
+      end
     end
   end
 end

data/app/views/test_mailer/test_asset_email.html.erb

@@ -0,0 +1 @@
+<%= render AssetComponent.new %>

data/app/views/view_components/preview.html.erb

@@ -1,13 +1,5 @@
 <% if @render_args[:component] %>
-  <% if ViewComponent::Base.config.render_monkey_patch_enabled || Rails.version.to_f >= 6.1 %>
-    <%= render(@render_args[:component], @render_args[:args], &@render_args[:block]) %>
-  <% else %>
-    <%= render_component(@render_args[:component], &@render_args[:block]) %>
-  <% end %>
+  <%= render(@render_args[:component], @render_args[:args], &@render_args[:block]) %>
 <% else %>
   <%= render template: @render_args[:template], locals: @render_args[:locals] || {} %>
 <% end %>
-
-<% if ViewComponent::Base.config.show_previews_source %>
-  <%= preview_source %>
-<% end %>

data/docs/CHANGELOG.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Changelog
-nav_order: 5
+nav_order: 6
 ---
 
 <!-- Add unreleased changes under the "main" heading. -->
@@ -10,6 +10,172 @@ nav_order: 5
 
 ## main
 
+## 4.0.0
+
+Almost six years after releasing [v1.0.0](https://github.com/ViewComponent/view_component/releases/tag/v1.0.0), we're proud to ship ViewComponent 4. This release marks a shift towards a Long Term Support model for the project, having reached significant feature maturity. While contributions are always welcome, we're unlikely to accept further breaking changes or major feature additions.
+
+This release makes the following breaking changes:
+
+* BREAKING: `--inline` generator option now generates inline template. Use `--call` to generate `#call` method.
+
+    *Joel Hawksley*
+
+* BREAKING: Remove `use_deprecated_instrumentation_name` configuration option. Events will always use `render.view_component` name.
+
+    *Joel Hawksley*
+
+* BREAKING: Remove `preview_source` functionality. Consider using [Lookbook](https://lookbook.build/) instead.
+
+    *Joel Hawksley*
+
+* BREAKING: Use `Nokogiri::HTML5` instead of `Nokogiri::HTML4` for test helpers.
+
+    *Noah Silvera*, *Joel Hawksley*
+
+* BREAKING: Move generators to a ViewComponent namespace.
+
+  Before, ViewComponent generators pollute the generator namespace with a bunch of top level items, and claim the generic "component" name.
+
+  Now, generators live in a "view_component" module/namespace, so what was before `rails g
+  component` is now `rails g view_component:component`.
+
+    *Paul Sadauskas*
+
+* BREAKING: Require [non-EOL](https://endoflife.date/rails) Rails (`>= 7.1.0`).
+
+    *Joel Hawksley*
+
+* BREAKING: Require [non-EOL](https://www.ruby-lang.org/en/downloads/branches/) Ruby (`>= 3.2.0`).
+
+    *Joel Hawksley*
+
+* BREAKING: Remove `render_component` and `render` monkey patch configured with `render_monkey_patch_enabled`.
+
+    *Joel Hawksley*
+
+* BREAKING: Remove support for variant names containing `.` to be consistent with Rails.
+
+    *Stephen Nelson*
+
+* BREAKING: Use ActionView's `lookup_context` for picking templates instead of the request format.
+
+  3.15 added support for using templates that match the request format, i.e. if `/resource.csv` is requested then
+  ViewComponents would pick `_component.csv.erb` over `_component.html.erb`.
+
+  With this release, the request format is no longer considered and instead ViewComponent will use the Rails logic
+  for picking the most appropriate template type, i.e. the csv template will be used if it matches the `Accept` header
+  or because the controller uses a `respond_to` block to pick the response format.
+
+    *Stephen Nelson*
+
+* BREAKING: Rename internal methods to have `__vc_` prefix if they shouldn't be used by consumers. Make internal constants private. Make `Collection#components`, `Slotable#register_polymorphic_slot` private. Remove unused `ComponentError` class.
+
+    *Joel Hawksley*
+
+* Fix bug where request-aware helpers did not work outside of the request context.
+
+    *Joel Hawksley*, *Stephen Nelson*
+
+* `ViewComponentsSystemTestController` should not be useable outside of test environment
+
+    *Joel Hawksley*, *Stephen Nelson*
+
+* Remove unnecessary ENABLE_RELOADING test suite flag.
+
+    *Joel Hawksley*
+
+* Add test coverage for uncovered code.
+
+    *Joel Hawksley*
+
+* Remove unnecessary `#format` methods that returned `nil`.
+
+    *Joel Hawksley*
+
+* Clean up project dependencies, relaxing versions of development gems.
+
+    *Joel Hawksley*
+
+* Test against `turbo-rails` `v2`.
+
+    *Joel Hawksley*
+
+* Test against `rspec-rails` `v7`.
+
+    *Joel Hawksley*
+
+* Remove unnecessary usage of `ruby2_keywords`.
+
+    *Joel Hawksley*
+
+* Remove unnecessary `respond_to` checks.
+
+    *Tiago Menegaz*, *Joel Hawksley*
+
+* Do not include internal `DocsBuilderComponent` or `YARD::MattrAccessorHandler` in published gem.
+
+    *Joel Hawksley*
+
+* Only lock to `concurrent-ruby` `1.3.4` for Rails 6.1.
+
+    *Joel Hawksley*
+
+* Fix generation of ViewComponent documentation that was broken due to HTML safety issues.
+
+    *Simon Fish*
+
+* Add documentation on how ViewComponent works.
+
+    *Joel Hawksley*
+
+* Clarify that `config.use_deprecated_instrumentation_name` will be removed in v4.
+
+    *Joel Hawksley*
+
+* Run RSpec tests in CI.
+
+    *Joel Hawksley*
+
+## 3.22.0
+
+* Rewrite `ViewComponents at GitHub` documentation as more general `Best practices`.
+
+    *Phil Schalm*, *Joel Hawksley*
+
+* Add unused mechanism for inheriting config from parent modules to enable future engine-local configuration.
+
+    *Simon Fish*
+
+* Improve handling of malformed component edge case when mocking components in tests.
+
+    *Martin Meyerhoff*, *Joel Hawksley*
+
+* Add Content Harmony & Learn To Be to list of companies using ViewComponent.
+
+    *Kane Jamison*
+
+* Clarify error message about render-dependent logic.
+
+  Error messages about render-dependent logic were sometimes inaccurate, saying `during initialization` despite also being raised after a component had been initialized but before it was rendered.
+
+    *Joel Hawksley*
+
+* Remove JS and CSS docs as they proved difficult to maintain and lacked consensus.
+
+    *Joel Hawksley*
+
+* Do not prefix release tags with `v`, per recommendation from @bkuhlmann.
+
+    *Joel Hawksley*
+
+* Add ruby 3.4 support to CI.
+
+    *Reegan Viljoen*
+
+* Add HomeStyler AI to list of companies using ViewComponent.
+
+    *JP Balarini*
+
 ## 3.21.0
 
 * Updates testing docs to include an example of how to use with RSpec.
@@ -218,6 +384,10 @@ nav_order: 5
 
     *Reegan Viljoen*
 
+* Fix a bug where component previews would crash with "undefined local variable or method `preview_source`."
+
+    *Henning Koch*
+
 ## 3.12.1
 
 * Ensure content is rendered correctly for forwarded slots.

data/lib/view_component/base.rb

@@ -9,6 +9,7 @@ require "view_component/config"
 require "view_component/errors"
 require "view_component/inline_template"
 require "view_component/preview"
+require "view_component/request_details"
 require "view_component/slotable"
 require "view_component/slotable_default"
 require "view_component/template"
@@ -25,6 +26,10 @@ module ViewComponent
       #
       # @return [ActiveSupport::OrderedOptions]
       def config
+        module_parents.each do |m|
+          config = m.try(:config).try(:view_component)
+          return config if config
+        end
         ViewComponent::Config.current
       end
     end
@@ -35,9 +40,6 @@ module ViewComponent
     include ViewComponent::Translatable
     include ViewComponent::WithContentHelper
 
-    RESERVED_PARAMETER = :content
-    VC_INTERNAL_DEFAULT_FORMAT = :html
-
     # For CSRF authenticity tokens in forms
     delegate :form_authenticity_token, :protect_against_forgery?, :config, to: :helpers
 
@@ -45,8 +47,7 @@ module ViewComponent
     delegate :content_security_policy_nonce, to: :helpers
 
     # Config option that strips trailing whitespace in templates before compiling them.
-    class_attribute :__vc_strip_trailing_whitespace, instance_accessor: false, instance_predicate: false
-    self.__vc_strip_trailing_whitespace = false # class_attribute:default doesn't work until Rails 5.2
+    class_attribute :__vc_strip_trailing_whitespace, instance_accessor: false, instance_predicate: false, default: false
 
     attr_accessor :__vc_original_view_context
 
@@ -63,6 +64,8 @@ module ViewComponent
       self.__vc_original_view_context = view_context
     end
 
+    using RequestDetails
+
     # Entrypoint for rendering components.
     #
     # - `view_context`: ActionView context from calling view
@@ -72,7 +75,7 @@ module ViewComponent
     #
     # @return [String]
     def render_in(view_context, &block)
-      self.class.compile(raise_errors: true)
+      self.class.__vc_compile(raise_errors: true)
 
       @view_context = view_context
       self.__vc_original_view_context ||= view_context
@@ -81,22 +84,18 @@ module ViewComponent
 
       @lookup_context ||= view_context.lookup_context
 
-      # required for path helpers in older Rails versions
-      @view_renderer ||= view_context.view_renderer
-
       # For content_for
       @view_flow ||= view_context.view_flow
 
       # For i18n
       @virtual_path ||= virtual_path
 
-      # For template variants (+phone, +desktop, etc.)
-      @__vc_variant ||= @lookup_context.variants.first
+      # Describes the inferred request constraints (locales, formats, variants)
+      @__vc_requested_details ||= @lookup_context.vc_requested_details
 
       # For caching, such as #cache_if
       @current_template = nil unless defined?(@current_template)
       old_current_template = @current_template
-      @current_template = self
 
       if block && defined?(@__vc_content_set_by_with_content)
         raise DuplicateContentError.new(self.class.name)
@@ -108,7 +107,7 @@ module ViewComponent
       before_render
 
       if render?
-        rendered_template = render_template_for(@__vc_variant, __vc_request&.format&.to_sym).to_s
+        rendered_template = render_template_for(@__vc_requested_details).to_s
 
         # Avoid allocating new string when output_preamble and output_postamble are blank
         if output_preamble.blank? && output_postamble.blank?
@@ -156,7 +155,7 @@ module ViewComponent
         target_render = self.class.instance_variable_get(:@__vc_ancestor_calls)[@__vc_parent_render_level]
         @__vc_parent_render_level += 1
 
-        target_render.bind_call(self, @__vc_variant)
+        target_render.bind_call(self, @__vc_requested_details)
       ensure
         @__vc_parent_render_level -= 1
       end
@@ -191,6 +190,8 @@ module ViewComponent
       true
     end
 
+    # Override the ActionView::Base initializer so that components
+    # do not need to define their own initializers.
     # @private
     def initialize(*)
     end
@@ -199,7 +200,7 @@ module ViewComponent
     #
     # This prevents an exception when rendering a partial inside of a component that has also been rendered outside
     # of the component. This is due to the partials compiled template method existing in the parent `view_context`,
-    #  and not the component's `view_context`.
+    # and not the component's `view_context`.
     #
     # @private
     def render(options = {}, args = {}, &block)
@@ -267,13 +268,6 @@ module ViewComponent
       []
     end
 
-    # For caching, such as #cache_if
-    #
-    # @private
-    def format
-      @__vc_variant if defined?(@__vc_variant)
-    end
-
     # The current request. Use sparingly as doing so introduces coupling that
     # inhibits encapsulation & reuse, often making testing difficult.
     #
@@ -282,10 +276,9 @@ module ViewComponent
       __vc_request
     end
 
-    # Enables consumers to override request/@request
-    #
     # @private
     def __vc_request
+      # The current request (if present, as mailers/jobs/etc do not have a request)
       @__vc_request ||= controller.request if controller.respond_to?(:request)
     end
 
@@ -328,7 +321,7 @@ module ViewComponent
     end
 
     def maybe_escape_html(text)
-      return text if __vc_request && !__vc_request.format.html?
+      return text if @current_template && !@current_template.html?
       return text if text.blank?
 
       if text.html_safe?
@@ -361,13 +354,6 @@ module ViewComponent
     # configured on a per-test basis using `with_controller_class`.
     #
 
-    # Set if render monkey patches should be included or not in Rails <6.1:
-    #
-    # ```ruby
-    # config.view_component.render_monkey_patch_enabled = false
-    # ```
-    #
-
     # Path for component files
     #
     # ```ruby
@@ -516,20 +502,20 @@ module ViewComponent
       def inherited(child)
         # Compile so child will inherit compiled `call_*` template methods that
         # `compile` defines
-        compile
+        __vc_compile
 
         # Give the child its own personal #render_template_for to protect against the case when
         # eager loading is disabled and the parent component is rendered before the child. In
         # such a scenario, the parent will override ViewComponent::Base#render_template_for,
         # meaning it will not be called for any children and thus not compile their templates.
-        if !child.instance_methods(false).include?(:render_template_for) && !child.compiled?
+        if !child.instance_methods(false).include?(:render_template_for) && !child.__vc_compiled?
           child.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-            def render_template_for(variant = nil, format = nil)
+            def render_template_for(requested_details)
               # Force compilation here so the compiler always redefines render_template_for.
               # This is mostly a safeguard to prevent infinite recursion.
-              self.class.compile(raise_errors: true, force: true)
-              # .compile replaces this method; call the new one
-              render_template_for(variant, format)
+              self.class.__vc_compile(raise_errors: true, force: true)
+              # .__vc_compile replaces this method; call the new one
+              render_template_for(requested_details)
             end
           RUBY
         end
@@ -568,22 +554,22 @@ module ViewComponent
       end
 
       # @private
-      def compiled?
-        compiler.compiled?
+      def __vc_compiled?
+        __vc_compiler.compiled?
       end
 
       # @private
-      def ensure_compiled
-        compile unless compiled?
+      def __vc_ensure_compiled
+        __vc_compile unless __vc_compiled?
       end
 
       # @private
-      def compile(raise_errors: false, force: false)
-        compiler.compile(raise_errors: raise_errors, force: force)
+      def __vc_compile(raise_errors: false, force: false)
+        __vc_compiler.compile(raise_errors: raise_errors, force: force)
       end
 
       # @private
-      def compiler
+      def __vc_compiler
         @__vc_compiler ||= Compiler.new(self)
       end
 
@@ -625,8 +611,8 @@ module ViewComponent
       # is accepted, as support for collection
       # rendering is optional.
       # @private
-      def validate_collection_parameter!(validate_default: false)
-        parameter = validate_default ? collection_parameter : provided_collection_parameter
+      def __vc_validate_collection_parameter!(validate_default: false)
+        parameter = validate_default ? __vc_collection_parameter : provided_collection_parameter
 
         return unless parameter
         return if initialize_parameter_names.include?(parameter) || splatted_keyword_argument_present?
@@ -645,35 +631,35 @@ module ViewComponent
       # invalid parameters that could override the framework's
       # methods.
       # @private
-      def validate_initialization_parameters!
-        return unless initialize_parameter_names.include?(RESERVED_PARAMETER)
+      def __vc_validate_initialization_parameters!
+        return unless initialize_parameter_names.include?(:content)
 
-        raise ReservedParameterError.new(name, RESERVED_PARAMETER)
+        raise ReservedParameterError.new(name, :content)
       end
 
       # @private
-      def collection_parameter
+      def __vc_collection_parameter
         provided_collection_parameter || name && name.demodulize.underscore.chomp("_component").to_sym
       end
 
       # @private
-      def collection_counter_parameter
-        :"#{collection_parameter}_counter"
+      def __vc_collection_counter_parameter
+        :"#{__vc_collection_parameter}_counter"
       end
 
       # @private
-      def counter_argument_present?
-        initialize_parameter_names.include?(collection_counter_parameter)
+      def __vc_counter_argument_present?
+        initialize_parameter_names.include?(__vc_collection_counter_parameter)
       end
 
       # @private
-      def collection_iteration_parameter
-        :"#{collection_parameter}_iteration"
+      def __vc_collection_iteration_parameter
+        :"#{__vc_collection_parameter}_iteration"
       end
 
       # @private
-      def iteration_argument_present?
-        initialize_parameter_names.include?(collection_iteration_parameter)
+      def __vc_iteration_argument_present?
+        initialize_parameter_names.include?(__vc_collection_iteration_parameter)
       end
 
       private
@@ -686,8 +672,6 @@ module ViewComponent
       def initialize_parameter_names
         return attribute_names.map(&:to_sym) if respond_to?(:attribute_names)
 
-        return attribute_types.keys.map(&:to_sym) if Rails::VERSION::MAJOR <= 5 && respond_to?(:attribute_types)
-
         initialize_parameters.map(&:last)
       end
 

data/lib/view_component/collection.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "action_view/renderer/collection_renderer" if Rails.version.to_f >= 6.1
+require "action_view/renderer/collection_renderer"
 
 module ViewComponent
   class Collection
@@ -22,12 +22,18 @@ module ViewComponent
       end.join(rendered_spacer(view_context)).html_safe
     end
 
+    def each(&block)
+      components.each(&block)
+    end
+
+    private
+
     def components
       return @components if defined? @components
 
       iterator = ActionView::PartialIteration.new(@collection.size)
 
-      component.validate_collection_parameter!(validate_default: true)
+      component.__vc_validate_collection_parameter!(validate_default: true)
 
       @components = @collection.map do |item|
         component.new(**component_options(item, iterator)).tap do |component|
@@ -36,18 +42,6 @@ module ViewComponent
       end
     end
 
-    def each(&block)
-      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, spacer_component, **options)
       @component = component
       @collection = collection_variable(object || [])
@@ -64,9 +58,9 @@ module ViewComponent
     end
 
     def component_options(item, iterator)
-      item_options = {component.collection_parameter => item}
-      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?
+      item_options = {component.__vc_collection_parameter => item}
+      item_options[component.__vc_collection_counter_parameter] = iterator.index if component.__vc_counter_argument_present?
+      item_options[component.__vc_collection_iteration_parameter] = iterator.dup if component.__vc_iteration_argument_present?
 
       @options.merge(item_options)
     end