Add Lookbook (#100)

lorenyu · web-flow · commit 6dbe98ab96da · 2025-05-01T12:34:04.000-07:00
- Add lookbook gem and related dependencies
- Add ENABLE_LOOKBOOK environment variable, defaulting to true in local
and dev environment
- Mount lookbook if ENABLE_LOOKBOOK is set
- Add component_preview layout for previewing partials without
application header/footer
- Add breadcrumb preview
- Make partial paths explicit
diff --git a/template-only-docs/Deployment.md b/template-only-docs/Deployment.md
@@ -39,6 +39,16 @@ While following the [infrastructure template installation instructions](https://
     ```
 1. Follow the infrastructure template instructions to configure [custom domains](https://github.com/navapbc/template-infra/blob/main/docs/infra/set-up-custom-domains.md) and [https support](https://github.com/navapbc/template-infra/blob/main/docs/infra/https-support.md).
 
+## Enabling Lookbook on the dev environment
+
+Lookbook is useful for sharing in progress components with teammates, including product managers and designers. To enable Lookbook on the dev environment, add an environment variable `ENABLE_LOOKBOOK` set to `true` in `/infra/<APP_NAME>/app-config/dev.tf` by adding the following code.
+
+```terraform
+service_override_extra_environment_variables = {
+  ENABLE_LOOKBOOK = "true"
+}
+```
+
 ## Deploying using another method
 
 - AWS Cognito requires a lot of configuration to work correctly. See the Nava Platform infrastructure template for example configuration.
diff --git a/template/docs/{{app_name}}/lookbook.md b/template/docs/{{app_name}}/lookbook.md
@@ -0,0 +1,40 @@
+# Lookbook
+
+Lookbook is a tool for documenting and showcasing your application's components. It allows you to create a living style guide that can be shared with your team and stakeholders. It is particularly useful for frontend developers, designers, and product managers to see the components in action and understand how they can be used.
+
+## Enabling Lookbook
+
+To enable Lookbook in your application, you need to set the `ENABLE_LOOKBOOK` environment variable to `true`. Locally this can be done by adding the following line to your `.env` file:
+
+```env
+ENABLE_LOOKBOOK=true
+```
+
+If you are using the Nava Platform infrastructure template, you can enable Lookbook in the dev environment by adding the following code to `/infra/<APP_NAME>/app-config/dev.tf`:
+
+```terraform
+service_override_extra_environment_variables = {
+  ENABLE_LOOKBOOK = "true"
+}
+```
+
+## Creating Lookbook previews
+
+### Previewing partial components
+
+When creating Lookbook previews for Rails partial components, remember to do the following:
+
+1. Set the layout to `"component_preview"` to avoid rendering the application header and footer.
+2. In the render method call, specify the `template:` parameter explicitly, and include the underscore in front of the partial name. At the time of writing, Lookbook does not support rendering with `render "string"` or `render partial: "partial/name"`.
+
+Here's an example of a Lookbook preview that follows these guidelines:
+
+```ruby
+class ExamplePreview < Lookbook::Preview
+  layout "component_preview"
+
+  def default
+    render template: "application/_example", locals: {}
+  end
+end
+```
diff --git a/template/{{app_name}}/Gemfile b/template/{{app_name}}/Gemfile
@@ -71,6 +71,8 @@ gem "faraday"
 # Create fake data (outside of dev/test block to support seeding lower environments)
 gem "faker", "~> 3.2"
 
+gem "lookbook", ">= 2.3.9"
+
 group :development, :test do
   gem "guard-rspec", require: false
 
@@ -83,6 +85,10 @@ group :development, :test do
   # Testing framework
   gem "factory_bot_rails"
   gem "rspec-rails", "~> 6.1.0"
+
+  # Required by Lookbook
+  gem "listen"
+  gem "actioncable"
 end
 
 group :development do
diff --git a/template/{{app_name}}/Gemfile.lock b/template/{{app_name}}/Gemfile.lock
@@ -132,6 +132,8 @@ GEM
     concurrent-ruby (1.3.5)
     connection_pool (2.5.0)
     crass (1.0.6)
+    css_parser (1.21.1)
+      addressable
     cssbundling-rails (1.4.1)
       railties (>= 6.0.0)
     date (3.4.1)
@@ -191,6 +193,8 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
+    htmlbeautifier (1.4.3)
+    htmlentities (4.3.4)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     importmap-rails (2.1.0)
@@ -224,6 +228,18 @@ GEM
     loofah (2.24.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
+    lookbook (2.3.9)
+      activemodel
+      css_parser
+      htmlbeautifier (~> 1.3)
+      htmlentities (~> 4.3.4)
+      marcel (~> 1.0)
+      railties (>= 5.0)
+      redcarpet (~> 3.5)
+      rouge (>= 3.26, < 5.0)
+      view_component (>= 2.0)
+      yard (~> 0.9)
+      zeitwerk (~> 2.5)
     lumberjack (1.2.10)
     mail (2.8.1)
       mini_mime (>= 0.1.1)
@@ -351,13 +367,15 @@ GEM
       ffi (~> 1.0)
     rdoc (6.12.0)
       psych (>= 4.0.0)
+    redcarpet (3.6.1)
     regexp_parser (2.10.0)
     reline (0.6.0)
       io-console (~> 0.5)
     responders (3.1.1)
       actionpack (>= 5.2)
       railties (>= 5.2)
     rexml (3.4.1)
+    rouge (4.5.2)
     route_translator (14.2.0)
       actionpack (>= 6.1)
       activesupport (>= 6.1)
@@ -456,6 +474,10 @@ GEM
     unicode-emoji (4.0.4)
     uri (1.0.3)
     useragent (0.16.11)
+    view_component (3.21.0)
+      activesupport (>= 5.2.0, < 8.1)
+      concurrent-ruby (~> 1.0)
+      method_source (~> 1.0)
     warden (1.2.9)
       rack (>= 2.0.9)
     web-console (4.2.1)
@@ -470,6 +492,7 @@ GEM
     websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
+    yard (0.9.37)
     zeitwerk (2.7.2)
 
 PLATFORMS
@@ -489,6 +512,7 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  actioncable
   active_storage_validations
   aws-sdk-cognitoidentityprovider (~> 1.88)
   aws-sdk-rails
@@ -507,6 +531,8 @@ DEPENDENCIES
   jbuilder
   jwt
   letter_opener
+  listen
+  lookbook (>= 2.3.9)
   pg (~> 1.1)
   pg-aws_rds_iam (~> 0.7.0)
   puma (>= 5.0)
diff --git a/template/{{app_name}}/app/previews/breadcrumbs_preview.rb b/template/{{app_name}}/app/previews/breadcrumbs_preview.rb
@@ -0,0 +1,9 @@
+class BreadcrumbsPreview < Lookbook::Preview
+  layout "component_preview"
+
+  def default
+    render template: "application/_breadcrumbs", locals: { crumbs: [
+      { name: "Passport applications", url: "default" }
+      ], current_name: "New passport application" }
+  end
+end
diff --git a/template/{{app_name}}/app/views/application/_header.html.erb b/template/{{app_name}}/app/views/application/_header.html.erb
@@ -29,12 +29,12 @@
             <% end %>
 
           <li class="usa-nav__primary-item">
-            <%= render partial: "language-toggle", locals: { container_class: "display-block desktop:display-none relative" } %>
+            <%= render partial: "application/language-toggle", locals: { container_class: "display-block desktop:display-none relative" } %>
           </li>
         </ul>
       </div>
     </nav>
 
-    <%= render partial: "language-toggle", locals: { container_class: "usa-language-container display-none desktop:display-block" } %>
+    <%= render partial: "application/language-toggle", locals: { container_class: "usa-language-container display-none desktop:display-block" } %>
   </div>
-</header>
+</header>
diff --git a/template/{{app_name}}/app/views/layouts/application.html.erb b/template/{{app_name}}/app/views/layouts/application.html.erb
@@ -20,13 +20,13 @@
 
   <body>
     <div class="display-flex flex-column minh-viewport">
-      <%= render partial: 'header' %>
+      <%= render partial: 'application/header' %>
 
       <main id="main-content" class="grid-col-fill display-flex flex-column">
         <div class="grid-col-fill <%= yield :main_col_class %>">
           <section class="usa-section">
             <div class="grid-container">
-              <%= render partial: 'flash' %>
+              <%= render partial: 'application/flash' %>
 
               <div class="grid-row grid-gap">
                 <%= yield :before_content_col %>
diff --git a/template/{{app_name}}/app/views/layouts/component_preview.html.erb b/template/{{app_name}}/app/views/layouts/component_preview.html.erb
@@ -0,0 +1,24 @@
+<%# Layout for Lookbook previews of component partials %>
+<!DOCTYPE html>
+<html lang="<%= I18n.locale %>">
+  <head>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+    <%= javascript_importmap_tags %>
+    <%= javascript_include_tag '@uswds/uswds/dist/js/uswds-init.min.js' %>
+  </head>
+
+  <body>
+    <div class="display-flex flex-column minh-viewport">
+      <main id="main-content" class="grid-col-fill display-flex flex-column">
+        <div class="grid-col-fill <%= yield :main_col_class %>">
+          <div class="grid-container">
+            <%= content_for?(:content) ? yield(:content) : yield %>
+          </div>
+        </div>
+      </main>
+    </div>
+
+    <%= javascript_include_tag '@uswds/uswds/dist/js/uswds.min.js' %>
+  </body>
+</html>
diff --git a/template/{{app_name}}/config/initializers/lookbook.rb b/template/{{app_name}}/config/initializers/lookbook.rb
@@ -0,0 +1,3 @@
+Rails.application.configure do
+  config.lookbook.preview_paths = [ Rails.root.join("app", "previews") ]
+end
diff --git a/template/{{app_name}}/config/routes.rb b/template/{{app_name}}/config/routes.rb
@@ -7,6 +7,8 @@
   # Keep the default /up rails endpoint.
   get "up" => "rails/health#show"
 
+  mount Lookbook::Engine, at: "/lookbook" if ENV["ENABLE_LOOKBOOK"].present?
+
   # Support locale prefixes for these routes:
   localized do
     # Defines the root path route ("/")
diff --git a/template/{{app_name}}/local.env.example.jinja b/template/{{app_name}}/local.env.example.jinja
@@ -42,3 +42,9 @@ DB_HOST=127.0.0.1
 DB_NAME=app
 DB_USER=app
 DB_PASSWORD=secret123
+
+############################
+# Lookbook
+############################
+
+ENABLE_LOOKBOOK=true

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Rails.application.configure do`
	`2`	`+ config.lookbook.preview_paths = [ Rails.root.join("app", "previews") ]`
	`3`	`+end`