view_component 2.35.0 → 2.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aecf7b0c1b767aefa852ac1c72ad9a8f9f579289136c15743e24124e240e3f36
-  data.tar.gz: 9fd3b0e4a7d2411626e4853c4d8bf59d0de2ebf1c09830aa3a8dde78222bcf04
+  metadata.gz: 74a9bb65a4c364b86c92249805629eb7dc5d7dad010e6743a461cd668d6897f3
+  data.tar.gz: ab5bf1fa266b729faebf8bed8b8884300a8fca4462d4ab8a0c6a0dce32153a26
 SHA512:
-  metadata.gz: 7a6954671a016ccc031bc4a1076640ddc6442a6a4de3f6366b8ef485a3e7cb8977afdca103660a67e5c81d510b9539d7a1d804cf27c750cad2c75945e5a33324
-  data.tar.gz: b0ce60068522b0f9fa45e8325d79bfde1534d81edcf690c43709f34f5196f48b1c1e70e0303a49d4b9063c6b366fdd2c1e60890e983af3bfa98a678b8529a4c6
+  metadata.gz: eae497c864c6005b6ec9cea9073d2659b5378e0f0ebde82397a7e8a09e834525293f6b1a25a615198a28ae9ccfc077505c0bdb35def7cbea69aeaa3472dba7a3
+  data.tar.gz: b11a86583fb7886828690d0d9d57ec9db3bf0f99b40f5cc0de5bb8fb6ca54ffd8e6fb65e150cdd2865c8cd71d46e13e9d7adbd3bd846d5ba5996a0a3c4ebf7d0

data/app/controllers/view_components_controller.rb

@@ -56,7 +56,7 @@ class ViewComponentsController < Rails::ApplicationController # :nodoc:
     if preview
       @preview = ViewComponent::Preview.find(preview)
     else
-      raise AbstractController::ActionNotFound, "Component preview '#{params[:path]}' not found"
+      raise AbstractController::ActionNotFound, "Component preview '#{params[:path]}' not found."
     end
   end
 

data/docs/CHANGELOG.md

@@ -7,6 +7,36 @@ title: Changelog
 
 ## main
 
+## 2.36.0
+
+* Add `slot_type` helper method.
+
+    *Jon Palmer*
+
+* Add test case for rendering a ViewComponent with slots in a controller.
+
+    *Simon Fish*
+
+* Add example ViewComponent to documentation landing page.
+
+    *Joel Hawksley*
+
+* Set maximum line length to 120.
+
+    *Joel Hawksley*
+
+* Setting a collection slot with the plural setter (`component.items(array)` for `renders_many :items`)  returns the array of slots.
+
+    *Jon Palmer*
+
+* Update error messages to be more descriptive and helpful.
+
+    *Joel Hawksley*
+
+* Raise an error if the slot name for renders_many is :contents
+
+    *Simon Fish*
+
 ## 2.35.0
 
 * Only load assets for Preview source highlighting if previews are enabled.

data/lib/view_component/base.rb

@@ -86,7 +86,11 @@ module ViewComponent
       @current_template = self
 
       if block && defined?(@__vc_content_set_by_with_content)
-        raise ArgumentError.new("Block provided after calling `with_content`. Use one or the other.")
+        raise ArgumentError.new(
+          "It looks like a block was provided after calling `with_content` on #{self.class.name}, " \
+          "which means that ViewComponent doesn't know which content to use.\n\n" \
+          "To fix this issue, use either `with_content` or a block."
+        )
       end
 
       @__vc_content_evaluated = false
@@ -110,7 +114,8 @@ module ViewComponent
       ""
     end
 
-    # Called before rendering the component. Override to perform operations that depend on having access to the view context, such as helpers.
+    # Called before rendering the component. Override to perform operations that
+    # depend on having access to the view context, such as helpers.
     #
     # @return [void]
     def before_render
@@ -150,20 +155,40 @@ module ViewComponent
       end
     end
 
-    # The current controller. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+    # The current controller. Use sparingly as doing so introduces coupling
+    # that inhibits encapsulation & reuse, often making testing difficult.
     #
     # @return [ActionController::Base]
     def controller
-      raise ViewContextCalledBeforeRenderError, "`controller` can only be called at render time." if view_context.nil?
+      if view_context.nil?
+        raise(
+          ViewContextCalledBeforeRenderError,
+          "`#controller` cannot 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
 
       @__vc_controller ||= view_context.controller
     end
 
-    # A proxy through which to access helpers. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+    # A proxy through which to access helpers. Use sparingly as doing so introduces
+    # coupling that inhibits encapsulation & reuse, often making testing difficult.
     #
     # @return [ActionView::Base]
     def helpers
-      raise ViewContextCalledBeforeRenderError, "`helpers` can only be called at render time." if view_context.nil?
+      if view_context.nil?
+        raise(
+          ViewContextCalledBeforeRenderError,
+          "`#helpers` cannot 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
 
       @__vc_helpers ||= controller.view_context
     end
@@ -201,7 +226,8 @@ module ViewComponent
       self
     end
 
-    # The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+    # The current request. Use sparingly as doing so introduces coupling that
+    # inhibits encapsulation & reuse, often making testing difficult.
     #
     # @return [ActionDispatch::Request]
     def request
@@ -409,13 +435,18 @@ module ViewComponent
         # the component.
         if initialize_parameters.empty?
           raise ArgumentError.new(
-            "#{self} initializer is empty or invalid."
+            "The #{self} 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 https://viewcomponent.org/guide/collections.html for more information on rendering collections."
           )
         end
 
         raise ArgumentError.new(
-          "#{self} initializer must accept " \
-          "`#{parameter}` collection parameter."
+          "The initializer for #{self} does not accept the parameter `#{parameter}`, " \
+          "which is required in order to render it as a collection.\n\n" \
+          "To fix this issue, update the initializer to accept `#{parameter}`.\n\n" \
+          "See https://viewcomponent.org/guide/collections.html for more information on rendering collections."
         )
       end
 
@@ -427,9 +458,8 @@ module ViewComponent
         return unless initialize_parameter_names.include?(RESERVED_PARAMETER)
 
         raise ViewComponent::ComponentError.new(
-          "#{self} initializer cannot contain " \
-          "`#{RESERVED_PARAMETER}` since it will override a " \
-          "public ViewComponent method."
+          "#{self} initializer cannot accept the parameter `#{RESERVED_PARAMETER}`, as it will override a " \
+          "public ViewComponent method. To fix this issue, rename the parameter."
         )
       end
 

data/lib/view_component/collection.rb

@@ -32,7 +32,10 @@ module ViewComponent
       if object.respond_to?(:to_ary)
         object.to_ary
       else
-        raise ArgumentError.new("The value of the argument isn't a valid collection. Make sure it responds to to_ary: #{object.inspect}")
+        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`."
+        )
       end
     end
 

data/lib/view_component/compiler.rb

@@ -16,7 +16,10 @@ module ViewComponent
       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`.")
+        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?
@@ -27,7 +30,8 @@ module ViewComponent
 
       if subclass_instance_methods.include?(:before_render_check)
         ActiveSupport::Deprecation.warn(
-          "`before_render_check` will be removed in v3.0.0. Use `#before_render` instead."
+          "`#before_render_check` will be removed in v3.0.0.\n\n" \
+          "To fix this issue, use `#before_render` instead."
         )
       end
 
@@ -40,7 +44,10 @@ module ViewComponent
         # Remove existing compiled template methods,
         # as Ruby warns when redefining a method.
         method_name = call_method_name(template[:variant])
-        component_class.send(:undef_method, method_name.to_sym) if component_class.instance_methods.include?(method_name.to_sym)
+
+        if component_class.instance_methods.include?(method_name.to_sym)
+          component_class.send(:undef_method, method_name.to_sym)
+        end
 
         component_class.class_eval <<-RUBY, template[:path], -1
           def #{method_name}
@@ -62,7 +69,9 @@ module ViewComponent
     attr_reader :component_class
 
     def define_render_template_for
-      component_class.send(:undef_method, :render_template_for) if component_class.instance_methods.include?(:render_template_for)
+      if component_class.instance_methods.include?(:render_template_for)
+        component_class.send(:undef_method, :render_template_for)
+      end
 
       variant_elsifs = variants.compact.uniq.map do |variant|
         "elsif variant.to_sym == :#{variant}\n    #{call_method_name(variant)}"
@@ -90,7 +99,9 @@ module ViewComponent
           end
 
           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."
+            errors <<
+              "More than one template found for #{component_class}. " \
+              "There can only be one default template file per component."
           end
 
           invalid_variants =
@@ -101,11 +112,16 @@ module ViewComponent
             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."
+            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
 
           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."
+            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
 
           duplicate_template_file_and_inline_variant_calls =
@@ -114,7 +130,12 @@ module ViewComponent
           unless duplicate_template_file_and_inline_variant_calls.empty?
             count = duplicate_template_file_and_inline_variant_calls.count
 
-            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."
+            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
 
           errors
@@ -143,7 +164,10 @@ module ViewComponent
           # 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_class.ancestors.take_while { |ancestor| ancestor != ViewComponent::Base } -
+              component_class.included_modules
+            )
 
           view_component_ancestors.flat_map { |ancestor| ancestor.instance_methods(false).grep(/^call/) }.uniq
         end
@@ -172,7 +196,13 @@ module ViewComponent
       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))
+        handler.call(
+          OpenStruct.new(
+            source: template,
+            identifier: component_class.identifier,
+            type: component_class.type
+          )
+        )
       end
     end
 

data/lib/view_component/content_areas.rb

@@ -14,7 +14,11 @@ module ViewComponent
     # @private
     def with(area, content = nil, &block)
       unless content_areas.include?(area)
-        raise ArgumentError.new "Unknown content_area '#{area}' - expected one of '#{content_areas}'"
+        raise ArgumentError.new(
+          "Unknown content_area '#{area}' for #{self} - expected one of '#{content_areas}'.\n\n" \
+          "To fix this issue, add `with_content_area :#{area}` to #{self} or reference " \
+          "a valid content area."
+        )
       end
 
       if block_given?
@@ -28,12 +32,15 @@ module ViewComponent
     class_methods do
       def with_content_areas(*areas)
         ActiveSupport::Deprecation.warn(
-          "`with_content_areas` is deprecated and will be removed in ViewComponent v3.0.0.\n" \
+          "`with_content_areas` is deprecated and will be removed in ViewComponent v3.0.0.\n\n" \
           "Use slots (https://viewcomponent.org/guide/slots.html) instead."
         )
 
         if areas.include?(:content)
-          raise ArgumentError.new ":content is a reserved content area name. Please use another name, such as ':body'"
+          raise ArgumentError.new(
+            "#{self} defines a content area called :content, which is a reserved name. \n\n" \
+            "To fix this issue, use another name, such as `:body`."
+          )
         end
 
         areas.each do |area|

data/lib/view_component/engine.rb

@@ -110,8 +110,19 @@ module ViewComponent
         app.routes.prepend do
           preview_controller = options.preview_controller.sub(/Controller$/, "").underscore
 
-          get options.preview_route, to: "#{preview_controller}#index", as: :preview_view_components, internal: true
-          get "#{options.preview_route}/*path", to: "#{preview_controller}#previews", as: :preview_view_component, internal: true
+          get(
+            options.preview_route,
+            to: "#{preview_controller}#index",
+            as: :preview_view_components,
+            internal: true
+          )
+
+          get(
+            "#{options.preview_route}/*path",
+            to: "#{preview_controller}#previews",
+            as: :preview_view_component,
+            internal: true
+          )
         end
       end
 

data/lib/view_component/instrumentation.rb

@@ -9,7 +9,11 @@ module ViewComponent # :nodoc:
     end
 
     def render_in(view_context, &block)
-      ActiveSupport::Notifications.instrument("!render.view_component", name: self.class.name, identifier: self.class.identifier) do
+      ActiveSupport::Notifications.instrument(
+        "!render.view_component",
+        name: self.class.name,
+        identifier: self.class.identifier
+      ) do
         super(view_context, &block)
       end
     end

data/lib/view_component/preview.rb

@@ -77,7 +77,11 @@ module ViewComponent # :nodoc:
           end
 
         if preview_path.nil?
-          raise PreviewTemplateError, "preview template for example #{example} does not exist"
+          raise(
+            PreviewTemplateError,
+            "A preview template for example #{example} does not exist.\n\n" \
+            "To fix this issue, create a template for the example."
+          )
         end
 
         path = Dir["#{preview_path}/#{preview_name}_preview/#{example}.html.*"].first

data/lib/view_component/slot_v2.rb

@@ -30,7 +30,13 @@ module ViewComponent
 
       view_context = @parent.send(:view_context)
 
-      raise ArgumentError.new("Block provided after calling `with_content`. Use one or the other.") if defined?(@__vc_content_block) && defined?(@__vc_content_set_by_with_content)
+      if defined?(@__vc_content_block) && defined?(@__vc_content_set_by_with_content)
+        raise ArgumentError.new(
+          "It looks like a block was provided after calling `with_content` on #{self.class.name}, " \
+          "which means that ViewComponent doesn't know which content to use.\n\n" \
+          "To fix this issue, use either `with_content` or a block."
+        )
+      end
 
       @content =
         if defined?(@__vc_component_instance)

data/lib/view_component/slotable_v2.rb

@@ -65,7 +65,7 @@ module ViewComponent
       #     <% end %>
       #   <% end %>
       def renders_one(slot_name, callable = nil)
-        validate_slot_name(slot_name)
+        validate_singular_slot_name(slot_name)
 
         define_method slot_name do |*args, **kwargs, &block|
           if args.empty? && kwargs.empty? && block.nil?
@@ -116,7 +116,7 @@ module ViewComponent
       #     <% end %>
       #   <% end %>
       def renders_many(slot_name, callable = nil)
-        validate_slot_name(slot_name)
+        validate_plural_slot_name(slot_name)
 
         singular_name = ActiveSupport::Inflector.singularize(slot_name)
 
@@ -133,7 +133,7 @@ module ViewComponent
           if collection_args.nil? && block.nil?
             get_slot(slot_name)
           else
-            collection_args.each do |args|
+            collection_args.map do |args|
               set_slot(slot_name, **args, &block)
             end
           end
@@ -142,6 +142,17 @@ module ViewComponent
         register_slot(slot_name, collection: true, callable: callable)
       end
 
+      def slot_type(slot_name)
+        registered_slot = registered_slots[slot_name]
+        if registered_slot
+          registered_slot[:collection] ? :collection : :single
+        else
+          plural_slot_name = ActiveSupport::Inflector.pluralize(slot_name).to_sym
+          plural_registered_slot = registered_slots[plural_slot_name]
+          plural_registered_slot&.fetch(:collection) ? :collection_item : nil
+        end
+      end
+
       # Clone slot configuration into child class
       # see #test_slots_pollution
       def inherited(child)
@@ -174,14 +185,35 @@ module ViewComponent
         self.registered_slots[slot_name] = slot
       end
 
-      def validate_slot_name(slot_name)
+      def validate_plural_slot_name(slot_name)
+        if slot_name.to_sym == :contents
+          raise ArgumentError.new(
+            "#{self} 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."
+          )
+        end
+
+        raise_if_slot_registered(slot_name)
+      end
+
+      def validate_singular_slot_name(slot_name)
         if slot_name.to_sym == :content
-          raise ArgumentError.new("#{slot_name} is not a valid slot name.")
+          raise ArgumentError.new(
+            "#{self} 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."
+          )
         end
 
+        raise_if_slot_registered(slot_name)
+      end
+
+      def raise_if_slot_registered(slot_name)
         if self.registered_slots.key?(slot_name)
           # TODO remove? This breaks overriding slots when slots are inherited
-          raise ArgumentError.new("#{slot_name} slot declared multiple times")
+          raise ArgumentError.new(
+            "#{self} declares the #{slot_name} slot multiple times.\n\n" \
+            "To fix this issue, choose a different slot name."
+          )
         end
       end
     end
@@ -224,7 +256,8 @@ module ViewComponent
         slot.__vc_component_instance = slot_definition[:renderable].new(*args, **kwargs)
       # If class name as a string
       elsif slot_definition[:renderable_class_name]
-        slot.__vc_component_instance = self.class.const_get(slot_definition[:renderable_class_name]).new(*args, **kwargs)
+        slot.__vc_component_instance =
+          self.class.const_get(slot_definition[:renderable_class_name]).new(*args, **kwargs)
       # If passed a lambda
       elsif slot_definition[:renderable_function]
         # Use `bind(self)` to ensure lambda is executed in the context of the

data/lib/view_component/test_helpers.rb

@@ -17,7 +17,13 @@ module ViewComponent
       # We don't have a test case for running an application without capybara installed.
       # It's probably fine to leave this without coverage.
       # :nocov:
-      warn "WARNING in `ViewComponent::TestHelpers`: You must add `capybara` to your Gemfile to use Capybara assertions." if ENV["DEBUG"]
+      if ENV["DEBUG"]
+        warn(
+          "WARNING in `ViewComponent::TestHelpers`: You must add `capybara` " \
+          "to your Gemfile to use Capybara assertions."
+        )
+      end
+
       # :nocov:
     end
 

data/lib/view_component/version.rb

@@ -3,7 +3,7 @@
 module ViewComponent
   module VERSION
     MAJOR = 2
-    MINOR = 35
+    MINOR = 36
     PATCH = 0
 
     STRING = [MAJOR, MINOR, PATCH].join(".")

data/lib/view_component/with_content_helper.rb

@@ -4,7 +4,10 @@ module ViewComponent
   module WithContentHelper
     def with_content(value)
       if value.nil?
-        raise ArgumentError.new("No content provided.")
+        raise ArgumentError.new(
+          "No content provided to `#with_content` for #{self}.\n\n" \
+          "To fix this issue, pass a value."
+        )
       else
         @__vc_content_set_by_with_content = value
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component
 version: !ruby/object:Gem::Version
-  version: 2.35.0
+  version: 2.36.0
 platform: ruby
 authors:
 - GitHub Open Source
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-02 00:00:00.000000000 Z
+date: 2021-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport