view_component 2.5.1 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38eb3604bfed89ac05aad6501271fe16c0045db486737fe1b6306ac002339b90
-  data.tar.gz: 5bd3f94e4f333667a9a534ff3171650a285df654bb45ae7e66a8f8441cfa5d9c
+  metadata.gz: 8bc0f4ab66dfca6a89f9882d0df39f5f4a84f479f26dfd0b3334b43fe4f9b4ed
+  data.tar.gz: 39128211a1338af6c78a54085b59f48a98411dc282e6248f03fc56229a6d7cd0
 SHA512:
-  metadata.gz: df1664a8bb11ccbb88dabb3605039ba15d57308219068341f00d5a85ec189d3dda57b0d6185c9f86526b99646a79e5b1e216e35d49b75439b9a3ea5f4df1ac59
-  data.tar.gz: 77ca17df33fadfafd7a38acfae6add65a2b2096f6dcc307717f899b2ff8f4e3d7532d68e7ee87b0d6addd8f4aeb47ef5b408e27a15d081c91ef39a5402890098
+  metadata.gz: 1aa9fb3d7361efa6a98465c1513e3296abc4495ad30393ed9fbf3febc919a8669184fe2e28fe5afa9666a42b71958787b2bf091b71d4e9889b020d0495769abf
+  data.tar.gz: 2ce5ece866ddc50d8aa01cd139c230c10b26aee9d8bbc49f7421b8d191e5b84dbd57d1247b9973f936932dcde9bd925f96c2d3114ac201d98511157b7643bac0

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # master
 
+# 2.6.0
+
+* Add `config.view_component.preview_route` to set the endpoint for component previews. By default `/rails/view_components` is used.
+
+    *Juan Manuel Ramallo*
+
+* Raise error when initializer omits with_collection_parameter.
+
+    *Joel Hawksley*
+
 # 2.5.1
 
 * Compile component before rendering collection.

data/README.md

@@ -1,30 +1,13 @@
 # ViewComponent
-A view component framework for Rails.
-
-**Current Status**: Used in production at GitHub. Because of this, all changes will be thoroughly vetted, which could slow down the process of contributing. We will do our best to actively communicate status of pull requests with any contributors. If you have any substantial changes that you would like to make, it would be great to first [open an issue](http://github.com/github/view_component/issues/new) to discuss them with us.
-
-## Migration from ActionView::Component
-
-This gem used to be called `ActionView::Component`.
-See [issue #206] for some background on the name change.
-Learn more about what changed and how to migrate [here][migration-info].
-
-[issue #206]: https://github.com/github/view_component/issues/206
-[migration-info]: https://github.com/github/view_component/blob/v2.0.0/README.md#migration-in-progress
-
-## Roadmap
-
-Support for third-party component frameworks was merged into Rails `6.1.0.alpha` in https://github.com/rails/rails/pull/36388 and https://github.com/rails/rails/pull/37919. Our goal with this project is to provide a first-class component framework for this new capability in Rails.
-
-This gem includes a backport of those changes for Rails `5.0.0` through `6.1.0.alpha`.
+ViewComponent is a framework for building view components that are reusable, testable & encapsulated, in Ruby on Rails.
 
 ## Design philosophy
-
-This library is designed to integrate as seamlessly as possible with Rails, with the [least surprise](https://www.artima.com/intv/ruby4.html).
+ViewComponent is designed to integrate as seamlessly as possible [with Rails](https://rubyonrails.org/doctrine/), with the [least surprise](https://www.artima.com/intv/ruby4.html).
 
 ## Compatibility
+ViewComponent is [supported natively](https://edgeguides.rubyonrails.org/layouts_and_rendering.html#rendering-objects) in Rails 6.1, and compatible with Rails 5.0+ via an included [monkey patch](https://github.com/github/view_component/blob/master/lib/view_component/render_monkey_patch.rb).
 
-`view_component` is tested for compatibility with combinations of Ruby `2.4`/`2.5`/`2.6`/`2.7` and Rails `5.0.0`/`5.2.3`/`6.0.0`/`master`.
+ViewComponent is tested for compatibility [with combinations of](https://github.com/github/view_component/blob/22e3d4ccce70d8f32c7375e5a5ccc3f70b22a703/.github/workflows/ruby_on_rails.yml#L10-L11) Ruby 2.4+ and Rails 5+.
 
 ## Installation
 
@@ -44,7 +27,7 @@ require "view_component/engine"
 
 ### What are components?
 
-`ViewComponent`s are Ruby classes that are used to render views. They take data as input and return output-safe HTML. Think of them as an evolution of the presenter/decorator/view model pattern, inspired by [React Components](https://reactjs.org/docs/react-component.html).
+ViewComponents are Ruby objects that output HTML. Think of them as an evolution of the presenter pattern, inspired by [React](https://reactjs.org/docs/react-component.html).
 
 Components are most effective in cases where view code is reused or benefits from being tested directly.
 
@@ -52,47 +35,39 @@ Components are most effective in cases where view code is reused or benefits fro
 
 #### Testing
 
-Rails encourages testing views with integration tests. This discourages us from testing views thoroughly, due to the overhead of exercising the routing and controller layers in addition to the view.
+Unlike traditional Rails views, ViewComponents can be unit-tested. In the GitHub codebase, component unit tests take around 25 milliseconds each, compared to about six seconds for controller tests.
 
-For partials, this means being tested for each view they are included in, reducing the benefit of reusing them.
+Rails views are typically tested with slow integration tests that also exercise the routing and controller layers in addition to the view. This cost often discourages thorough test coverage.
 
-`ViewComponent`s can be unit-tested. In the GitHub codebase, our component unit tests run in around 25 milliseconds, compared to about six seconds for integration tests.
+With ViewComponent, integration tests can be reserved for end-to-end assertions, with permutations and corner cases covered at the unit level.
 
 #### Data Flow
 
-Unlike a method declaration on an object, views do not declare the values they are expected to receive, making it hard to figure out what context is necessary to render them. This often leads to subtle bugs when reusing a view in different contexts.
+Traditional Rails views have an implicit interface, making it hard to reason about what information is needed to render, leading to subtle bugs when rendering the same view in different contexts.
 
-By clearly defining the context necessary to render a `ViewComponent`, they're easier to reuse than partials.
+ViewComponents use a standard Ruby initializer that clearly defines what is needed to render, making them easier (and safer) to reuse than partials.
 
 #### Standards
 
 Views often fail basic Ruby code quality standards: long methods, deep conditional nesting, and mystery guests abound.
 
-`ViewComponent`s are Ruby objects, making it easy to follow code quality standards.
-
-#### Code Coverage
-
-Many common Ruby code coverage tools cannot properly handle coverage of views, making it difficult to audit how thorough tests are and leading to missing coverage in test suites.
-
-`ViewComponent` is at least partially compatible with code coverage tools, such as SimpleCov.
+ViewComponents are Ruby objects, making it easy to follow (and enforce) code quality standards.
 
 ### Building components
 
 #### Conventions
 
-Components are subclasses of `ViewComponent::Base` and live in `app/components`. It's recommended to create an `ApplicationComponent` that is a subclass of `ViewComponent::Base` and inherit from that instead.
-
-Component class names end in -`Component`.
+Components are subclasses of `ViewComponent::Base` and live in `app/components`. It's common practice to create and inherit from an `ApplicationComponent` that is a subclass of `ViewComponent::Base`.
 
-Component module names are plural, as they are for controllers. (`Users::AvatarComponent`)
+Component names end in -`Component`.
 
-Content passed to a `ViewComponent` as a block is captured and assigned to the `content` accessor.
+Component module names are plural, as for controllers and jobs: `Users::AvatarComponent`
 
 #### Quick start
 
-Use the component generator to create a new `ViewComponent`.
+Use the component generator to create a new ViewComponent.
 
-The generator accepts the component name and the list of accepted properties as arguments:
+The generator accepts a component name and a list of arguments:
 
 ```bash
 bin/rails generate component Example title content
@@ -102,7 +77,7 @@ bin/rails generate component Example title content
       create  app/components/example_component.html.erb
 ```
 
-`ViewComponent` includes template generators for the `erb`, `haml`, and `slim` template engines and will use the template engine specified in the Rails configuration (`config.generators.template_engine`) by default.
+ViewComponent includes template generators for the `erb`, `haml`, and `slim` template engines and will default to the template engine specified in `config.generators.template_engine`.
 
 The template engine can also be passed as an option to the generator:
 
@@ -112,7 +87,7 @@ bin/rails generate component Example title content --template-engine slim
 
 #### Implementation
 
-A `ViewComponent` is a Ruby file and corresponding template file with the same base name:
+A ViewComponent is a Ruby file and corresponding template file with the same base name:
 
 `app/components/test_component.rb`:
 ```ruby
@@ -128,7 +103,7 @@ end
 <span title="<%= @title %>"><%= content %></span>
 ```
 
-Which is rendered in a view as:
+Rendered in a view as:
 
 ```erb
 <%= render(TestComponent.new(title: "my title")) do %>
@@ -136,7 +111,7 @@ Which is rendered in a view as:
 <% end %>
 ```
 
-Which returns:
+Returning:
 
 ```html
 <span title="my title">Hello, World!</span>
@@ -144,7 +119,9 @@ Which returns:
 
 #### Content Areas
 
-A component can declare additional content areas to be rendered in the component. For example:
+Content passed to a ViewComponent as a block is captured and assigned to the `content` accessor.
+
+ViewComponents can declare additional content areas. For example:
 
 `app/components/modal_component.rb`:
 ```ruby
@@ -161,7 +138,7 @@ end
 </div>
 ```
 
-Which is rendered in a view as:
+Rendered in a view as:
 
 ```erb
 <%= render(ModalComponent.new) do |component| %>
@@ -174,7 +151,7 @@ Which is rendered in a view as:
 <% end %>
 ```
 
-Which returns:
+Returning:
 
 ```html
 <div class="modal">
@@ -185,10 +162,9 @@ Which returns:
 
 ### Inline Component
 
-A component can be rendered without any template file as well.
+ViewComponents can render without a template file, by defining a `call` method:
 
 `app/components/inline_component.rb`:
-
 ```ruby
 class InlineComponent < ViewComponent::Base
   def call
@@ -201,34 +177,30 @@ class InlineComponent < ViewComponent::Base
 end
 ```
 
-It is also possible to render variants inline by creating additional `call_` methods.
+It is also possible to define methods for variants:
 
 ```ruby
 class InlineVariantComponent < ViewComponent::Base
-  def call
-    link_to "Default", default_path
-  end
-
   def call_phone
     link_to "Phone", phone_path
   end
+
+  def call
+    link_to "Default", default_path
+  end
 end
 ```
 
-Using a mixture of templates and inline render methods in a component is supported, however only one should be provided per component (or variant).
-
 ### Conditional Rendering
 
-Components can implement a `#render?` method to determine if they should be rendered.
+Components can implement a `#render?` method to be called after initialization to determine if the component should render.
 
-For example, given a component that displays a banner to users who haven't confirmed their email address, the logic for whether to render the banner would need to go in either the component template:
+Traditionally, the logic for whether to render a view could go in either the component template:
 
 `app/components/confirm_email_component.html.erb`
 ```
 <% if user.requires_confirmation? %>
-  <div class="alert">
-    Please confirm your email address.
-  </div>
+  <div class="alert">Please confirm your email address.</div>
 <% end %>
 ```
 
@@ -241,7 +213,7 @@ or the view that renders the component:
 <% end %>
 ```
 
-Instead, the `#render?` hook expresses this logic in the Ruby class, simplifying the view:
+Using the `#render?` hook simplifies the view:
 
 `app/components/confirm_email_component.rb`
 ```ruby
@@ -268,19 +240,17 @@ end
 <%= render(ConfirmEmailComponent.new(user: current_user)) %>
 ```
 
-To assert that a component has not been rendered, use `refute_component_rendered` from `ViewComponent::TestHelpers`.
+_To assert that a component has not been rendered, use `refute_component_rendered` from `ViewComponent::TestHelpers`._
 
 ### Rendering collections
 
-It's possible to render collections with components:
+Use `with_collection` to render a ViewComponent with a collection:
 
 `app/view/products/index.html.erb`
 ``` erb
 <%= render(ProductComponent.with_collection(@products)) %>
 ```
 
-Where the `ProductComponent` and associated template might look something like the following. Notice that the constructor must take a `product` and the name of that parameter matches the name of the component.
-
 `app/components/product_component.rb`
 ``` ruby
 class ProductComponent < ViewComponent::Base
@@ -290,12 +260,26 @@ class ProductComponent < ViewComponent::Base
 end
 ```
 
-`app/components/product_component.html.erb`
-``` erb
-<li><%= @product.name %></li>
+[By default](https://github.com/github/view_component/blob/89f8fab4609c1ef2467cf434d283864b3c754473/lib/view_component/base.rb#L249), the component name is used to define the parameter passed into the component from the collection.
+
+#### `with_collection_parameter`
+
+Use `with_collection_parameter` to change the name of the collection parameter:
+
+`app/components/product_component.rb`
+``` ruby
+class ProductComponent < ViewComponent::Base
+  with_collection_parameter :item
+
+  def initialize(item:)
+    @item = item
+  end
+end
 ```
 
-Additionally, extra arguments can be passed to the component and the name of the parameter can be changed:
+#### Additional arguments
+
+Additional arguments besides the collection are passed to each component instance:
 
 `app/view/products/index.html.erb`
 ``` erb
@@ -322,7 +306,9 @@ end
 </li>
 ```
 
-`ViewComponent` defines a counter variable matching the parameter name above, followed by `_counter`. To access this variable, add it to `initialize` as an argument:
+#### Collection counter
+
+ViewComponent defines a counter variable matching the parameter name above, followed by `_counter`. To access the variable, add it to `initialize` as an argument:
 
 `app/components/product_component.rb`
 ``` ruby
@@ -341,140 +327,53 @@ end
 </li>
 ```
 
-### Sidecar assets (experimental)
-
-We're experimenting with including Javascript and CSS alongside components, sometimes called "sidecar" assets or files.
-
-To use the Webpacker gem to compile sidecar assets located in `app/components`:
-
-1. 1. In `config/webpacker.yml`, add `"app/components"` to the `resolved_paths` array (e.g. `resolved_paths: ["app/components"]`).
-2. In the Webpack entry file (often `app/javascript/packs/application.js`), add an import statement to a helper file, and in the helper file, import the components' Javascript:
-
-Near the top the entry file, add:
-
-```js
-import "../components"
-```
-
-Then add the following to a new file `app/javascript/components.js`:
-
-```js
-function importAll(r) {
-  r.keys().forEach(r)
-}
-
-importAll(require.context("../components", true, /_component.js$/))
-```
-
-Any file with the `_component.js` suffix, for example `app/components/widget_component.js`, will get compiled into the Webpack bundle. If that file itself imports another file, for example `app/components/widget_component.css`, that will also get compiled and bundled into Webpack's output stylesheet if Webpack is being used for styles.
-
-#### Encapsulating sidecar assets
-
-Ideally, sidecar Javascript/CSS should not "leak" out of the context of its associated component.
-
-One approach is to use Web Components, which contain all Javascript functionality, internal markup, and styles within the shadow root of the Web Component.
+### Using helpers
 
-For example:
+Helper methods can be used through the `helpers` proxy:
 
-`app/components/comment_component.rb`
 ```ruby
-class CommentComponent < ViewComponent::Base
-  def initialize(comment:)
-    @comment = comment
-  end
-
-  def commenter
-    @comment.user
-  end
-
-  def commenter_name
-    commenter.name
-  end
-
-  def avatar
-    commenter.avatar_image_url
+module IconHelper
+  def icon(name)
+    tag.i data: { feather: name.to_s.dasherize }
   end
+end
 
-  def formatted_body
-    simple_format(@comment.body)
+class UserComponent < ViewComponent::Base
+  def profile_icon
+    helpers.icon :user
   end
-
-  private
-
-  attr_reader :comment
 end
 ```
 
-`app/components/comment_component.html.erb`
-```erb
-<my-comment comment-id="<%= comment.id %>">
-  <time slot="posted" datetime="<%= comment.created_at.iso8601 %>"><%= comment.created_at.strftime("%b %-d") %></time>
-
-  <div slot="avatar"><img src="<%= avatar %>" /></div>
-
-  <div slot="author"><%= commenter_name %></div>
-
-  <div slot="body"><%= formatted_body %></div>
-</my-comment>
-```
+Which can be used with `delegate`:
 
-`app/components/comment_component.js`
-```js
-class Comment extends HTMLElement {
-  styles() {
-    return `
-      :host {
-        display: block;
-      }
-      ::slotted(time) {
-        float: right;
-        font-size: 0.75em;
-      }
-      .commenter { font-weight: bold; }
-      .body { … }
-    `
-  }
+```ruby
+class UserComponent < ViewComponent::Base
+  delegate :icon, to: :helpers
 
-  constructor() {
-    super()
-    const shadow = this.attachShadow({mode: 'open'});
-    shadow.innerHTML = `
-      <style>
-        ${this.styles()}
-      </style>
-      <slot name="posted"></slot>
-      <div class="commenter">
-        <slot name="avatar"></slot> <slot name="author"></slot>
-      </div>
-      <div class="body">
-        <slot name="body"></slot>
-      </div>
-    `
-  }
-}
-customElements.define('my-comment', Comment)
+  def profile_icon
+    icon :user
+  end
+end
 ```
 
-##### Stimulus
+Helpers can also be used by including the helper:
 
-In Stimulus, create a 1:1 mapping between a Stimulus controller and a component. In order to load in Stimulus controllers from the `app/components` tree, amend the Stimulus boot code in `app/javascript/packs/application.js`:
+```ruby
+class UserComponent < ViewComponent::Base
+  include IconHelper
 
-```js
-const application = Application.start()
-const context = require.context("controllers", true, /.js$/)
-const context_components = require.context("../../components", true, /_controller.js$/)
-application.load(
-  definitionsFromContext(context).concat(
-    definitionsFromContext(context_components)
-  )
-)
+  def profile_icon
+    icon :user
+  end
+end
 ```
 
-This will allow you to create files such as `app/components/widget_controller.js`, where the controller identifier matches the `data-controller` attribute in the component's HTML template.
-
 ### Testing
 
-Unit test components directly, using the `render_inline` test helper. If you have a `capybara` test dependency, Capybara matchers will be available in your tests:
+Unit test components directly, using the `render_inline` test helper, asserting against the rendered output.
+
+Capybara matchers are available if the gem is installed:
 
 ```ruby
 require "view_component/test_case"
@@ -483,12 +382,12 @@ class MyComponentTest < ViewComponent::TestCase
   test "render component" do
     render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }
 
-    assert_selector("span[title='my title']", "Hello, World!")
+    assert_selector("span[title='my title']", text: "Hello, World!")
   end
 end
 ```
 
-In the absence of `capybara`, you can make assertions on the `render_inline` return value, which is an instance of `Nokogiri::HTML::DocumentFragment`:
+In the absence of `capybara`, assertion against the return values of `render_inline`, which is an instance of `Nokogiri::HTML::DocumentFragment`:
 
 ```ruby
 test "render component" do
@@ -507,7 +406,7 @@ test "render component for tablet" do
   with_variant :tablet do
     render_inline(TestComponent.new(title: "my title")) { "Hello, tablets!" }
 
-    assert_selector("span[title='my title']", "Hello, tablets!")
+    assert_selector("span[title='my title']", text: "Hello, tablets!")
   end
 end
 ```
@@ -551,17 +450,13 @@ class TestComponentPreview < ViewComponent::Preview
 end
 ```
 
-You'll then be able to pass down a value with <http://localhost:3000/rails/components/test_component/with_dynamic_title?title=Custom+title>.
+Which enables passing in a value with <http://localhost:3000/rails/components/test_component/with_dynamic_title?title=Custom+title>.
 
 The `ViewComponent::Preview` base class includes
-[`ActionView::Helpers::TagHelper`][tag-helper], which provides the [`tag`][tag]
-and [`content_tag`][content_tag] view helper methods.
-
-[tag-helper]: https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html
-[tag]: https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-tag
-[content_tag]: https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag
+[`ActionView::Helpers::TagHelper`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html), which provides the [`tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-tag)
+and [`content_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag) view helper methods.
 
-Previews default to the application layout, but can be overridden:
+Previews use the application layout by default, but can use a specific layout with the `layout` option:
 
 `test/components/previews/test_component_preview.rb`
 ```ruby
@@ -572,18 +467,25 @@ class TestComponentPreview < ViewComponent::Preview
 end
 ```
 
-Preview classes live in `test/components/previews`, can be configured using the `preview_path` option.
-
-To use `lib/component_previews`:
+Preview classes live in `test/components/previews`, which can be configured using the `preview_path` option:
 
 `config/application.rb`
 ```ruby
 config.view_component.preview_path = "#{Rails.root}/lib/component_previews"
 ```
 
+Previews are served from <http://localhost:3000/rails/view_components> by default. To use a different endpoint, set the `preview_route` option:
+
+`config/application.rb`
+```ruby
+config.view_component.preview_route = "/previews"
+```
+
+This example will make the previews available from <http://localhost:3000/previews>.
+
 #### Configuring TestController
 
-Component tests and previews assume the existence of an `ApplicationController` class, be can be configured using the `test_controller` option:
+Component tests and previews assume the existence of an `ApplicationController` class, which be can be configured using the `test_controller` option:
 
 `config/application.rb`
 ```ruby
@@ -612,19 +514,144 @@ To use component previews:
 config.view_component.preview_path = "#{Rails.root}/spec/components/previews"
 ```
 
-## Frequently Asked Questions
+### Sidecar assets (experimental)
 
-### Can I use other templating languages besides ERB?
+It’s possible to include Javascript and CSS alongside components, sometimes called "sidecar" assets or files.
+
+To use the Webpacker gem to compile sidecar assets located in `app/components`:
+
+1. In `config/webpacker.yml`, add `"app/components"` to the `resolved_paths` array (e.g. `resolved_paths: ["app/components"]`).
+2. In the Webpack entry file (often `app/javascript/packs/application.js`), add an import statement to a helper file, and in the helper file, import the components' Javascript:
+
+```js
+import "../components"
+```
+
+Then, in `app/javascript/components.js`, add:
+
+```js
+function importAll(r) {
+  r.keys().forEach(r)
+}
+
+importAll(require.context("../components", true, /_component.js$/))
+```
+
+Any file with the `_component.js` suffix (such as `app/components/widget_component.js`) will be compiled into the Webpack bundle. If that file itself imports another file, for example `app/components/widget_component.css`, it will also be compiled and bundled into Webpack's output stylesheet if Webpack is being used for styles.
+
+#### Encapsulating sidecar assets
+
+Ideally, sidecar Javascript/CSS should not "leak" out of the context of its associated component.
+
+One approach is to use Web Components, which contain all Javascript functionality, internal markup, and styles within the shadow root of the Web Component.
+
+For example:
+
+`app/components/comment_component.rb`
+```ruby
+class CommentComponent < ViewComponent::Base
+  def initialize(comment:)
+    @comment = comment
+  end
+
+  def commenter
+    @comment.user
+  end
+
+  def commenter_name
+    commenter.name
+  end
+
+  def avatar
+    commenter.avatar_image_url
+  end
+
+  def formatted_body
+    simple_format(@comment.body)
+  end
+
+  private
 
-Yes. This gem is tested against ERB, Haml, and Slim, but it should support most Rails template handlers.
+  attr_reader :comment
+end
+```
+
+`app/components/comment_component.html.erb`
+```erb
+<my-comment comment-id="<%= comment.id %>">
+  <time slot="posted" datetime="<%= comment.created_at.iso8601 %>"><%= comment.created_at.strftime("%b %-d") %></time>
+
+  <div slot="avatar"><img src="<%= avatar %>" /></div>
+
+  <div slot="author"><%= commenter_name %></div>
+
+  <div slot="body"><%= formatted_body %></div>
+</my-comment>
+```
+
+`app/components/comment_component.js`
+```js
+class Comment extends HTMLElement {
+  styles() {
+    return `
+      :host {
+        display: block;
+      }
+      ::slotted(time) {
+        float: right;
+        font-size: 0.75em;
+      }
+      .commenter { font-weight: bold; }
+      .body { … }
+    `
+  }
+
+  constructor() {
+    super()
+    const shadow = this.attachShadow({mode: 'open'});
+    shadow.innerHTML = `
+      <style>
+        ${this.styles()}
+      </style>
+      <slot name="posted"></slot>
+      <div class="commenter">
+        <slot name="avatar"></slot> <slot name="author"></slot>
+      </div>
+      <div class="body">
+        <slot name="body"></slot>
+      </div>
+    `
+  }
+}
+customElements.define('my-comment', Comment)
+```
+
+##### Stimulus
+
+In Stimulus, create a 1:1 mapping between a Stimulus controller and a component. In order to load in Stimulus controllers from the `app/components` tree, amend the Stimulus boot code in `app/javascript/packs/application.js`:
+
+```js
+const application = Application.start()
+const context = require.context("controllers", true, /.js$/)
+const context_components = require.context("../../components", true, /_controller.js$/)
+application.load(
+  definitionsFromContext(context).concat(
+    definitionsFromContext(context_components)
+  )
+)
+```
 
-### What happened to inline templates?
+This enables the creation of files such as `app/components/widget_controller.js`, where the controller identifier matches the `data-controller` attribute in the component's HTML template.
+
+## Frequently Asked Questions
+
+### Can I use other templating languages besides ERB?
 
-Inline templates have been removed (for now) due to concerns raised by [@soutaro](https://github.com/soutaro) regarding compatibility with the type systems being developed for Ruby 3.
+Yes. ViewComponent is tested against ERB, Haml, and Slim, but it should support most Rails template handlers.
 
 ### Isn't this just like X library?
 
-`ViewComponent` is far from a novel idea! Popular implementations of view components in Ruby include, but are not limited to:
+ViewComponent is far from a novel idea! Popular implementations of view components in Ruby include, but are not limited to:
 
 - [trailblazer/cells](https://github.com/trailblazer/cells)
 - [dry-rb/dry-view](https://github.com/dry-rb/dry-view)
@@ -633,6 +660,7 @@ Inline templates have been removed (for now) due to concerns raised by [@soutaro
 
 ## Resources
 
+- [Encapsulating Views, RailsConf 2020](https://youtu.be/YVYRus_2KZM)
 - [ViewComponent at GitHub with Joel Hawksley](https://the-ruby-blend.fireside.fm/9)
 - [Components, HAML vs ERB, and Design Systems](https://the-ruby-blend.fireside.fm/4)
 - [Choosing the Right Tech Stack with Dave Paola](https://5by5.tv/rubyonrails/307)
@@ -648,7 +676,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/github
 
 ## Contributors
 
-`view_component` is built by:
+ViewComponent is built by:
 
 |<img src="https://avatars.githubusercontent.com/joelhawksley?s=256" alt="joelhawksley" width="128" />|<img src="https://avatars.githubusercontent.com/tenderlove?s=256" alt="tenderlove" width="128" />|<img src="https://avatars.githubusercontent.com/jonspalmer?s=256" alt="jonspalmer" width="128" />|<img src="https://avatars.githubusercontent.com/juanmanuelramallo?s=256" alt="juanmanuelramallo" width="128" />|<img src="https://avatars.githubusercontent.com/vinistock?s=256" alt="vinistock" width="128" />|
 |:---:|:---:|:---:|:---:|:---:|
@@ -687,4 +715,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/github
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+ViewComponent is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/app/controllers/{rails/view_components_controller.rb → view_components_controller.rb}

@@ -2,8 +2,8 @@
 
 require "rails/application_controller"
 
-class Rails::ViewComponentsController < Rails::ApplicationController # :nodoc:
-  prepend_view_path File.expand_path("../../../lib/railties/lib/rails/templates/rails", __dir__)
+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
@@ -16,26 +16,19 @@ class Rails::ViewComponentsController < Rails::ApplicationController # :nodoc:
   def index
     @previews = ViewComponent::Preview.all
     @page_title = "Component Previews"
-    # rubocop:disable GitHub/RailsControllerRenderPathsExist
-    render "components/index"
-    # rubocop:enable GitHub/RailsControllerRenderPathsExist
   end
 
   def previews
     if params[:path] == @preview.preview_name
       @page_title = "Component Previews for #{@preview.preview_name}"
-      # rubocop:disable GitHub/RailsControllerRenderPathsExist
-      render "components/previews"
-      # rubocop:enable GitHub/RailsControllerRenderPathsExist
+      render "view_components/previews"
     else
       prepend_application_view_paths
       @example_name = File.basename(params[:path])
       @render_args = @preview.render_args(@example_name, params: params.permit!)
       layout = @render_args[:layout]
       opts = layout.nil? ? {} : { layout: layout }
-      # rubocop:disable GitHub/RailsControllerRenderPathsExist
-      render "components/preview", **opts
-      # rubocop:enable GitHub/RailsControllerRenderPathsExist
+      render "view_components/preview", opts
     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/{lib/railties/lib/rails/templates/rails/components → app/views/view_components}/previews.html.erb

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

data/lib/view_component/base.rb

@@ -10,15 +10,11 @@ module ViewComponent
     include ActiveSupport::Configurable
     include ViewComponent::Previewable
 
+    # For CSRF authenticity tokens in forms
     delegate :form_authenticity_token, :protect_against_forgery?, to: :helpers
 
-    class_attribute :content_areas, default: []
-    self.content_areas = [] # default doesn't work until Rails 5.2
-
-    # Render a component collection.
-    def self.with_collection(*args)
-      Collection.new(self, *args)
-    end
+    class_attribute :content_areas
+    self.content_areas = [] # class_attribute:default doesn't work until Rails 5.2
 
     # Entrypoint for rendering components.
     #
@@ -45,17 +41,29 @@ module ViewComponent
     # <span title="greeting">Hello, world!</span>
     #
     def render_in(view_context, &block)
-      self.class.compile!
+      self.class.compile(raise_errors: true)
+
       @view_context = view_context
-      @view_renderer ||= view_context.view_renderer
       @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_check
@@ -77,12 +85,10 @@ module ViewComponent
       true
     end
 
-    def self.short_identifier
-      @short_identifier ||= defined?(Rails.root) ? source_location.sub("#{Rails.root}/", "") : source_location
-    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)
@@ -95,7 +101,7 @@ module ViewComponent
       @controller ||= view_context.controller
     end
 
-    # Provides a proxy to access helper methods through
+    # Provides a proxy to access helper methods
     def helpers
       @helpers ||= view_context
     end
@@ -105,14 +111,17 @@ module ViewComponent
       self.class.source_location.gsub(%r{(.*app/components)|(\.rb)}, "")
     end
 
+    # For caching, such as #cache_if
     def view_cache_dependencies
       []
     end
 
-    def format # :nodoc:
+    # 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}'"
@@ -128,6 +137,9 @@ module ViewComponent
 
     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
@@ -143,7 +155,18 @@ module ViewComponent
     class << self
       attr_accessor :source_location
 
+      # Render a component collection.
+      def with_collection(*args)
+        Collection.new(self, *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
@@ -165,36 +188,52 @@ module ViewComponent
       end
 
       def compiled?
-        @compiled && ActionView::Base.cache_template_loading
-      end
+        @compiled ||= false
 
-      def compile!
-        compile(raise_template_errors: true)
+        @compiled && ActionView::Base.cache_template_loading
       end
 
       # Compile templates to instance methods, assuming they haven't been compiled already.
-      # We could in theory do this on app boot, at least in production environments.
-      # Right now this just compiles the first time the component is rendered.
-      def compile(raise_template_errors: false)
+      #
+      # 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_template_errors
+          raise ViewComponent::TemplateError.new(template_errors) if raise_errors
           return false
         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_counter_parameter_name) do
-          "#{collection_parameter_name}_counter".to_sym
+        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_name)
+          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
@@ -208,8 +247,13 @@ module ViewComponent
           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 #{call_method_name(template[:variant])}
+            def #{method_name}
               @output_buffer = ActionView::OutputBuffer.new
               #{compiled_template(template[:path])}
             end
@@ -236,21 +280,38 @@ module ViewComponent
         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
+        attr_reader(*areas)
         self.content_areas = areas
       end
 
-      # Support overriding this component's collection parameter name
+      # Support overriding collection parameter name
       def with_collection_parameter(param)
-        @with_collection_parameter = param
+        @provided_collection_parameter = param
       end
 
-      def collection_parameter_name
-        (@with_collection_parameter || name.demodulize.underscore.chomp("_component")).to_sym
+      # 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 instance_method(:initialize).parameters.map(&:last).include?(parameter)
+
+        raise ArgumentError.new(
+          "#{self} initializer must accept " \
+          "`#{parameter}` collection parameter."
+        )
       end
 
       private
 
+      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)

data/lib/view_component/collection.rb

@@ -5,7 +5,9 @@ module ViewComponent
     def render_in(view_context, &block)
       iterator = ActionView::PartialIteration.new(@collection.size)
 
-      @component.compile!
+      @component.compile(raise_errors: true)
+      @component.validate_collection_parameter!(validate_default: true)
+
       @collection.map do |item|
         content = @component.new(component_options(item, iterator)).render_in(view_context, &block)
         iterator.iterate!
@@ -30,8 +32,8 @@ module ViewComponent
     end
 
     def component_options(item, iterator)
-      item_options = { @component.collection_parameter_name => item }
-      item_options[@component.collection_counter_parameter_name] = iterator.index + 1 if @component.counter_argument_present?
+      item_options = { @component.collection_parameter => item }
+      item_options[@component.collection_counter_parameter] = iterator.index + 1 if @component.counter_argument_present?
 
       @options.merge(item_options)
     end

data/lib/view_component/engine.rb

@@ -11,6 +11,7 @@ module ViewComponent
       options = app.config.view_component
 
       options.show_previews = Rails.env.development? if options.show_previews.nil?
+      options.preview_route ||= ViewComponent::Base.preview_route
 
       if options.show_previews
         options.preview_path ||= defined?(Rails.root) ? "#{Rails.root}/test/components/previews" : nil
@@ -64,8 +65,8 @@ module ViewComponent
 
       if options.show_previews
         app.routes.prepend do
-          get "/rails/view_components"       => "rails/view_components#index", :internal => true
-          get "/rails/view_components/*path" => "rails/view_components#previews", :internal => true
+          get options.preview_route, to: "view_components#index", as: :preview_view_components, internal: true
+          get "#{options.preview_route}/*path", to: "view_components#previews", as: :preview_view_component, internal: true
         end
       end
     end

data/lib/view_component/preview.rb

@@ -23,6 +23,7 @@ module ViewComponent # :nodoc:
         example_params_names = instance_method(example).parameters.map(&:last)
         provided_params = params.slice(*example_params_names).to_h.symbolize_keys
         result = provided_params.empty? ? new.public_send(example) : new.public_send(example, **provided_params)
+        @layout = nil unless defined?(@layout)
         result.merge(layout: @layout)
       end
 

data/lib/view_component/previewable.rb

@@ -20,6 +20,16 @@ module ViewComponent # :nodoc:
       # Defaults to +true+ for development environment
       #
       mattr_accessor :show_previews, instance_writer: false
+
+      # Set the entry route for component previews through app configuration:
+      #
+      #     config.view_component.preview_route = "/previews"
+      #
+      # Defaults to +/rails/view_components+ when `show_previews' is enabled
+      #
+      mattr_accessor :preview_route, instance_writer: false do
+        "/rails/view_components"
+      end
     end
   end
 end

data/lib/view_component/version.rb

@@ -3,8 +3,8 @@
 module ViewComponent
   module VERSION
     MAJOR = 2
-    MINOR = 5
-    PATCH = 1
+    MINOR = 6
+    PATCH = 0
 
     STRING = [MAJOR, MINOR, PATCH].join(".")
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component
 version: !ruby/object:Gem::Version
-  version: 2.5.1
+  version: 2.6.0
 platform: ruby
 authors:
 - GitHub Open Source
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-21 00:00:00.000000000 Z
+date: 2020-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -64,14 +64,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.6.0
 - !ruby/object:Gem::Dependency
   name: haml
   requirement: !ruby/object:Gem::Requirement
@@ -152,7 +152,10 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- app/controllers/rails/view_components_controller.rb
+- app/controllers/view_components_controller.rb
+- app/views/view_components/index.html.erb
+- app/views/view_components/preview.html.erb
+- app/views/view_components/previews.html.erb
 - lib/rails/generators/component/USAGE
 - lib/rails/generators/component/component_generator.rb
 - lib/rails/generators/component/templates/component.rb.tt
@@ -166,10 +169,6 @@ files:
 - lib/rails/generators/slim/templates/component.html.slim.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/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/view_component.rb
 - lib/view_component/base.rb
 - lib/view_component/collection.rb

data/lib/railties/lib/rails.rb

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

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

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

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

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