showcase-rails 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 151c0562d98ae25ac207acf0921c0f299fb60ca37ca325b6f2ccc117e32ed09b
-  data.tar.gz: 5d532b1992e910ff03a4e4bde0ae41c1e32d83c3e58a17be68378d0e6b6380a1
+  metadata.gz: 0c5d33100bd6414501e65b9739978d060032490a480bcf17cac74b689c556605
+  data.tar.gz: ac2cf1b91db211cce86ad10ac4b9acc9dbfd5c19a7d4fdda17e853b3e81ebade
 SHA512:
-  metadata.gz: 6c65a5683153a76fe6410ab0e4140b311100ea5843da37a056f3ae70f02a13565ee58e2f9624d07a8969f8676093a59eab30bdf69b6a2d9d06852b8ab9640d6a
-  data.tar.gz: 77d2f23c5f9a0871f14713d46637bb326d48b9caa8610cf50654f5da05092d062d3ba0dd03500678e0af1902573b6c79f8c12e8998cbcd6ae3aa313fbda5ec58
+  metadata.gz: 754d2bfcd10de161792834a56b470dc88652ac393429295d794e05b6c97b8da6a309af9aad284456742f34fde3faa6f7de50583f43f341178e2a0f22f13e314d
+  data.tar.gz: 2bb6891dd5236ce84728bb6c86db146de9724152f471b5e7f71fd1149941866572e9e2d5fd23e575e87019db5c62eb4597ef3807e28b3c20c33265cc896c479d

data/README.md

@@ -2,20 +2,32 @@
 
 Showcase lets you build previews for your partials, components, view helpers, Stimulus controllers and more — Rails engines included!
 
-Add a partial to `app/views/showcase/previews` and it'll show up in Showcase's menu. Here's how to showcase a standard button component:
+Add a partial to `app/views/showcase/previews` and it'll show up in Showcase's menu.
 
-```html
+| Light Mode | Dark Mode |
+| --- | --- |
+| ![](/readme/example-light.png?raw=true "Showcase showing a button component") | ![](/readme/example-dark.png?raw=true "Showcase showing a button component") |
+
+Each sample shows the render time in milliseconds and the allocation count so it's easier to spot if there's something different happening between your samples.
+
+## What can I showcase?
+
+### Rails partials
+
+Here's how to showcase a standard button component written with standard Rails partials:
+
+```erb
 <%# app/views/showcase/previews/components/_button.html.erb %>
 <% showcase.title "Button" %> <%# `title` is optional and inferred from the filename, by default. %>
 <% showcase.badge :partial, :component %> <%# Optional badges you can add to further clarify the type of the showcase. %>
 <% showcase.description "This button component handles what we click on" %>
 
 <% showcase.sample "Basic" do %>
-  <%= render "component/button", content: "Button content", mode: :small %>
+  <%= render "components/button", content: "Button content", mode: :small %>
 <% end %>
 
 <% showcase.sample "Large", description: "This is our larger button" do %>
-  <%= render "component/button", content: "Button content", mode: :large %>
+  <%= render "components/button", content: "Button content", mode: :large %>
 <% end %>
 
 <% showcase.options do |o| %>
@@ -24,70 +36,173 @@ Add a partial to `app/views/showcase/previews` and it'll show up in Showcase's m
 <% end %>
 ```
 
-Which will then render the following:
+### Components with ViewComponent
 
-| Light Mode | Dark Mode |
-| --- | --- |
-| ![](/readme/example-light.png?raw=true "Showcase showing a button component") | ![](/readme/example-dark.png?raw=true "Showcase showing a button component") |
+If we take the `MessageComponent` as seen on [https://viewcomponent.org](https://viewcomponent.org):
 
-Each sample shows the render time in milliseconds and the allocation count so it's easier to spot if there's something different happening between your samples.
+```ruby
+# app/components/message_component.rb
+class MessageComponent < ViewComponent::Base
+  def initialize(name:)
+    @name = name
+  end
+end
+```
 
-## Syntax Highlighting
+```erb
+<%# app/components/message_component.html.erb %>
+<h1>Hello, <%= @name %>!</h1>
+```
 
-To have out of the box syntax highlighting, add `gem "rouge"` to your Gemfile and Showcase will set it up. Any denoted syntaxes in your samples are then highlighted, e.g.
+We can showcase it just by rendering it:
 
 ```erb
-# app/views/showcase/previews/_plain_ruby.ruby
-<% showcase.sample "Basic", syntax: :ruby do %>
-  concat "hello".upcase
+<%# app/views/showcase/previews/components/_message_component.html.erb %>
+<% showcase.sample "Basic" do %>
+  <%= render MessageComponent.new(name: "World") %>
+<% end %>
+
+<% showcase.options do |o| %>
+  <% o.required :name, "The name to say hello to" %>
 <% end %>
 ```
 
-To change the default theme, look at [Loading your own syntax highlighting theme](#loading-your-own-syntax-highlighting-theme).
+### Components with Phlex
 
-To use a different syntax highlighter, you can assign your own Proc to `sample_renderer` like this:
+Given this [phlex-rails](https://www.phlex.fun/rails/) component:
 
 ```ruby
-# config/initializers/showcase.rb
-if defined?(Showcase)
-  Showcase.sample_renderer = ->(source, syntax) do
-    # Return a String of lexed and formatted code.
+# app/views/components/article.rb
+class Components::Article < Phlex::HTML
+  def initialize(article) = @article = article
+
+  def template
+    h1 { @article.title }
   end
 end
 ```
 
-## Using options contexts
+We can use Rails' `render` method to showcase it:
 
-Showcase also supports custom options contexts. They're useful for cases where the options have a very specific format and it would be nice to keep them standardized.
+```erb
+<%# app/views/showcase/previews/components/_article.html.erb %>
+<% showcase.sample "Basic" do %>
+  <%= render Components::Article.new(Article.first) %>
+<% end %>
+```
+
+### View helpers
+
+Any application helpers defined in `app/helpers` are automatically available in Showcase's engine, so given a helper like this:
+
+```ruby
+# app/helpers/upcase_helper.rb
+module UpcaseHelper
+  def upcase_string(string)
+    string.upcase
+  end
+end
+```
+
+You can showcase it like this:
+
+```erb
+<%# app/views/showcase/previews/helpers/_upcase_helper.html.erb %>
+<% showcase.sample "Basic" do %>
+  <%= upcase_string "hello" %>
+<% end %>
+```
+
+### JavaScript with Stimulus controllers
+
+Assuming we have a Stimulus controller like this:
+
+```javascript
+// app/assets/javascripts/controllers/welcome_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = [ "greeter" ]
+  static values = { yell: Boolean }
 
-By default, Showcase ships Nice Partials and Stimulus contexts out of the box. Here's a sample of the Stimulus one:
+  connect() {
+    let greeting = this.hasGreeterTarget ? `Welcome, ${this.greeterTarget.textContent}!` : "Welcome!"
+    if (this.yellValue) greeting = greeting.toUpperCase()
+
+    console.log(greeting)
+    this.dispatch("greeting", { detail: { greeting } })
+  }
+})
+```
+
+We can then render it to showcase it:
 
 ```erb
+<% showcase.description "The welcome controller says hello when it enters the screen" %>
+
+<% showcase.sample "Basic", events: "welcome:greeting" do %>
+  <div data-controller="welcome">I've just said welcome!</div>
+<% end %>
+
+<% showcase.sample "With greeter", events: "welcome:greeting" do %>
+  <div data-controller="welcome">
+    <div data-welcome-target="greeter">Somebody</div>
+  </div>
+<% end %>
+
+<% showcase.sample "Yelling!!!", events: "welcome:greeting" do %>
+  <div data-controller="welcome" data-welcome-yell-value="true">
+<% end %>
+
+<%# We're using the built-in Stimulus context here to output `data-` attributes correctly, and save some typing. %>
 <% showcase.options.context :stimulus, controller: :welcome do |o| %>
   <% o.optional.targets :greeter, "If the id of the target element must be printed" %>
+  <% o.required.values :yell, "Whether the hello is to be YELLED", default: false %>
+
+  <%# We support the other Stimulus declarations too: %>
+  <% o.required.classes :success, "The success class to append after greeting" %>
+  <% o.required.outlet :list, "An outlet to append each yelled greeter to" %>
+  <% o.optional.action :greet, "An action to repeat the greeting, if need be" %>
 <% end %>
 ```
 
-In case Showcase didn't ship with a Stimulus context, here's how you could add it:
+Note that by adding `events: "welcome:greeting"` we're listening for any time that event is dispatched. Events are logged with `console.log`, but also output alongside the sample in the browser.
+
+## Installation
+
+Add these lines to your application's Gemfile. See next section for why Showcase is in the test group.
 
 ```ruby
-# config/initializers/showcase.rb
-if defined?(Showcase)
-  Showcase.options.define :stimulus do
-    def targets(name, ...)
-      option(%(data-#{@controller}-target="#{name}"), ...)
-    end
-  end
+group :development, :test do
+  gem "showcase-rails"
+  gem "rouge" # Optional. For out-of-the-box syntax highlighting.
 end
 ```
 
-## Automatic previews testing
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install showcase-rails
+```
+
+Then add the following in your `config/routes.rb` within the block passed to `Rails.application.routes.draw`:
 
-Showcase can automatically generate tests for all your Showcases to have it executed in your CI setup, run `bin/rails showcase:install:previews_test` to set this up.
+```ruby
+mount Showcase::Engine, at: "/docs/showcase" if defined?(Showcase::Engine)
+```
 
- You can then open `test/views/showcase_test.rb` and add your own `setup` and `teardown` hooks, as well as override the provided `assert_showcase_preview` to add custom assertions.
+### Automatic previews testing
 
-If you need custom assertions for specific previews and their samples, you can use the `test` helper:
+To have Showcase generate tests to exercise all your previews on CI, run `bin/rails showcase:install:previews_test` to add `test/views/showcase_test.rb`.
+
+ There you can add `setup` and `teardown` hooks, plus override the provided `assert_showcase_preview` to add custom assertions for any preview.
+
+If you need custom assertions for specific previews, you can use the `test` helper:
 
 ```ruby
 # test/views/showcase_test.rb
@@ -111,7 +226,78 @@ class ShowcaseTest < Showcase::PreviewsTest
 end
 ```
 
-## Linking to previews
+### Syntax Highlighting
+
+Add `gem "rouge"` to your Gemfile and Showcase will set syntax highlighting up for you. Any denoted syntaxes in your samples are then highlighted, e.g.:
+
+```erb
+# app/views/showcase/previews/_plain_ruby.ruby
+<% showcase.sample "Basic", syntax: :ruby do %>
+  concat "hello".upcase
+<% end %>
+```
+
+By default, `syntax: :erb` is used, so you don't need to mark the majority of your samples.
+
+#### Replacing the highlighter
+
+To use a different syntax highlighter, assign your own Proc to `sample_renderer` like this:
+
+```ruby
+# config/initializers/showcase.rb
+return unless defined?(Showcase)
+
+Showcase.sample_renderer = ->(source, syntax) do
+  # Return a String of lexed and formatted code.
+end
+```
+
+#### Replacing the theme
+
+By default, Showcase's syntax highlighting runs on Rouge's `"github"` theme.
+
+To use a different theme, override [showcase/engine/_stylesheets.html.erb](app/views/showcase/engine/_stylesheets.html.erb) with the following, replacing `:magritte` with a [valid theme](rouge-themes):
+
+```erb
+<%= stylesheet_link_tag "showcase" %> <%# We've removed the default showcase.highlights file here. %>
+<%= tag.style Rouge::Theme.find(:magritte).render(scope: ".sc-highlight") %>
+```
+
+[rouge-themes]: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
+
+## Taking Showcase further
+
+### View examples
+
+Clone the repository, run `bundle install`, then run `bin/rails server`, and visit localhost:3000 in your browser. You'll see the examples from [test/dummy/app/views/showcase/previews](test/dummy/app/views/showcase/previews).
+
+### Configuring what trees to open
+
+Showcase's sidebar mirrors your `app/views/showcase/previews` directory with their paths, and then trees at each directory level.
+
+So a `showcase/previews` directory with `_top_level.html.erb`, `components/_button.html.erb`, `deeply/nested/_partial.html.erb`, will generate a sidebar like this:
+
+- Previews
+  - Top Level
+- Components
+  - Button
+- Deeply
+  - Nested
+    - Partial
+
+Internally, Showcase renders an open `details` element for each tree. You can control that with this:
+
+```ruby
+# config/initializers/showcase.rb
+return unless defined?(Showcase)
+
+Showcase.tree_opens = true  # All trees are open (the default).
+Showcase.tree_opens = false # All trees are closed.
+Showcase.tree_opens = ->(tree) { tree.root? } # Only open the root level trees (Previews, Components, Deeply but not Nested).
+Showcase.tree_opens = ->(tree) { tree.id.start_with? ".", "components" } # Just open the top-level tree and the components tree.
+```
+
+### Linking to previews
 
 Call `showcase.link_to` with the URL path to the other Showcase:
 
@@ -123,7 +309,34 @@ Call `showcase.link_to` with the URL path to the other Showcase:
 <%= showcase.link_to id: "extra-large" %>
 ```
 
-## Full Rails engine support
+### Adding options contexts
+
+Showcase also supports custom options contexts. They're useful for cases where the options have a very specific format and it would be nice to keep them standardized.
+
+By default, Showcase ships Nice Partials and Stimulus contexts out of the box. See [lib/showcase.rb](lib/showcase.rb) for how they're defined.
+
+To add a new context, you can do this:
+
+```ruby
+# config/initializers/showcase.rb
+return unless defined?(Showcase)
+
+Showcase.options.define :some_context do
+  def targets(name, ...)
+    option("data-#{@prefix}-#{name}", ...)
+  end
+end
+```
+
+And now we can use it, here passing in `prefix:` which becomes an instance variable available in the `define` block.
+
+```erb
+<% showcase.options.context :some_context, prefix: "super-" do |o| %>
+  <% o.required.targets :title %>
+<% end %>
+```
+
+### Full Rails engine support
 
 Any Rails engines in your app that ships previews in their `app/views/showcase/previews` directory will automatically be surfaced in your app. Here's an example from the [bullet_train-themes-light Rails engine](https://github.com/bullet-train-co/bullet_train-core/tree/main/bullet_train-themes-light/app/views/showcase/previews).
 
@@ -131,11 +344,7 @@ Showcase respects the Rails views rendering order, allowing you to override a sp
 
 _📖 How does this work? 📖_ Internally, Showcase leverages Rails controllers' ordered set of `view_paths` — which each engine automatically prepends their app/views directory to by calling something like [`ActionController::Base.prepend_view_path`](https://github.com/rails/rails/blob/e78ed07e008676752b2ed2cff97e74b31ffacaf5/railties/lib/rails/engine.rb#L606) when initializing.
 
-## View examples
-
-Clone the repository, run `bundle install`, then run `bin/rails server`, visit localhost:3000 in your browser.
-
-## Overriding Showcase's default rendering
+### Overriding Showcase's default rendering
 
 Showcase's rendering happens through two controllers:
 
@@ -179,48 +388,9 @@ partials, make sure to include `"showcase"` in your list of assets.
 
 [javascript_include_tag]: https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-javascript_include_tag
 [stylesheet_link_tag]: https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-stylesheet_link_tag
-[showcase/engine/_head.html.erb]: ./showcase/engine/_head.html.erb
-[showcase/engine/_javascripts.html.erb]: ./showcase/engine/_javascripts.html.erb
-[showcase/engine/_stylesheets.html.erb]: ./showcase/engine/_stylesheets.html.erb
-
-### Loading your own syntax highlighting theme
-
-By default, Showcase's syntax highlighting runs on Rouge's "github" theme.
-
-To use a different theme, override [showcase/engine/_stylesheets.html.erb][] with the following, replacing `:magritte` with a [valid theme](rouge-themes):
-
-```erb
-<%= stylesheet_link_tag "showcase" %> # We've removed the default showcase.highlights file here.
-<%= tag.style Rouge::Theme.find(:magritte).render(scope: ".sc-highlight") %>
-```
-
-[rouge-themes]: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
-
-## Installation
-
-Add this line to your application's Gemfile. To get the previews testing make sure the `showcase-rails` gem is available to your test environment:
-
-```ruby
-group :development, :test do
-  gem "showcase-rails"
-end
-```
-
-And then execute:
-```bash
-$ bundle
-```
-
-Or install it yourself as:
-```bash
-$ gem install showcase-rails
-```
-
-Then add the following in your `config/routes.rb` within the block passed to `Rails.application.routes.draw`:
-
-```ruby
-mount Showcase::Engine, at: "/docs/showcase" if defined?(Showcase::Engine)
-```
+[showcase/engine/_head.html.erb]: app/views/showcase/engine/_head.html.erb
+[showcase/engine/_javascripts.html.erb]: app/views/showcase/engine/_javascripts.html.erb
+[showcase/engine/_stylesheets.html.erb]: app/views/showcase/engine/_stylesheets.html.erb
 
 ## Contributing
 Contribution directions go here.