view_component 2.18.0 → 2.20.0

data/README.md

@@ -1,10 +1,13 @@
 # ViewComponent
+
 ViewComponent is a framework for building view components that are reusable, testable & encapsulated, in Ruby on Rails.
 
 ## Design philosophy
+
 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).
 
 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+.
@@ -14,13 +17,7 @@ ViewComponent is tested for compatibility [with combinations of](https://github.
 In `Gemfile`, add:
 
 ```ruby
-gem "view_component"
-```
-
-In `config/application.rb`, add:
-
-```bash
-require "view_component/engine"
+gem "view_component", require: "view_component/engine"
 ```
 
 ## Guide
@@ -47,6 +44,10 @@ Traditional Rails views have an implicit interface, making it hard to reason abo
 
 ViewComponents use a standard Ruby initializer that clearly defines what is needed to render, making them easier (and safer) to reuse than partials.
 
+#### Performance
+
+Based on our [benchmarks](performance/benchmark.rb), ViewComponents are ~10x faster than partials.
+
 #### Standards
 
 Views often fail basic Ruby code quality standards: long methods, deep conditional nesting, and mystery guests abound.
@@ -63,6 +64,8 @@ Component names end in -`Component`.
 
 Component module names are plural, as for controllers and jobs: `Users::AvatarComponent`
 
+Name components for what they render, not what they accept. (`AvatarComponent` instead of `UserComponent`)
+
 #### Quick start
 
 Use the component generator to create a new ViewComponent.
@@ -90,6 +93,7 @@ bin/rails generate component Example title content --template-engine slim
 A ViewComponent is a Ruby file and corresponding template file with the same base name:
 
 `app/components/test_component.rb`:
+
 ```ruby
 class TestComponent < ViewComponent::Base
   def initialize(title:)
@@ -99,6 +103,7 @@ end
 ```
 
 `app/components/test_component.html.erb`:
+
 ```erb
 <span title="<%= @title %>"><%= content %></span>
 ```
@@ -124,6 +129,7 @@ Content passed to a ViewComponent as a block is captured and assigned to the `co
 ViewComponents can declare additional content areas. For example:
 
 `app/components/modal_component.rb`:
+
 ```ruby
 class ModalComponent < ViewComponent::Base
   with_content_areas :header, :body
@@ -131,6 +137,7 @@ end
 ```
 
 `app/components/modal_component.html.erb`:
+
 ```erb
 <div class="modal">
   <div class="header"><%= header %></div>
@@ -164,19 +171,17 @@ Returning:
 
 _Slots are currently under development as a successor to Content Areas. The Slot APIs should be considered unfinished and subject to breaking changes in non-major releases of ViewComponent._
 
-Slots enable multiple blocks of content to be passed to a single ViewComponent.
-
-Slots exist in two forms: normal slots and collection slots.
+Slots enable multiple blocks of content to be passed to a single ViewComponent, reducing the need for sub-components (e.g. ModalHeader, ModalBody).
 
-Normal slots can be rendered once per component. They expose an accessor with the name of the slot that returns an instance of `ViewComponent::Slot`, etc.
+By default, slots can be rendered once per component. They provide an accessor with the name of the slot (`#header`) that returns an instance of `ViewComponent::Slot`, etc.
 
-Collection slots can be rendered multiple times. They expose an accessor with the pluralized name of the slot (`#rows`), which is an Array of `ViewComponent::Slot` instances.
+Slots declared with `collection: true` can be rendered multiple times. They provide an accessor with the pluralized name of the slot (`#rows`), which is an Array of `ViewComponent::Slot` instances.
 
-To learn more about the design of the Slots API, see https://github.com/github/view_component/pull/348.
+To learn more about the design of the Slots API, see [#348](https://github.com/github/view_component/pull/348) and [#325](https://github.com/github/view_component/discussions/325).
 
 ##### Defining Slots
 
-Slots are defined by the `with_slot` macro:
+Slots are defined by `with_slot`:
 
 `with_slot :header`
 
@@ -184,15 +189,16 @@ To define a collection slot, add `collection: true`:
 
 `with_slot :row, collection: true`
 
-To define a slot with a custom class, pass `class_name`:
+To define a slot with a custom Ruby class, pass `class_name`:
 
-`with_slot :body, class_name: 'BodySlot`
+`with_slot :body, class_name: 'BodySlot'`
 
-Slot classes should be subclasses of `ViewComponent::Slot`.
+_Note: Slot classes must be subclasses of `ViewComponent::Slot`._
 
 ##### Example ViewComponent with Slots
 
 `# box_component.rb`
+
 ```ruby
 class BoxComponent < ViewComponent::Base
   include ViewComponent::Slotable
@@ -202,12 +208,12 @@ class BoxComponent < ViewComponent::Base
   with_slot :row, collection: true, class_name: "Row"
 
   class Header < ViewComponent::Slot
-    def initialize(class_names: "")
-      @class_names = class_names
+    def initialize(classes: "")
+      @classes = classes
     end
 
-    def class_names
-      "Box-header #{@class_names}"
+    def classes
+      "Box-header #{@classes}"
     end
   end
 
@@ -237,10 +243,11 @@ end
 ```
 
 `# box_component.html.erb`
+
 ```erb
 <div class="Box">
   <% if header %>
-    <div class="<%= header.class_names %>">
+    <div class="<%= header.classes %>">
       <%= header.content %>
     </div>
   <% end %>
@@ -260,16 +267,17 @@ end
   <% end %>
   <% if footer %>
     <div class="Box-footer">
-      <%= footer %>
+      <%= footer.content %>
     </div>
   <% end %>
 </div>
 ```
 
 `# index.html.erb`
+
 ```erb
 <%= render(BoxComponent.new) do |component| %>
-  <% component.slot(:header, class_names: "my-class-name") do %>
+  <% component.slot(:header, classes: "my-class-name") do %>
     This is my header!
   <% end %>
   <% component.slot(:body) do %>
@@ -292,6 +300,7 @@ end
 ViewComponents can render without a template file, by defining a `call` method:
 
 `app/components/inline_component.rb`:
+
 ```ruby
 class InlineComponent < ViewComponent::Base
   def call
@@ -318,6 +327,18 @@ class InlineVariantComponent < ViewComponent::Base
 end
 ```
 
+### Template Inheritance
+
+Components that subclass another component inherit the parent component's
+template if they don't define their own template.
+
+```ruby
+# If `my_link_component.html.erb` is not defined the component will fall back
+# to `LinkComponent`s template
+class MyLinkComponent < LinkComponent
+end
+```
+
 ### Sidecar Assets
 
 ViewComponents supports two options for defining view files.
@@ -326,7 +347,7 @@ ViewComponents supports two options for defining view files.
 
 The simplest option is to place the view next to the Ruby component:
 
-```
+```console
 app/components
 ├── ...
 ├── test_component.rb
@@ -338,7 +359,7 @@ app/components
 
 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.
 
-```
+```console
 app/components
 ├── ...
 ├── example_component.rb
@@ -347,12 +368,11 @@ app/components
 |   ├── example_component.html.erb
 |   └── example_component.js
 ├── ...
-
 ```
 
 To generate a component with a sidecar directory, use the `--sidecar` flag:
 
-```
+```console
 bin/rails generate component Example title content --sidecar
       invoke  test_unit
       create  test/components/example_component_test.rb
@@ -360,6 +380,32 @@ bin/rails generate component Example title content --sidecar
       create  app/components/example_component/example_component.html.erb
 ```
 
+#### Component file inside Sidecar directory
+
+It's also possible to place the Ruby component file inside the sidecar directory, grouping all related files in the same folder:
+
+_Note: Avoid giving your containing folder the same name as your `.rb` file or there will be a conflict between Module and Class definitions_
+
+```console
+app/components
+├── ...
+├── example
+|   ├── component.rb
+|   ├── component.css
+|   ├── component.html.erb
+|   └── component.js
+├── ...
+
+```
+
+The component can then be rendered using the folder name as a namespace:
+
+```erb
+<%= render(Example::Component.new(title: "my title")) do %>
+  Hello, World!
+<% end %>
+```
+
 ### Conditional Rendering
 
 Components can implement a `#render?` method to be called after initialization to determine if the component should render.
@@ -367,7 +413,8 @@ Components can implement a `#render?` method to be called after initialization t
 Traditionally, the logic for whether to render a view could go in either the component template:
 
 `app/components/confirm_email_component.html.erb`
-```
+
+```erb
 <% if user.requires_confirmation? %>
   <div class="alert">Please confirm your email address.</div>
 <% end %>
@@ -376,6 +423,7 @@ Traditionally, the logic for whether to render a view could go in either the com
 or the view that renders the component:
 
 `app/views/_banners.html.erb`
+
 ```erb
 <% if current_user.requires_confirmation? %>
   <%= render(ConfirmEmailComponent.new(user: current_user)) %>
@@ -385,6 +433,7 @@ or the view that renders the component:
 Using the `#render?` hook simplifies the view:
 
 `app/components/confirm_email_component.rb`
+
 ```ruby
 class ConfirmEmailComponent < ViewComponent::Base
   def initialize(user:)
@@ -398,13 +447,15 @@ end
 ```
 
 `app/components/confirm_email_component.html.erb`
-```
+
+```erb
 <div class="banner">
   Please confirm your email address.
 </div>
 ```
 
 `app/views/_banners.html.erb`
+
 ```erb
 <%= render(ConfirmEmailComponent.new(user: current_user)) %>
 ```
@@ -416,6 +467,7 @@ _To assert that a component has not been rendered, use `refute_component_rendere
 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
@@ -429,11 +481,13 @@ end
 Use `with_collection` to render a ViewComponent with a collection:
 
 `app/view/products/index.html.erb`
+
 ``` erb
 <%= render(ProductComponent.with_collection(@products)) %>
 ```
 
 `app/components/product_component.rb`
+
 ``` ruby
 class ProductComponent < ViewComponent::Base
   def initialize(product:)
@@ -449,6 +503,7 @@ end
 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
@@ -464,11 +519,13 @@ end
 Additional arguments besides the collection are passed to each component instance:
 
 `app/view/products/index.html.erb`
+
 ``` erb
 <%= render(ProductComponent.with_collection(@products, notice: "hi")) %>
 ```
 
 `app/components/product_component.rb`
+
 ``` ruby
 class ProductComponent < ViewComponent::Base
   with_collection_parameter :item
@@ -481,6 +538,7 @@ end
 ```
 
 `app/components/product_component.html.erb`
+
 ``` erb
 <li>
   <h2><%= @item.name %></h2>
@@ -493,6 +551,7 @@ end
 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
 class ProductComponent < ViewComponent::Base
   def initialize(product:, product_counter:)
@@ -503,6 +562,7 @@ end
 ```
 
 `app/components/product_component.html.erb`
+
 ``` erb
 <li>
   <%= @counter %> <%= @product.name %>
@@ -551,7 +611,7 @@ class UserComponent < ViewComponent::Base
 end
 ```
 
-### Testing
+### Writing tests
 
 Unit test components directly, using the `render_inline` test helper, asserting against the rendered output.
 
@@ -561,7 +621,7 @@ Capybara matchers are available if the gem is installed:
 require "view_component/test_case"
 
 class MyComponentTest < ViewComponent::TestCase
-  test "render component" do
+  def test_render_component
     render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }
 
     assert_selector("span[title='my title']", text: "Hello, World!")
@@ -572,7 +632,7 @@ end
 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
+def test_render_component
   result = render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }
 
   assert_includes result.css("span[title='my title']").to_html, "Hello, World!"
@@ -582,7 +642,7 @@ end
 Alternatively, assert against the raw output of the component, which is exposed as `rendered_component`:
 
 ```ruby
-test "render component" do
+def test_render_component
   render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }
 
   assert_includes rendered_component, "Hello, World!"
@@ -592,7 +652,7 @@ end
 To test components that use `with_content_areas`:
 
 ```ruby
-test "renders content_areas template with content " do
+def test_renders_content_areas_template_with_content
   render_inline(ContentAreasComponent.new(footer: "Bye!")) do |component|
     component.with(:title, "Hello!")
     component.with(:body) { "Have a nice day." }
@@ -609,7 +669,7 @@ end
 Use the `with_variant` helper to test specific variants:
 
 ```ruby
-test "render component for tablet" do
+def test_render_component_for_tablet
   with_variant :tablet do
     render_inline(TestComponent.new(title: "my title")) { "Hello, tablets!" }
 
@@ -619,9 +679,11 @@ end
 ```
 
 ### Previewing Components
+
 `ViewComponent::Preview`, like `ActionMailer::Preview`, provides a way to preview components in isolation:
 
 `test/components/previews/test_component_preview.rb`
+
 ```ruby
 class TestComponentPreview < ViewComponent::Preview
   def with_default_title
@@ -649,6 +711,7 @@ and <http://localhost:3000/rails/view_components/test_component/with_content_blo
 It's also possible to set dynamic values from the params by setting them as arguments:
 
 `test/components/previews/test_component_preview.rb`
+
 ```ruby
 class TestComponentPreview < ViewComponent::Preview
   def with_dynamic_title(title: "Test component default")
@@ -666,6 +729,7 @@ and [`content_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHe
 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
 class TestComponentPreview < ViewComponent::Preview
   layout "admin"
@@ -677,14 +741,16 @@ end
 You can also set a custom layout to be used by default for previews as well as the preview index pages via the `default_preview_layout` configuration option:
 
 `config/application.rb`
+
 ```ruby
 # Set the default layout to app/views/layouts/component_preview.html.erb
-config.default_preview_layout = "component_preview"
+config.view_component.default_preview_layout = "component_preview"
 ```
 
 Preview classes live in `test/components/previews`, which can be configured using the `preview_paths` option:
 
 `config/application.rb`
+
 ```ruby
 config.view_component.preview_paths << "#{Rails.root}/lib/component_previews"
 ```
@@ -692,6 +758,7 @@ config.view_component.preview_paths << "#{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"
 ```
@@ -703,6 +770,7 @@ This example will make the previews available from <http://localhost:3000/previe
 Given a preview `test/components/previews/cell_component_preview.rb`, template files can be defined at `test/components/previews/cell_component_preview/`:
 
 `test/components/previews/cell_component_preview.rb`
+
 ```ruby
 class CellComponentPreview < ViewComponent::Preview
   def default
@@ -711,6 +779,7 @@ end
 ```
 
 `test/components/previews/cell_component_preview/default.html.erb`
+
 ```erb
 <table class="table">
   <tbody>
@@ -725,6 +794,7 @@ To use a different location for preview templates, pass the `template` argument:
 (the path should be relative to `config.view_component.preview_path`):
 
 `test/components/previews/cell_component_preview.rb`
+
 ```ruby
 class CellComponentPreview < ViewComponent::Preview
   def default
@@ -736,6 +806,7 @@ end
 Values from `params` can be accessed through `locals`:
 
 `test/components/previews/cell_component_preview.rb`
+
 ```ruby
 class CellComponentPreview < ViewComponent::Preview
   def default(title: "Default title", subtitle: "A subtitle")
@@ -749,11 +820,22 @@ end
 
 Which enables passing in a value with <http://localhost:3000/rails/components/cell_component/default?title=Custom+title&subtitle=Another+subtitle>.
 
+#### Configuring preview controller
+
+Previews can be extended to allow users to add authentication, authorization, before actions, or anything that the end user would need to meet their needs using the `preview_controller` option:
+
+`config/application.rb`
+
+```ruby
+config.view_component.preview_controller = "MyPreviewController"
+```
+
 #### Configuring TestController
 
-Component tests and previews assume the existence of an `ApplicationController` class, which be can be configured using the `test_controller` option:
+Component tests assume the existence of an `ApplicationController` class, which be can be configured using the `test_controller` option:
 
 `config/application.rb`
+
 ```ruby
 config.view_component.test_controller = "BaseController"
 ```
@@ -763,6 +845,7 @@ config.view_component.test_controller = "BaseController"
 To use RSpec, add the following:
 
 `spec/rails_helper.rb`
+
 ```ruby
 require "view_component/test_helpers"
 
@@ -776,6 +859,7 @@ Specs created by the generator have access to test helpers like `render_inline`.
 To use component previews:
 
 `config/application.rb`
+
 ```ruby
 config.view_component.preview_paths << "#{Rails.root}/spec/components/previews"
 ```
@@ -788,7 +872,7 @@ In order to [avoid conflicts](https://github.com/github/view_component/issues/28
 
 With the monkey patch disabled, use `render_component` (or  `render_component_to_string`) instead:
 
-```
+```erb
 <%= render_component Component.new(message: "bar") %>
 ```
 
@@ -826,6 +910,7 @@ One approach is to use Web Components, which contain all Javascript functionalit
 For example:
 
 `app/components/comment_component.rb`
+
 ```ruby
 class CommentComponent < ViewComponent::Base
   def initialize(comment:)
@@ -855,6 +940,7 @@ 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>
@@ -868,6 +954,7 @@ end
 ```
 
 `app/components/comment_component.js`
+
 ```js
 class Comment extends HTMLElement {
   styles() {
@@ -921,6 +1008,35 @@ application.load(
 
 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.
 
+After configuring Webpack to load Stimulus controller files from the `components` directory, add the path to `resolved_paths` in `config/webpacker.yml`:
+
+```yml
+  resolved_paths: ["app/components"]
+```
+
+When placing a Stimulus controller inside a sidecar directory, be aware that when referencing the controller [each forward slash in a namespaced controller file’s path becomes two dashes in its identifier](
+https://stimulusjs.org/handbook/installing#controller-filenames-map-to-identifiers):
+
+```console
+app/components
+├── ...
+├── example
+|   ├── component.rb
+|   ├── component.css
+|   ├── component.html.erb
+|   └── component_controller.js
+├── ...
+```
+
+`component_controller.js`'s Stimulus identifier becomes: `example--component`:
+
+```erb
+<div data-controller="example--component">
+  <input type="text">
+  <button data-action="click->example--component#greet">Greet</button>
+</div>
+```
+
 ## Frequently Asked Questions
 
 ### Can I use other templating languages besides ERB?
@@ -952,7 +1068,7 @@ ViewComponent is far from a novel idea! Popular implementations of view componen
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/github/view_component. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. We recommend reading the [contributing guide](./CONTRIBUTING.md) as well.
+This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. We recommend reading the [contributing guide](./CONTRIBUTING.md) as well.
 
 ## Contributors
 
@@ -1003,6 +1119,11 @@ ViewComponent is built by:
 |@johannesengl|@czj|@mrrooijen|@bradparker|@mattbrictson|
 |Berlin, Germany|Paris, France|The Netherlands|Brisbane, Australia|San Francisco|
 
+|<img src="https://avatars.githubusercontent.com/mixergtz?s=256" alt="mixergtz" width="128" />|<img src="https://avatars.githubusercontent.com/jules2689?s=256" alt="jules2689" width="128" />|<img src="https://avatars.githubusercontent.com/g13ydson?s=256" alt="g13ydson" width="128" />|<img src="https://avatars.githubusercontent.com/swanson?s=256" alt="swanson" width="128" />|
+|:---:|:---:|:---:|:---:|
+|@mixergtz|@jules2689|@g13ydson|@swanson|
+|Medellin, Colombia|Toronto, Canada|João Pessoa, Brazil|Indianapolis, IN|
+
 ## License
 
 ViewComponent is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).