showcase-rails 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bf404f8262fdae51c6ab3541595e310d63777b55f20125d41240565e77c147f
-  data.tar.gz: 145c8eb4f5c2f90ae15946d277fd444d0c8c3c6cd3f18357daa004391ec3ecf7
+  metadata.gz: 29e0e0059cf53cd0d451d1f5018bee11ee70957dbe6c01bd286cfc38647922c1
+  data.tar.gz: fa52f4fb277dd3236fa8f831d6ab124094206dbcc5b7b88b84f5717ec82dd349
 SHA512:
-  metadata.gz: a95d16e34f3e0c500356c38217a0e859e1963635c4b0ae14262c5d293c0c11e43063f2e6457b2a698b554351d847c8372885194edfd66c3885e2169978c404e1
-  data.tar.gz: 2584d6cab57b362d6a685f0b2268f8dbe02135dac6919628780d9de1a5d21fd3a865aae08a67155f309638291b3d474c50017ec15530668721be77fd8960c75f
+  metadata.gz: f6c4dea89446707034687d3677bf9960fccb8aacec4ddec9a7827ee1e7979fe6c48b987cb7e82858ca7ec32b03cb2194c5aba6d68603f271fd44efe204a91cd8
+  data.tar.gz: b14391d1b133b50b11c396cdc076041dd0a8791141191233736c475db2d617701504a37e85dd5799da77bd5a960ecd2ae6706fe8578f7bdac8976030a5fe21df

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,14 @@ class Showcase::Path
       id == "." ? "Previews" : id
     end
 
+    def open?
+      Showcase.tree_opens.call(self)
+    end
+
+    def active?(id)
+      children.any? { _1.active?(id) }
+    end
+
     def ordered_children
       children.partition { !_1.is_a?(Tree) }.flatten
     end
@@ -58,6 +66,10 @@ class Showcase::Path
   cached_partial_path = "showcase/engine/path/path"
   define_method(:to_partial_path) { cached_partial_path }
 
+  def active?(id)
+    self.id == id
+  end
+
   def preview_for(view_context)
     Showcase::Preview.new(view_context, id: id, title: basename.titleize).tap(&:render_associated_partial)
   end

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

@@ -1,3 +1,3 @@
-<article class="hover:sc-bg-indigo-50 dark:hover:sc-bg-neutral-700/50 <%= "sc-bg-indigo-50 dark:sc-bg-neutral-700/50" if path.id == params[:id] %>">
+<article class="hover:sc-bg-indigo-50 dark:hover:sc-bg-neutral-700/50 <%= "sc-bg-indigo-50 dark:sc-bg-neutral-700/50" if path.active? params[:id] %>">
   <%= link_to path.basename.titleize, preview_path(path.id), class: "sc-inline-block sc-py-2 sc-px-8 sc-w-full !sc-text-inherit !sc-no-underline" %>
 </article>

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.active?(params[:id]) || 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.2"
 end

data/lib/showcase.rb

@@ -12,6 +12,13 @@ module Showcase
   autoload :RouteHelper,  "showcase/route_helper"
   autoload :Options,      "showcase/options"
 
+  singleton_class.attr_reader :tree_opens
+
+  def self.tree_opens=(opens)
+    @tree_opens = opens.respond_to?(:call) ? opens : proc { opens }
+  end
+  self.tree_opens = true # All open by default
+
   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.2
 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