actionview-component 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30f9a7b6c2e7f0549743bf979ce3db726539f9c1f9391cb4f2f34e6d955b8689
-  data.tar.gz: 6db7efd3c77edbdacfa376d78729c8092848fc48176378a0677b50e6cd110433
+  metadata.gz: 0552c91192357398456b81be3efd02cfa663581acf91a07ff0cebff2b8f55a62
+  data.tar.gz: f945914f027bc27c0ee5397bad3a4d7ea0c1882c95500d7de67076d96f8159de
 SHA512:
-  metadata.gz: bd86da9ed9d6be7b8397711cde1da635d657630b1864da03e297e87596395476d84bbafb4c84447b4518207ead5cbe2f905b6b7fc95f10b96cfe0b2bd5e9fcc5
-  data.tar.gz: d42213b009dfbd75489be053daab29fa0c74614f8657d308a08254c72ba31327933d0683d5c4ad6df43d1cdf63b86236ef3cda9e6b23b9b883ba987c1692b719
+  metadata.gz: 24b6e98091a0af3b3f2a0db50310d5ab6c60a59cc4bba80fdee57a6e6d34bd8535a99c9ec6183032426fdb2ddd7d41743eb9356d0552f371ca127885d906249a
+  data.tar.gz: aff611c2259676d8d6690e897983180c23da45b231853e0be8de61d2c0b4d2bb08340e46fa03274d2bee12366d2098721b6259205de0b4f2377365b0c37a7373

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# v1.5.0
+
+Note: `actionview-component` is now loaded by requiring `actionview/component`, not `actionview/component/base`.
+
+* Fix issue with generating component method signatures.
+
+    *Ryan Workman, Dylan Clark*
+
+* Create component generator.
+
+    *Vinicius Stock*
+
+* Add helpers proxy.
+
+    *Kasper Meyer*
+
+* Introduce ActionView::Component::Previews.
+
+    *Juan Manuel Ramallo*
+
 # v1.4.0
 
 * Fix bug where components broke in application paths with periods.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    actionview-component (1.4.0)
+    actionview-component (1.5.0)
 
 GEM
   remote: https://rubygems.org/
@@ -64,7 +64,7 @@ GEM
     ast (2.4.0)
     builder (3.2.3)
     concurrent-ruby (1.1.5)
-    crass (1.0.4)
+    crass (1.0.5)
     erubi (1.8.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
@@ -74,7 +74,7 @@ GEM
     i18n (1.6.0)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.3)
-    loofah (2.2.3)
+    loofah (2.3.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
@@ -87,7 +87,7 @@ GEM
     mini_portile2 (2.4.0)
     minitest (5.1.0)
     nio4r (2.5.2)
-    nokogiri (1.10.4)
+    nokogiri (1.10.5)
       mini_portile2 (~> 2.4.0)
     parallel (1.17.0)
     parser (2.6.3.0)

data/README.md

@@ -32,7 +32,7 @@ $ bundle
 In `config/application.rb`, add:
 
 ```bash
-require "action_view/component/base"
+require "action_view/component"
 ```
 
 ## Guide
@@ -97,10 +97,26 @@ Components are subclasses of `ActionView::Component::Base` and live in `app/comp
 
 Component class names end in -`Component`.
 
+Component module names are plural, as they are for controllers. (`Users::AvatarComponent`)
+
 Components support ActiveModel validations. Components are validated after initialization, but before rendering.
 
 Content passed to an `ActionView::Component` as a block is captured and assigned to the `content` accessor.
 
+#### Quick start
+
+Use the component generator to create a new `ActionView::Component`.
+
+The generator accepts the component name and the list of accepted properties as arguments:
+
+```bash
+bin/rails generate component Example title content
+      invoke  test_unit
+      create  test/components/example_component_test.rb
+      create  app/components/example_component.rb
+      create  app/components/example_component.html.erb
+```
+
 #### Implementation
 
 An `ActionView::Component` is a Ruby file and corresponding template file (in any format supported by Rails) with the same base name:
@@ -201,6 +217,49 @@ def test_render_component_for_tablet
 end
 ```
 
+### Previewing Components
+`ActionView::Component::Preview`s provide a way to see how components look by visiting a special URL that renders them.
+In the previous example, the preview class for `TestComponent` would be called `TestComponentPreview` and located in `test/components/previews/test_component_preview.rb`.
+To see the preview of the component with a given title, implement a method that renders the component.
+You can define as many examples as you want:
+
+```ruby
+# test/components/previews/test_component_preview.rb
+
+class TestComponentPreview < ActionView::Component::Preview
+  def with_default_title
+    render(TestComponent, title: "Test component default")
+  end
+
+  def with_long_title
+    render(TestComponent, title: "This is a really long title to see how the component renders this")
+  end
+end
+```
+
+The previews will be available in <http://localhost:3000/rails/components/test_component/with_default_title>
+and <http://localhost:3000/rails/components/test_component/with_long_title>.
+
+Previews use the application layout by default, but you can also use other layouts from your app:
+
+```ruby
+# test/components/previews/test_component_preview.rb
+
+class TestComponentPreview < ActionView::Component::Preview
+  layout "admin"
+
+  ...
+end
+```
+
+By default, the preview classes live in `test/components/previews`.
+This can be configured using the `preview_path` option.
+For example, if you want to use `lib/component_previews`, set the following in `config/application.rb`:
+
+```ruby
+config.action_view_component.preview_path = "#{Rails.root}/lib/component_previews"
+```
+
 ## Frequently Asked Questions
 
 ### Can I use other templating languages besides ERB?

data/lib/action_view/component.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "action_view/component/monkey_patch"
+require "action_view/component/base"
+require "action_view/component/railtie"

data/lib/action_view/component/base.rb

@@ -1,37 +1,18 @@
 # frozen_string_literal: true
 
-# Monkey patch ActionView::Base#render to support ActionView::Component
-#
-# A version of this monkey patch was upstreamed in https://github.com/rails/rails/pull/36388
-# We'll need to upstream an updated version of this eventually.
-class ActionView::Base
-  module RenderMonkeyPatch
-    def render(options = {}, args = {}, &block)
-      if options.respond_to?(:render_in)
-        ActiveSupport::Deprecation.warn(
-          "passing component instances (`render MyComponent.new(foo: :bar)`) has been deprecated and will be removed in v2.0.0. Use `render MyComponent, foo: :bar` instead."
-        )
-
-        options.render_in(self, &block)
-      elsif options.is_a?(Class) && options < ActionView::Component::Base
-        options.new(args).render_in(self, &block)
-      elsif options.is_a?(Hash) && options.has_key?(:component)
-        options[:component].new(options[:locals]).render_in(self, &block)
-      else
-        super
-      end
-    end
-  end
-
-  prepend RenderMonkeyPatch
-end
+require "active_model"
+require "action_view"
+require "active_support/configurable"
+require_relative "preview"
 
 module ActionView
   module Component
     class Base < ActionView::Base
       include ActiveModel::Validations
       include ActiveSupport::Configurable
-      include ActionController::RequestForgeryProtection
+      include ActionView::Component::Previews
+
+      delegate :form_authenticity_token, :protect_against_forgery?, to: :helpers
 
       validate :variant_exists
 
@@ -93,10 +74,14 @@ module ActionView
         @controller ||= view_context.controller
       end
 
-      # Looks for the source file path of the initialize method of the instance's class.
+      # Provides a proxy to access helper methods through
+      def helpers
+        @helpers ||= view_context
+      end
+
       # Removes the first part of the path and the extension.
       def virtual_path
-        self.class.source_location.gsub(%r{(.*app/)|(\.rb)}, "")
+        self.class.source_location.gsub(%r{(.*app/components)|(\.rb)}, "")
       end
 
       def view_cache_dependencies
@@ -173,6 +158,15 @@ module ActionView
           templates.map { |template| template[:variant] }
         end
 
+        # we'll eventually want to update this to support other types
+        def type
+          "text/html"
+        end
+
+        def identifier
+          ""
+        end
+
         private
 
         def templates
@@ -206,31 +200,15 @@ module ActionView
           handler = ActionView::Template.handler_for_extension(File.extname(file_path).gsub(".", ""))
           template = File.read(file_path)
 
-          # This can be removed once this code is merged into Rails
           if handler.method(:call).parameters.length > 1
-            handler.call(DummyTemplate.new, template)
-          else
-            handler.call(DummyTemplate.new(template))
+            handler.call(self, template)
+          else # remove before upstreaming into Rails
+            handler.call(OpenStruct.new(source: template, identifier: identifier, type: type))
           end
         end
       end
 
-      class DummyTemplate
-        attr_reader :source
-
-        def initialize(source = nil)
-          @source = source
-        end
-
-        def identifier
-          ""
-        end
-
-        # we'll eventually want to update this to support other types
-        def type
-          "text/html"
-        end
-      end
+      ActiveSupport.run_load_hooks(:action_view_component, self)
     end
   end
 end

data/lib/action_view/component/monkey_patch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Monkey patch ActionView::Base#render to support ActionView::Component
+#
+# A version of this monkey patch was upstreamed in https://github.com/rails/rails/pull/36388
+# We'll need to upstream an updated version of this eventually.
+class ActionView::Base
+  module RenderMonkeyPatch
+    def render(options = {}, args = {}, &block)
+      if options.respond_to?(:render_in)
+        ActiveSupport::Deprecation.warn(
+          "passing component instances (`render MyComponent.new(foo: :bar)`) has been deprecated and will be removed in v2.0.0. Use `render MyComponent, foo: :bar` instead."
+        )
+
+        options.render_in(self, &block)
+      elsif options.is_a?(Class) && options < ActionView::Component::Base
+        options.new(args).render_in(self, &block)
+      elsif options.is_a?(Hash) && options.has_key?(:component)
+        options[:component].new(options[:locals]).render_in(self, &block)
+      else
+        super
+      end
+    end
+  end
+
+  prepend RenderMonkeyPatch
+end

data/lib/action_view/component/preview.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/descendants_tracker"
+require_relative "test_helpers"
+
+module ActionView
+  module Component #:nodoc:
+    module Previews
+      extend ActiveSupport::Concern
+
+      included do
+        # Set the location of component previews through app configuration:
+        #
+        #     config.action_view_component.preview_path = "#{Rails.root}/lib/component_previews"
+        #
+        mattr_accessor :preview_path, instance_writer: false
+
+        # Enable or disable component previews through app configuration:
+        #
+        #     config.action_view_component.show_previews = true
+        #
+        # Defaults to +true+ for development environment
+        #
+        mattr_accessor :show_previews, instance_writer: false
+      end
+    end
+
+    class Preview
+      extend ActiveSupport::DescendantsTracker
+      include ActionView::Component::TestHelpers
+
+      def render(component, *locals)
+        render_inline(component, *locals)
+      end
+
+      class << self
+        # Returns all component preview classes.
+        def all
+          load_previews if descendants.empty?
+          descendants
+        end
+
+        # Returns the html of the component in its layout
+        def call(example)
+          example_html = new.public_send(example)
+
+          Rails::ComponentExamplesController.render(template: "examples/show",
+                                                    layout: @layout || "layouts/application",
+                                                    assigns: { example: example_html })
+        end
+
+        # Returns the component object class associated to the preview.
+        def component
+          self.name.sub(%r{Preview$}, "").constantize
+        end
+
+        # Returns all of the available examples for the component preview.
+        def examples
+          public_instance_methods(false).map(&:to_s).sort
+        end
+
+        # Returns +true+ if the example of the component preview exists.
+        def example_exists?(example)
+          examples.include?(example)
+        end
+
+        # Returns +true+ if the preview exists.
+        def exists?(preview)
+          all.any? { |p| p.preview_name == preview }
+        end
+
+        # Find a component preview by its underscored class name.
+        def find(preview)
+          all.find { |p| p.preview_name == preview }
+        end
+
+        # Returns the underscored name of the component preview without the suffix.
+        def preview_name
+          name.sub(/Preview$/, "").underscore
+        end
+
+        # Setter for layout name.
+        def layout(layout_name)
+          @layout = layout_name
+        end
+
+        private
+
+        def load_previews
+          if preview_path
+            Dir["#{preview_path}/**/*_preview.rb"].sort.each { |file| require_dependency file }
+          end
+        end
+
+        def preview_path
+          Base.preview_path
+        end
+
+        def show_previews
+          Base.show_previews
+        end
+      end
+    end
+  end
+end

data/lib/action_view/component/railtie.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "railties/lib/rails/components_controller"
+require "railties/lib/rails/component_examples_controller"
+
+module ActionView
+  module Component
+    class Railtie < Rails::Railtie # :nodoc:
+      config.action_view_component = ActiveSupport::OrderedOptions.new
+
+      # Disabled due to issues with ActionView::Component::Base not defining .logger
+      # initializer "action_view_component.logger" do
+      #   ActiveSupport.on_load(:action_view_component) { self.logger ||= Rails.logger }
+      # end
+
+      initializer "action_view_component.set_configs" do |app|
+        options = app.config.action_view_component
+
+        options.show_previews = Rails.env.development? if options.show_previews.nil?
+
+        if options.show_previews
+          options.preview_path ||= defined?(Rails.root) ? "#{Rails.root}/test/components/previews" : nil
+        end
+
+        ActiveSupport.on_load(:action_view_component) do
+          options.each { |k, v| send("#{k}=", v) }
+        end
+      end
+
+      initializer "action_view_component.compile_config_methods" do
+        ActiveSupport.on_load(:action_view_component) do
+          config.compile_methods! if config.respond_to?(:compile_methods!)
+        end
+      end
+
+      initializer "action_view_component.eager_load_actions" do
+        ActiveSupport.on_load(:after_initialize) do
+          ActionView::Component::Base.descendants.each(&:action_methods) if config.eager_load
+        end
+      end
+
+      config.after_initialize do |app|
+        options = app.config.action_view_component
+
+        if options.show_previews
+          app.routes.prepend do
+            get "/rails/components" => "rails/components#index", :internal => true
+            get "/rails/components/*path" => "rails/components#previews", :internal => true
+          end
+
+          if options.preview_path
+            ActiveSupport::Dependencies.autoload_paths << options.preview_path
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_view/component/version.rb

@@ -4,7 +4,7 @@ module ActionView
   module Component
     module VERSION
       MAJOR = 1
-      MINOR = 4
+      MINOR = 5
       PATCH = 0
 
       STRING = [MAJOR, MINOR, PATCH].join(".")

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,50 @@
+# 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"
+      hook_for :test_framework
+      check_class_collision suffix: "Component"
+
+      def create_component_file
+        template "component.rb", File.join("app/components",  "#{file_name}_component.rb")
+      end
+
+      def create_template_file
+        template "component.html.erb", File.join("app/components",  "#{file_name}_component.html.erb")
+      end
+
+      private
+
+      def file_name
+        @_file_name ||= super.sub(/_component\z/i, "")
+      end
+
+      def requires_content?
+        return @requires_content if @asked
+
+        @asked = true
+        @requires_content = ask("Would you like #{class_name} to require content? (Y/n)").downcase == "y"
+      end
+
+      def parent_class
+        defined?(ApplicationComponent) ? "ApplicationComponent" : "ActionView::Component::Base"
+      end
+
+      def initialize_signature
+        if attributes.present?
+          attributes.map { |attr| "#{attr.name}:" }.join(", ")
+        else
+          "*"
+        end
+      end
+
+      def initialize_body
+        attributes.map { |attr| "@#{attr.name} = #{attr.name}" }.join("\n    ")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+<%- if requires_content? -%>
+<%= "<%= content %%>" %>
+<%- else -%>
+<div>Add <%= class_name %> template here</div>
+<%- end -%>

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

@@ -0,0 +1,9 @@
+class <%= class_name %>Component < <%= parent_class %>
+  <%- if requires_content? -%>
+  validates :content, presence: true
+  <%- end -%>
+
+  def initialize(<%= initialize_signature %>)
+    <%= initialize_body %>
+  end
+end

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", "#{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,12 @@
+require "test_helper"
+
+class <%= class_name %>ComponentTest < ActiveSupport::TestCase
+  include ActionView::Component::TestHelpers
+
+  test "component renders something useful" do
+    # assert_equal(
+    #   %(<span title="my title">Hello, components!</span>),
+    #   render_inline(<%= class_name %>, attr: "value") { "Hello, components!" }.css("span").to_html
+    # )
+  end
+end

data/lib/railties/lib/rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Rails
+  autoload :ComponentsController
+  autoload :ComponentExamplesController
+end

data/lib/railties/lib/rails/component_examples_controller.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rails/application_controller"
+load "config/application.rb" unless Rails.root
+
+class Rails::ComponentExamplesController < ActionController::Base # :nodoc:
+  prepend_view_path File.expand_path("templates/rails", __dir__)
+  append_view_path Rails.root.join("app/views")
+end

data/lib/railties/lib/rails/components_controller.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/application_controller"
+
+class Rails::ComponentsController < Rails::ApplicationController # :nodoc:
+  prepend_view_path File.expand_path("templates/rails", __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 = ActionView::Component::Preview.all
+    @page_title = "Component Previews"
+    render template: "components/index"
+  end
+
+  def previews
+    if params[:path] == @preview.preview_name
+      @page_title = "Component Previews for #{@preview.preview_name}"
+      render template: "components/previews"
+    else
+      @example_name = File.basename(params[:path])
+      render template: "components/preview", layout: false
+    end
+  end
+
+  private
+
+  def show_previews? # :doc:
+    ActionView::Component::Base.show_previews
+  end
+
+  def find_preview # :doc:
+    candidates = []
+    params[:path].to_s.scan(%r{/|$}) { candidates << $` }
+    preview = candidates.detect { |candidate| ActionView::Component::Preview.exists?(candidate) }
+
+    if preview
+      @preview = ActionView::Component::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
+end

data/lib/railties/lib/rails/templates/rails/components/index.html.erb

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

data/lib/railties/lib/rails/templates/rails/components/preview.html.erb

@@ -0,0 +1 @@
+<%= raw @preview.call(@example_name) %>

data/lib/railties/lib/rails/templates/rails/components/previews.html.erb

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

data/lib/railties/lib/rails/templates/rails/examples/show.html.erb

@@ -0,0 +1 @@
+<%= raw @example %>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actionview-component
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - GitHub Open Source
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-07 00:00:00.000000000 Z
+date: 2019-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -127,9 +127,26 @@ files:
 - README.md
 - Rakefile
 - actionview-component.gemspec
+- lib/action_view/component.rb
 - lib/action_view/component/base.rb
+- lib/action_view/component/monkey_patch.rb
+- lib/action_view/component/preview.rb
+- lib/action_view/component/railtie.rb
 - lib/action_view/component/test_helpers.rb
 - lib/action_view/component/version.rb
+- lib/rails/generators/component/USAGE
+- lib/rails/generators/component/component_generator.rb
+- lib/rails/generators/component/templates/component.html.erb.tt
+- lib/rails/generators/component/templates/component.rb.tt
+- lib/rails/generators/test_unit/component_generator.rb
+- lib/rails/generators/test_unit/templates/component_test.rb.tt
+- lib/railties/lib/rails.rb
+- lib/railties/lib/rails/component_examples_controller.rb
+- lib/railties/lib/rails/components_controller.rb
+- lib/railties/lib/rails/templates/rails/components/index.html.erb
+- lib/railties/lib/rails/templates/rails/components/preview.html.erb
+- lib/railties/lib/rails/templates/rails/components/previews.html.erb
+- lib/railties/lib/rails/templates/rails/examples/show.html.erb
 - script/bootstrap
 - script/console
 - script/install