view_component 2.17.0

data/app/controllers/view_components_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "rails/application_controller"
+
+class ViewComponentsController < Rails::ApplicationController # :nodoc:
+  prepend_view_path File.expand_path("../views", __dir__)
+
+  around_action :set_locale, only: :previews
+  before_action :find_preview, only: :previews
+  before_action :require_local!, unless: :show_previews?
+
+  if respond_to?(:content_security_policy)
+    content_security_policy(false)
+  end
+
+  def index
+    @previews = ViewComponent::Preview.all
+    @page_title = "Component Previews"
+  end
+
+  def previews
+    if params[:path] == @preview.preview_name
+      @page_title = "Component Previews for #{@preview.preview_name}"
+      render "view_components/previews"
+    else
+      prepend_application_view_paths
+      prepend_preview_examples_view_path
+      @example_name = File.basename(params[:path])
+      @render_args = @preview.render_args(@example_name, params: params.permit!)
+      layout = @render_args[:layout]
+      template = @render_args[:template]
+      locals = @render_args[:locals]
+      opts = {}
+      opts[:layout] = layout if layout.present?
+      opts[:locals] = locals if locals.present?
+      render template, opts # rubocop:disable GitHub/RailsControllerRenderLiteral
+    end
+  end
+
+  private
+
+  def show_previews? # :doc:
+    ViewComponent::Base.show_previews
+  end
+
+  def find_preview # :doc:
+    candidates = []
+    params[:path].to_s.scan(%r{/|$}) { candidates << $` }
+    preview = candidates.detect { |candidate| ViewComponent::Preview.exists?(candidate) }
+
+    if preview
+      @preview = ViewComponent::Preview.find(preview)
+    else
+      raise AbstractController::ActionNotFound, "Component preview '#{params[:path]}' not found"
+    end
+  end
+
+  def set_locale
+    I18n.with_locale(params[:locale] || I18n.default_locale) do
+      yield
+    end
+  end
+
+  def prepend_application_view_paths
+    prepend_view_path Rails.root.join("app/views") if defined?(Rails.root)
+  end
+
+  def prepend_preview_examples_view_path
+    prepend_view_path(ViewComponent::Base.preview_paths)
+  end
+end

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

@@ -0,0 +1,8 @@
+<% @previews.each do |preview| %>
+  <h3><%= link_to preview.preview_name.titleize, preview_view_component_path(preview.preview_name) %></h3>
+  <ul>
+    <% preview.examples.each do |preview_example| %>
+      <li><%= link_to preview_example, preview_view_component_path("#{preview.preview_name}/#{preview_example}") %></li>
+    <% end %>
+  </ul>
+<% end %>

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

@@ -0,0 +1 @@
+<%= render(@render_args[:component], @render_args[:args], &@render_args[:block])%>

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

@@ -0,0 +1,6 @@
+<h3><%= @preview.preview_name.titleize %></h3>
+<ul>
+  <% @preview.examples.each do |example| %>
+    <li><%= link_to example, preview_view_component_path("#{@preview.preview_name}/#{example}") %></li>
+  <% end %>
+</ul>

data/lib/rails/generators/component/USAGE

@@ -0,0 +1,13 @@
+Description:
+============
+    Creates a new component and test.
+    Pass the component name, either CamelCased or under_scored, and an optional list of attributes as arguments.
+
+Example:
+========
+    bin/rails generate component Profile name age
+
+    creates a Profile component and test:
+        Component:    app/components/profile_component.rb
+        Template:     app/components/profile_component.html.erb
+        Test:         test/components/profile_component_test.rb

data/lib/rails/generators/component/component_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Rails
+  module Generators
+    class ComponentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :attributes, type: :array, default: [], banner: "attribute"
+      check_class_collision suffix: "Component"
+
+      def create_component_file
+        template "component.rb", File.join("app/components", class_path, "#{file_name}_component.rb")
+      end
+
+      hook_for :test_framework
+
+      hook_for :template_engine do |instance, template_engine|
+        instance.invoke template_engine, [instance.name]
+      end
+
+      private
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+
+      def parent_class
+        defined?(ApplicationComponent) ? "ApplicationComponent" : "ViewComponent::Base"
+      end
+
+      def initialize_signature
+        return if attributes.blank?
+
+        attributes.map { |attr| "#{attr.name}:" }.join(", ")
+      end
+
+      def initialize_body
+        attributes.map { |attr| "@#{attr.name} = #{attr.name}" }.join("\n    ")
+      end
+    end
+  end
+end

data/lib/rails/generators/component/templates/component.rb.tt

@@ -0,0 +1,7 @@
+class <%= class_name %>Component < <%= parent_class %>
+<%- if initialize_signature -%>
+  def initialize(<%= initialize_signature %>)
+    <%= initialize_body %>
+  end
+<%- end -%>
+end

data/lib/rails/generators/erb/component_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators/erb"
+
+module Erb
+  module Generators
+    class ComponentGenerator < Base
+      source_root File.expand_path("templates", __dir__)
+      class_option :sidecar, type: :boolean, default: false
+
+      def copy_view_file
+        template "component.html.erb", destination
+      end
+
+      private
+
+      def destination
+        if options["sidecar"]
+          File.join("app/components", class_path, "#{file_name}_component", "#{file_name}_component.html.erb")
+        else
+          File.join("app/components", class_path, "#{file_name}_component.html.erb")
+        end
+      end
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+    end
+  end
+end

data/lib/rails/generators/erb/templates/component.html.erb.tt

@@ -0,0 +1 @@
+<div>Add <%= class_name %> template here</div>

data/lib/rails/generators/haml/component_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators/erb/component_generator"
+
+module Haml
+  module Generators
+    class ComponentGenerator < Erb::Generators::ComponentGenerator
+      source_root File.expand_path("templates", __dir__)
+      class_option :sidecar, type: :boolean, default: false
+
+      def copy_view_file
+        template "component.html.haml", destination
+      end
+
+      private
+
+      def destination
+        if options["sidecar"]
+          File.join("app/components", class_path, "#{file_name}_component", "#{file_name}_component.html.haml")
+        else
+          File.join("app/components", class_path, "#{file_name}_component.html.haml")
+        end
+      end
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+    end
+  end
+end

data/lib/rails/generators/haml/templates/component.html.haml.tt

@@ -0,0 +1 @@
+%div Add <%= class_name %> template here

data/lib/rails/generators/rspec/component_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Generators
+    class ComponentGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_test_file
+        template "component_spec.rb", File.join("spec/components", class_path, "#{file_name}_component_spec.rb")
+      end
+
+      private
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+    end
+  end
+end

data/lib/rails/generators/rspec/templates/component_spec.rb.tt

@@ -0,0 +1,13 @@
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Component, type: :component do
+  pending "add some examples to (or delete) #{__FILE__}"
+
+  # it "renders something useful" do
+  #   expect(
+  #     render_inline(described_class.new(attr: "value")) { "Hello, components!" }.css("p").to_html
+  #   ).to include(
+  #     "Hello, components!"
+  #   )
+  # end
+end

data/lib/rails/generators/slim/component_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators/erb/component_generator"
+
+module Slim
+  module Generators
+    class ComponentGenerator < Erb::Generators::ComponentGenerator
+      source_root File.expand_path("templates", __dir__)
+      class_option :sidecar, type: :boolean, default: false
+
+      def copy_view_file
+        template "component.html.slim", destination
+      end
+
+      private
+
+      def destination
+        if options["sidecar"]
+          File.join("app/components", class_path, "#{file_name}_component", "#{file_name}_component.html.slim")
+        else
+          File.join("app/components", class_path, "#{file_name}_component.html.slim")
+        end
+      end
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+    end
+  end
+end

data/lib/rails/generators/slim/templates/component.html.slim.tt

@@ -0,0 +1 @@
+div Add <%= class_name %> template here

data/lib/rails/generators/test_unit/component_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TestUnit
+  module Generators
+    class ComponentGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+      check_class_collision suffix: "ComponentTest"
+
+      def create_test_file
+        template "component_test.rb", File.join("test/components", class_path, "#{file_name}_component_test.rb")
+      end
+
+      private
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+    end
+  end
+end

data/lib/rails/generators/test_unit/templates/component_test.rb.tt

@@ -0,0 +1,10 @@
+require "test_helper"
+
+class <%= class_name %>ComponentTest < ViewComponent::TestCase
+  test "component renders something useful" do
+    # assert_equal(
+    #   %(<span>Hello, components!</span>),
+    #   render_inline(<%= class_name %>Component.new(message: "Hello, components!")).css("span").to_html
+    # )
+  end
+end

data/lib/view_component.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require "action_view"
+require "active_support/dependencies/autoload"
+
+module ViewComponent
+  extend ActiveSupport::Autoload
+
+  autoload :Base
+  autoload :Preview
+  autoload :PreviewTemplateError
+  autoload :TestHelpers
+  autoload :TestCase
+  autoload :TemplateError
+end

data/lib/view_component/base.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "active_support/configurable"
+require "view_component/collection"
+require "view_component/compile_cache"
+require "view_component/previewable"
+require "view_component/slotable"
+
+module ViewComponent
+  class Base < ActionView::Base
+    include ActiveSupport::Configurable
+    include ViewComponent::Previewable
+
+    # For CSRF authenticity tokens in forms
+    delegate :form_authenticity_token, :protect_against_forgery?, :config, to: :helpers
+
+    class_attribute :content_areas
+    self.content_areas = [] # class_attribute:default doesn't work until Rails 5.2
+
+    # Hash of registered Slots
+    class_attribute :slots
+    self.slots = {}
+
+    # Entrypoint for rendering components.
+    #
+    # view_context: ActionView context from calling view
+    # block: optional block to be captured within the view context
+    #
+    # returns HTML that has been escaped by the respective template handler
+    #
+    # Example subclass:
+    #
+    # app/components/my_component.rb:
+    # class MyComponent < ViewComponent::Base
+    #   def initialize(title:)
+    #     @title = title
+    #   end
+    # end
+    #
+    # app/components/my_component.html.erb
+    # <span title="<%= @title %>">Hello, <%= content %>!</span>
+    #
+    # In use:
+    # <%= render MyComponent.new(title: "greeting") do %>world<% end %>
+    # returns:
+    # <span title="greeting">Hello, world!</span>
+    #
+    def render_in(view_context, &block)
+      self.class.compile(raise_errors: true)
+
+      @view_context = view_context
+      @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.)
+      @variant = @lookup_context.variants.first
+
+      # For caching, such as #cache_if
+      @current_template = nil unless defined?(@current_template)
+      old_current_template = @current_template
+      @current_template = self
+
+      # Assign captured content passed to component as a block to @content
+      @content = view_context.capture(self, &block) if block_given?
+
+      before_render
+
+      if render?
+        send(self.class.call_method_name(@variant))
+      else
+        ""
+      end
+    ensure
+      @current_template = old_current_template
+    end
+
+    def before_render
+      before_render_check
+    end
+
+    def before_render_check
+      # noop
+    end
+
+    def render?
+      true
+    end
+
+    def initialize(*); end
+
+    # If trying to render a partial or template inside a component,
+    # pass the render call to the parent view_context.
+    def render(options = {}, args = {}, &block)
+      if options.is_a?(String) || (options.is_a?(Hash) && options.has_key?(:partial))
+        view_context.render(options, args, &block)
+      else
+        super
+      end
+    end
+
+    def controller
+      @controller ||= view_context.controller
+    end
+
+    # Provides a proxy to access helper methods from the context of the current controller
+    def helpers
+      @helpers ||= controller.view_context
+    end
+
+    # Removes the first part of the path and the extension.
+    def virtual_path
+      self.class.source_location.gsub(%r{(.*app/components)|(\.rb)}, "")
+    end
+
+    # For caching, such as #cache_if
+    def view_cache_dependencies
+      []
+    end
+
+    # For caching, such as #cache_if
+    def format
+      @variant
+    end
+
+    # Assign the provided content to the content area accessor
+    def with(area, content = nil, &block)
+      unless content_areas.include?(area)
+        raise ArgumentError.new "Unknown content_area '#{area}' - expected one of '#{content_areas}'"
+      end
+
+      if block_given?
+        content = view_context.capture(&block)
+      end
+
+      instance_variable_set("@#{area}".to_sym, content)
+      nil
+    end
+
+    private
+
+    # Exposes the current request to the component.
+    # Use sparingly as doing so introduces coupling
+    # that inhibits encapsulation & reuse.
+    def request
+      @request ||= controller.request
+    end
+
+    attr_reader :content, :view_context
+
+    # The controller used for testing components.
+    # Defaults to ApplicationController. This should be set early
+    # in the initialization process and should be set to a string.
+    mattr_accessor :test_controller
+    @@test_controller = "ApplicationController"
+
+    # Configure if render monkey patches should be included or not in Rails <6.1.
+    mattr_accessor :render_monkey_patch_enabled, instance_writer: false, default: true
+
+    class << self
+      attr_accessor :source_location
+
+      # Render a component collection.
+      def with_collection(collection, **args)
+        Collection.new(self, collection, **args)
+      end
+
+      # Provide identifier for ActionView template annotations
+      def short_identifier
+        @short_identifier ||= defined?(Rails.root) ? source_location.sub("#{Rails.root}/", "") : source_location
+      end
+
+      def inherited(child)
+        # If we're in Rails, add application url_helpers to the component context
+        if defined?(Rails)
+          child.include Rails.application.routes.url_helpers unless child < Rails.application.routes.url_helpers
+        end
+
+        # Derive the source location of the component Ruby file from the call stack.
+        # We need to ignore `inherited` frames here as they indicate that `inherited`
+        # has been re-defined by the consuming application, likely in ApplicationComponent.
+        child.source_location = caller_locations(1, 10).reject { |l| l.label == "inherited" }[0].absolute_path
+
+        # Clone slot configuration into child class
+        # see #test_slots_pollution
+        child.slots = self.slots.clone
+
+        super
+      end
+
+      def call_method_name(variant)
+        if variant.present? && variants.include?(variant)
+          "call_#{variant}"
+        else
+          "call"
+        end
+      end
+
+      def compiled?
+        CompileCache.compiled?(self)
+      end
+
+      # Compile templates to instance methods, assuming they haven't been compiled already.
+      #
+      # Do as much work as possible in this step, as doing so reduces the amount
+      # of work done each time a component is rendered.
+      def compile(raise_errors: false)
+        return if compiled?
+
+        if template_errors.present?
+          raise ViewComponent::TemplateError.new(template_errors) if raise_errors
+          return false
+        end
+
+        if instance_methods(false).include?(:before_render_check)
+          ActiveSupport::Deprecation.warn(
+            "`before_render_check` will be removed in v3.0.0. Use `before_render` instead."
+          )
+        end
+
+        # Remove any existing singleton methods,
+        # as Ruby warns when redefining a method.
+        remove_possible_singleton_method(:variants)
+        remove_possible_singleton_method(:collection_parameter)
+        remove_possible_singleton_method(:collection_counter_parameter)
+        remove_possible_singleton_method(:counter_argument_present?)
+
+        define_singleton_method(:variants) do
+          templates.map { |template| template[:variant] } + variants_from_inline_calls(inline_calls)
+        end
+
+        define_singleton_method(:collection_parameter) do
+          if provided_collection_parameter
+            provided_collection_parameter
+          else
+            name.demodulize.underscore.chomp("_component").to_sym
+          end
+        end
+
+        define_singleton_method(:collection_counter_parameter) do
+          "#{collection_parameter}_counter".to_sym
+        end
+
+        define_singleton_method(:counter_argument_present?) do
+          instance_method(:initialize).parameters.map(&:second).include?(collection_counter_parameter)
+        end
+
+        validate_collection_parameter! if raise_errors
+
+        # If template name annotations are turned on, a line is dynamically
+        # added with a comment. In this case, we want to return a different
+        # starting line number so errors that are raised will point to the
+        # correct line in the component template.
+        line_number =
+          if ActionView::Base.respond_to?(:annotate_rendered_view_with_filenames) &&
+            ActionView::Base.annotate_rendered_view_with_filenames
+            -2
+          else
+            -1
+          end
+
+        templates.each do |template|
+          # Remove existing compiled template methods,
+          # as Ruby warns when redefining a method.
+          method_name = call_method_name(template[:variant])
+          undef_method(method_name.to_sym) if instance_methods.include?(method_name.to_sym)
+
+          class_eval <<-RUBY, template[:path], line_number
+            def #{method_name}
+              @output_buffer = ActionView::OutputBuffer.new
+              #{compiled_template(template[:path])}
+            end
+          RUBY
+        end
+
+        CompileCache.register self
+      end
+
+      # we'll eventually want to update this to support other types
+      def type
+        "text/html"
+      end
+
+      def format
+        :html
+      end
+
+      def identifier
+        source_location
+      end
+
+      def with_content_areas(*areas)
+        if areas.include?(:content)
+          raise ArgumentError.new ":content is a reserved content area name. Please use another name, such as ':body'"
+        end
+        attr_reader(*areas)
+        self.content_areas = areas
+      end
+
+      # Support overriding collection parameter name
+      def with_collection_parameter(param)
+        @provided_collection_parameter = param
+      end
+
+      # Ensure the component initializer accepts the
+      # collection parameter. By default, we do not
+      # validate that the default parameter name
+      # is accepted, as support for collection
+      # rendering is optional.
+      def validate_collection_parameter!(validate_default: false)
+        parameter = validate_default ? collection_parameter : provided_collection_parameter
+
+        return unless parameter
+        return if initialize_parameters.map(&:last).include?(parameter)
+
+        # If Ruby cannot parse the component class, then the initalize
+        # parameters will be empty and ViewComponent will not be able to render
+        # the component.
+        if initialize_parameters.empty?
+          raise ArgumentError.new(
+            "#{self} initializer is empty or invalid."
+          )
+        end
+
+        raise ArgumentError.new(
+          "#{self} initializer must accept " \
+          "`#{parameter}` collection parameter."
+        )
+      end
+
+      private
+
+      def initialize_parameters
+        instance_method(:initialize).parameters
+      end
+
+      def provided_collection_parameter
+        @provided_collection_parameter ||= nil
+      end
+
+      def compiled_template(file_path)
+        handler = ActionView::Template.handler_for_extension(File.extname(file_path).gsub(".", ""))
+        template = File.read(file_path)
+
+        if handler.method(:call).parameters.length > 1
+          handler.call(self, template)
+        else
+          handler.call(OpenStruct.new(source: template, identifier: identifier, type: type))
+        end
+      end
+
+      def inline_calls
+        @inline_calls ||=
+          begin
+            # Fetch only ViewComponent ancestor classes to limit the scope of
+            # finding inline calls
+            view_component_ancestors =
+              ancestors.take_while { |ancestor| ancestor != ViewComponent::Base } - included_modules
+
+            view_component_ancestors.flat_map { |ancestor| ancestor.instance_methods(false).grep(/^call/) }.uniq
+          end
+      end
+
+      def inline_calls_defined_on_self
+        @inline_calls_defined_on_self ||= instance_methods(false).grep(/^call/)
+      end
+
+      def matching_views_in_source_location
+        return [] unless source_location
+
+        location_without_extension = source_location.chomp(File.extname(source_location))
+
+        extenstions = ActionView::Template.template_handler_extensions.join(",")
+
+        # view files in the same directory as te component
+        sidecar_files = Dir["#{location_without_extension}.*{#{extenstions}}"]
+
+        # view files in a directory named like the component
+        directory = File.dirname(source_location)
+        filename = File.basename(source_location, ".rb")
+        component_name = name.demodulize.underscore
+
+        sidecar_directory_files = Dir["#{directory}/#{component_name}/#{filename}.*{#{extenstions}}"]
+
+        (sidecar_files - [source_location] + sidecar_directory_files)
+      end
+
+      def templates
+        @templates ||=
+          matching_views_in_source_location.each_with_object([]) do |path, memo|
+            pieces = File.basename(path).split(".")
+
+            memo << {
+              path: path,
+              variant: pieces.second.split("+").second&.to_sym,
+              handler: pieces.last
+            }
+          end
+      end
+
+      def template_errors
+        @template_errors ||=
+          begin
+            errors = []
+
+            if (templates + inline_calls).empty?
+              errors << "Could not find a template file or inline render method for #{self}."
+            end
+
+            if templates.count { |template| template[:variant].nil? } > 1
+              errors << "More than one template found for #{self}. There can only be one default template file per component."
+            end
+
+            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 #{self}. 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 #{self}. There can only be a template file or inline render method per component."
+            end
+
+            duplicate_template_file_and_inline_variant_calls =
+              templates.pluck(:variant) & variants_from_inline_calls(inline_calls_defined_on_self)
+
+            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 #{self}. There can only be a template file or inline render method per variant."
+            end
+
+            errors
+          end
+      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
+    end
+
+    ActiveSupport.run_load_hooks(:view_component, self)
+  end
+end