showcase-rails 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bf404f8262fdae51c6ab3541595e310d63777b55f20125d41240565e77c147f
-  data.tar.gz: 145c8eb4f5c2f90ae15946d277fd444d0c8c3c6cd3f18357daa004391ec3ecf7
+  metadata.gz: 0c5d33100bd6414501e65b9739978d060032490a480bcf17cac74b689c556605
+  data.tar.gz: ac2cf1b91db211cce86ad10ac4b9acc9dbfd5c19a7d4fdda17e853b3e81ebade
 SHA512:
-  metadata.gz: a95d16e34f3e0c500356c38217a0e859e1963635c4b0ae14262c5d293c0c11e43063f2e6457b2a698b554351d847c8372885194edfd66c3885e2169978c404e1
-  data.tar.gz: 2584d6cab57b362d6a685f0b2268f8dbe02135dac6919628780d9de1a5d21fd3a865aae08a67155f309638291b3d474c50017ec15530668721be77fd8960c75f
+  metadata.gz: 754d2bfcd10de161792834a56b470dc88652ac393429295d794e05b6c97b8da6a309af9aad284456742f34fde3faa6f7de50583f43f341178e2a0f22f13e314d
+  data.tar.gz: 2bb6891dd5236ce84728bb6c86db146de9724152f471b5e7f71fd1149941866572e9e2d5fd23e575e87019db5c62eb4597ef3807e28b3c20c33265cc896c479d

data/README.md

@@ -38,7 +38,7 @@ Here's how to showcase a standard button component written with standard Rails p
 
 ### Components with ViewComponent
 
-If we take the `MessageComponent` as seen on [https://viewcomponent.org]():
+If we take the `MessageComponent` as seen on [https://viewcomponent.org](https://viewcomponent.org):
 
 ```ruby
 # app/components/message_component.rb
@@ -168,9 +168,67 @@ We can then render it to showcase 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.
 
-## Syntax Highlighting
+## Installation
+
+Add these lines to your application's Gemfile. See next section for why Showcase is in the test group.
+
+```ruby
+group :development, :test do
+  gem "showcase-rails"
+  gem "rouge" # Optional. For out-of-the-box syntax highlighting.
+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)
+```
+
+### Automatic previews testing
+
+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
+require "test_helper"
+
+class ShowcaseTest < Showcase::PreviewsTest
+  test showcase: "combobox" do
+    # This test block runs within the #combobox container element.
+    assert_text "This is a combobox, for sure."
+  end
+
+  test showcase: "button" do
+    assert_selector id: "basic" do
+      assert_button class: ["text-xs"]
+    end
+  end
 
-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.
+  test "some non-Showcase test" do
+    # You can still use the regular Rails `test` method too.
+  end
+end
+```
+
+### 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
@@ -179,102 +237,106 @@ To have out of the box syntax highlighting, add `gem "rouge"` to your Gemfile an
 <% end %>
 ```
 
-To change the default theme, look at [Loading your own syntax highlighting theme](#loading-your-own-syntax-highlighting-theme).
+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, you can assign your own Proc to `sample_renderer` like this:
+To use a different syntax highlighter, assign your own Proc to `sample_renderer` like this:
 
 ```ruby
 # config/initializers/showcase.rb
-if defined?(Showcase)
-  Showcase.sample_renderer = ->(source, syntax) do
-    # Return a String of lexed and formatted code.
-  end
+return unless defined?(Showcase)
+
+Showcase.sample_renderer = ->(source, syntax) do
+  # Return a String of lexed and formatted code.
 end
 ```
 
-### Loading your own syntax highlighting theme
+#### Replacing the theme
 
-By default, Showcase's syntax highlighting runs on Rouge's "github" 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):
+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.
+<%= 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
 
-## Using options contexts
+## Taking Showcase further
 
-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.
+### View examples
 
-By default, Showcase ships Nice Partials and Stimulus contexts out of the box. See [lib/showcase.rb][] for how they're defined.
+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).
 
-To add a new context, you can do this:
+### 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.options.define :some_context do
-  def targets(name, ...)
-    option("data-#{@prefix}-#{name}", ...)
-  end
-end
+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.
 ```
 
-And now we can use it, here passing in `prefix:` which becomes an instance variable available in the `define` block.
+### Linking to previews
+
+Call `showcase.link_to` with the URL path to the other Showcase:
 
 ```erb
-<% showcase.options.context :some_context, prefix: "super-" do |o| %>
-  <% o.required.targets :title %>
-<% end %>
+<%= showcase.link_to "stimulus_controllers/welcome" %>
+<%= showcase.link_to "components/button", id: "extra-large" %> <%# Pass an id to link to a specific sample %>
+
+<%# You can also pass just an id: to target a sample on the current showcase %>
+<%= showcase.link_to id: "extra-large" %>
 ```
 
-## Automatic previews testing
+### Adding options contexts
 
-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.
+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.
 
- 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.
+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.
 
-If you need custom assertions for specific previews and their samples, you can use the `test` helper:
+To add a new context, you can do this:
 
 ```ruby
-# test/views/showcase_test.rb
-require "test_helper"
-
-class ShowcaseTest < Showcase::PreviewsTest
-  test showcase: "combobox" do
-    # This test block runs within the #combobox container element.
-    assert_text "This is a combobox, for sure."
-  end
-
-  test showcase: "button" do
-    assert_selector id: "basic" do
-      assert_button class: ["text-xs"]
-    end
-  end
+# config/initializers/showcase.rb
+return unless defined?(Showcase)
 
-  test "some non-Showcase test" do
-    # You can still use the regular Rails `test` method too.
+Showcase.options.define :some_context do
+  def targets(name, ...)
+    option("data-#{@prefix}-#{name}", ...)
   end
 end
 ```
 
-## Linking to previews
-
-Call `showcase.link_to` with the URL path to the other Showcase:
+And now we can use it, here passing in `prefix:` which becomes an instance variable available in the `define` block.
 
 ```erb
-<%= showcase.link_to "stimulus_controllers/welcome" %>
-<%= showcase.link_to "components/button", id: "extra-large" %> <%# Pass an id to link to a specific sample %>
-
-<%# You can also pass just an id: to target a sample on the current showcase %>
-<%= showcase.link_to id: "extra-large" %>
+<% showcase.options.context :some_context, prefix: "super-" do |o| %>
+  <% o.required.targets :title %>
+<% end %>
 ```
 
-## Full Rails engine support
+### 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).
 
@@ -282,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:
 
@@ -330,36 +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
-
-## 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"
-  gem "rouge" # For syntax highlighting in Showcase.
-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.

data/app/models/showcase/path.rb

@@ -13,6 +13,10 @@ class Showcase::Path
       id == "." ? "Previews" : id
     end
 
+    def open?
+      Showcase.tree_opens.call(self)
+    end
+
     def ordered_children
       children.partition { !_1.is_a?(Tree) }.flatten
     end

data/app/views/showcase/engine/path/_tree.html.erb

@@ -1,4 +1,4 @@
-<details open class="sc-flex sc-flex-col <%= "sc-pl-4" unless tree.root? %>">
+<%= tag.details open: tree.open?, class: ["sc-flex sc-flex-col", "sc-pl-4" => !tree.root?] do %>
   <%= tag.summary tree.name.titleize, class: "sc-list-item hover:sc-bg-indigo-50 dark:hover:sc-bg-neutral-700/50 sc-font-medium sc-text-base sc-py-2 sc-pl-4 sc-cursor-pointer" %>
   <%= render tree.ordered_children %>
-</details>
+<% end %>

data/lib/showcase/version.rb

@@ -1,3 +1,3 @@
 module Showcase
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/lib/showcase.rb

@@ -12,6 +12,17 @@ module Showcase
   autoload :RouteHelper,  "showcase/route_helper"
   autoload :Options,      "showcase/options"
 
+  class << self
+    attr_reader :tree_opens
+
+    def tree_opens=(opens)
+      @tree_opens = opens.respond_to?(:call) ? opens : proc { opens }
+    end
+  end
+  self.tree_opens = true # All open by default
+  # self.tree_opens = false # All closed by default
+  # self.tree_opens = ->(tree) { tree.root? } # Just keep the root-level trees open.
+
   singleton_class.attr_accessor :sample_renderer
   @sample_renderer = proc { _1 }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: showcase-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Daniel Pence
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-28 00:00:00.000000000 Z
+date: 2023-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails