view_component 2.4.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0004a178e80b26bc7c47af5ef2dab32cdb4f3c61d09a1b27e593cf8ec4f5ea
-  data.tar.gz: 16427ce66ee5872627dafd670799fe19c42bfec499163dcbbe4e643a0e3b34fc
+  metadata.gz: 7ac6dfbc2cb2fb7bbad0aac55de41cfbdc782dac0eb14f1e4b18784e15db02a9
+  data.tar.gz: 294bd6faac8d95b0db842ab67139e141117058148c24d503647960e31c19ef21
 SHA512:
-  metadata.gz: 7ea71f48ee58741b49df4818f0717328b715a1c11ebb0ecf0771c15aabb53fc3cdb51428c0b5f85781c04f113afca98fbe152083090f9f0b518f988cd60de3e9
-  data.tar.gz: 401537d259e436c9cb0ea7e3c4dc40af6c02f69013460583b4827795f9d615d79aa510aa9472840af05edea39d689d6cd785279a82c6e1b48ebb980654c03087
+  metadata.gz: 4d2da7f6d4ff599ea9b92408dc632eecb7629d7bf7cda9484eab20b0f02dd1a78ba3669fc5f9107f2b6388d2f5634258a14b806d58327c716a8339b819ef8aa7
+  data.tar.gz: 50b86ff9e697608ae063352c8a55430763b5762016c3512dfa103f5df7a2fbb4875a993e319783f2e1e077c4ca157152a4314d3a106b0fc0a84186926044f917

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # master
 
+# 2.8.0
+
+* Add `before_render`, deprecating `before_render_check`.
+
+    *Joel Hawksley*
+
+# 2.7.0
+
+* Add `rendered_component` method to `ViewComponent::TestHelpers` which exposes the raw output of the rendered component.
+
+    *Richard Macklin*
+
+* Support sidecar directories for views and other assets.
+
+    *Jon Palmer*
+
+# 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.
+
+    *Rainer Borene*
+
+# v2.5.0
+
+* Add counter variables when rendering collections.
+
+    *Frank S*
+
+* Add the ability to access params from preview examples.
+
+    *Fabio Cantoni*
+
 # v2.4.0
 
 * Add `#render_to_string` support.

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.
+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 class names end in -`Component`.
+Component names end in -`Component`.
 
-Component module names are plural, as they are for controllers. (`Users::AvatarComponent`)
-
-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,62 @@ 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).
+### Sidecar Assets
+
+ViewComponents supports two options for defining view files.
+
+#### Sidecar view
+
+The simplest option is to place the view next to the Ruby component:
+
+```
+app/components
+├── ...
+├── test_component.rb
+├── test_component.html.erb
+├── ...
+```
+
+#### Sidecar directory
+
+As an alternative, views and other assets can be placed in a sidecar directory with the same name as the component, which can be useful for organizing views alongside other assets like Javascript and CSS.
+
+```
+app/components
+├── ...
+├── test_component.rb
+├── test_component
+|   ├── test_component.css
+|   ├── test_component.html.erb
+|   └── test_component.js
+├── ...
+
+```
 
 ### 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 +245,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 +272,30 @@ 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`._
+
+### `before_render`
+
+Components can define a `before_render` method to be called before a component is rendered, when `helpers` is able to be used:
+
+`app/components/confirm_email_component.rb`
+```ruby
+class MyComponent < ViewComponent::Base
+  def before_render
+    @my_icon = helpers.star_icon
+  end
+end
+```
 
 ### 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 +305,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,140 +351,74 @@ 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:
+#### Collection counter
 
-Near the top the entry file, add:
+ViewComponent defines a counter variable matching the parameter name above, followed by `_counter`. To access the variable, add it to `initialize` as an argument:
 
-```js
-import "../components"
+`app/components/product_component.rb`
+``` ruby
+class ProductComponent < ViewComponent::Base
+  def initialize(product:, product_counter:)
+    @product = product
+    @counter = product_counter
+  end
+end
 ```
 
-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$/))
+`app/components/product_component.html.erb`
+``` erb
+<li>
+  <%= @counter %> <%= @product.name %>
+</li>
 ```
 
-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.
+### Using helpers
 
-#### Encapsulating sidecar assets
+Helper methods can be used through the `helpers` proxy:
 
-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
+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>
+Which can be used with `delegate`:
 
-  <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 { … }
-    `
-  }
+```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"
@@ -464,12 +427,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`, assert against the return value of `render_inline`, which is an instance of `Nokogiri::HTML::DocumentFragment`:
 
 ```ruby
 test "render component" do
@@ -479,6 +442,31 @@ test "render component" do
 end
 ```
 
+Alternatively, assert against the raw output of the component, which is exposed as `rendered_component`:
+
+```ruby
+test "render component" do
+  render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }
+
+  assert_includes rendered_component, "Hello, World!"
+end
+```
+
+To test components that use `with_content_areas`:
+
+```ruby
+test "renders content_areas template with content " do
+  render_inline(ContentAreasComponent.new(footer: "Bye!")) do |component|
+    component.with(:title, "Hello!")
+    component.with(:body) { "Have a nice day." }
+  end
+
+  assert_selector(".title", text: "Hello!")
+  assert_selector(".body", text: "Have a nice day.")
+  assert_selector(".footer", text: "Bye!")
+end
+```
+
 #### Action Pack Variants
 
 Use the `with_variant` helper to test specific variants:
@@ -488,7 +476,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
 ```
@@ -508,7 +496,7 @@ class TestComponentPreview < ViewComponent::Preview
   end
 
   def with_content_block
-    render(TestComponent.new(title: "This component accepts a block of content") do
+    render(TestComponent.new(title: "This component accepts a block of content")) do
       tag.div do
         content_tag(:span, "Hello")
       end
@@ -521,15 +509,24 @@ Which generates
 <http://localhost:3000/rails/view_components/test_component/with_long_title>,
 and <http://localhost:3000/rails/view_components/test_component/with_content_block>.
 
-The `ViewComponent::Preview` base class includes
-[`ActionView::Helpers::TagHelper`][tag-helper], which provides the [`tag`][tag]
-and [`content_tag`][content_tag] view helper methods.
+It's also possible to set dynamic values from the params by setting them as arguments:
 
-[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
+`test/components/previews/test_component_preview.rb`
+```ruby
+class TestComponentPreview < ViewComponent::Preview
+  def with_dynamic_title(title: "Test component default")
+    render(TestComponent.new(title: title))
+  end
+end
+```
 
-Previews default to the application layout, but can be overridden:
+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`](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 use the application layout by default, but can use a specific layout with the `layout` option:
 
 `test/components/previews/test_component_preview.rb`
 ```ruby
@@ -540,18 +537,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
@@ -580,19 +584,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.
 
-Yes. This gem is tested against ERB, Haml, and Slim, but it should support most Rails template handlers.
+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
 
-### What happened to inline templates?
+  def avatar
+    commenter.avatar_image_url
+  end
+
+  def formatted_body
+    simple_format(@comment.body)
+  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>
+```
+
+`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)
+  )
+)
+```
+
+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)
@@ -601,6 +730,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)
@@ -616,7 +746,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" />|
 |:---:|:---:|:---:|:---:|:---:|
@@ -648,11 +778,11 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/github
 |@blakewilliams|@seanpdoyle|@tclem|@nashby|@jaredcwhite|
 |Boston, MA|New York, NY|San Francisco, CA|Minsk|Portland, OR|
 
-|<img src="https://avatars.githubusercontent.com/simonrand?s=256" alt="simonrand" width="128" />|<img src="https://avatars.githubusercontent.com/fugufish?s=256" alt="fugufish" width="128" />|
-|:---:|:---:|
-|@simonrand|@fugufish|
-|Dublin, Ireland|Salt Lake City, Utah|
+|<img src="https://avatars.githubusercontent.com/simonrand?s=256" alt="simonrand" width="128" />|<img src="https://avatars.githubusercontent.com/fugufish?s=256" alt="fugufish" width="128" />|<img src="https://avatars.githubusercontent.com/cover?s=256" alt="cover" width="128" />|<img src="https://avatars.githubusercontent.com/franks921?s=256" alt="franks921" width="128" />|
+|:---:|:---:|:---:|:---:|
+|@simonrand|@fugufish|@cover|@franks921|
+|Dublin, Ireland|Salt Lake City, Utah|Barcelona|South Africa|
 
 ## 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).