view_component 2.17.0 → 2.19.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+.
@@ -47,6 +50,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 +70,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 +99,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 +109,7 @@ end
 ```
 
 `app/components/test_component.html.erb`:
+
 ```erb
 <span title="<%= @title %>"><%= content %></span>
 ```
@@ -124,6 +135,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 +143,7 @@ end
 ```
 
 `app/components/modal_component.html.erb`:
+
 ```erb
 <div class="modal">
   <div class="header"><%= header %></div>
@@ -164,19 +177,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 +195,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`
 
-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 +214,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 +249,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 +273,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 +306,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 +333,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 +353,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 +365,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 +374,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 +386,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 +419,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 +429,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 +439,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 +453,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 +473,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 +487,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 +509,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 +525,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 +544,7 @@ end
 ```
 
 `app/components/product_component.html.erb`
+
 ``` erb
 <li>
   <h2><%= @item.name %></h2>
@@ -493,6 +557,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 +568,7 @@ end
 ```
 
 `app/components/product_component.html.erb`
+
 ``` erb
 <li>
   <%= @counter %> <%= @product.name %>
@@ -551,7 +617,7 @@ class UserComponent < ViewComponent::Base
 end
 ```
 
-### Testing
+### Writing tests
 
 Unit test components directly, using the `render_inline` test helper, asserting against the rendered output.
 
@@ -619,9 +685,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 +717,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 +735,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"
@@ -674,9 +744,19 @@ class TestComponentPreview < ViewComponent::Preview
 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.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"
 ```
@@ -684,6 +764,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"
 ```
@@ -695,6 +776,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
@@ -703,6 +785,7 @@ end
 ```
 
 `test/components/previews/cell_component_preview/default.html.erb`
+
 ```erb
 <table class="table">
   <tbody>
@@ -717,6 +800,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
@@ -728,6 +812,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")
@@ -746,6 +831,7 @@ Which enables passing in a value with <http://localhost:3000/rails/components/ce
 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
 config.view_component.test_controller = "BaseController"
 ```
@@ -755,6 +841,7 @@ config.view_component.test_controller = "BaseController"
 To use RSpec, add the following:
 
 `spec/rails_helper.rb`
+
 ```ruby
 require "view_component/test_helpers"
 
@@ -768,6 +855,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"
 ```
@@ -780,7 +868,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") %>
 ```
 
@@ -818,6 +906,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:)
@@ -847,6 +936,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>
@@ -860,6 +950,7 @@ end
 ```
 
 `app/components/comment_component.js`
+
 ```js
 class Comment extends HTMLElement {
   styles() {
@@ -913,6 +1004,29 @@ 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.
 
+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?
@@ -944,7 +1058,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
 
@@ -990,10 +1104,15 @@ ViewComponent is built by:
 |@maxbeizer|@franco|@tbroad-ramsey|@jensljungblad|@bbugh|
 |Nashville, TN|Switzerland|Spring Hill, TN|New York, NY|Austin, TX|
 
-|<img src="https://avatars.githubusercontent.com/johannesengl?s=256" alt="johannesengl" width="128" />|<img src="https://avatars.githubusercontent.com/czj?s=256" alt="czj" width="128" />|<img src="https://avatars.githubusercontent.com/mrrooijen?s=256" alt="mrrooijen" width="128" />|
-|:---:|:---:|:---:|
-|@johannesengl|@czj|@mrrooijen|
-|Berlin, Germany|Paris, France|The Netherlands|
+|<img src="https://avatars.githubusercontent.com/johannesengl?s=256" alt="johannesengl" width="128" />|<img src="https://avatars.githubusercontent.com/czj?s=256" alt="czj" width="128" />|<img src="https://avatars.githubusercontent.com/mrrooijen?s=256" alt="mrrooijen" width="128" />|<img src="https://avatars.githubusercontent.com/bradparker?s=256" alt="bradparker" width="128" />|<img src="https://avatars.githubusercontent.com/mattbrictson?s=256" alt="mattbrictson" width="128" />|
+|:---:|:---:|:---:|:---:|:---:|
+|@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" />|
+|:---:|:---:|
+|@mixergtz|@jules2689|
+|Medellin, Colombia|Toronto, Canada|
 
 ## License