showcase-rails 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf778403a9352a0351175e44992b887820d5336c211e2d3dcfa6975b27240bf3
-  data.tar.gz: aea48794945648e9681c3fa345d5503b99aebb81f4c49d6e527bbc13f38f7da6
+  metadata.gz: 616178a6d44d9d2a3da1d3e501d65fcd15375b89d87c1ec25dff13f58dba3f4a
+  data.tar.gz: 9f2c3e39bda86712762003630c92796967f5b30f6d87102c72cb69fbd905580d
 SHA512:
-  metadata.gz: e44e0daed1d4d76efacfd3f261a815ff5a5920335baf2318adea7a72f307c02d45b923905ceca8e6c0d45f179eba3761f7151ed06679a0075cc686fa73f8b6f2
-  data.tar.gz: 845ffb9426a6d1de5892cad9cad0a0bffd06d54a238767115d37f7c68d3643aa6e6eaa4c6308106b7cd071014e0be7faeb52e2d89952b66b5dc841a2df0823cf
+  metadata.gz: 0c47ba2bdb23a3173b3c4460387423338b02096b2b3fdd9cba9114f2bc429d39bae6c4a7c010991c7659294e6ab9508c663112701cca3450a4005e84a3282ee1
+  data.tar.gz: 575cb0f98daab6bfe9353d2faf3e5356756f7a67e8158ac16fd59bf5479ad50d2b4260a106b72c0bf27136531f01058200c9bbdf62114b7e84fe8b1e9ae20c51

data/README.md

@@ -1,21 +1,20 @@
 # Showcase
 
-Showcase lets you build previews for your partials, components, view helpers, Stimulus controllers and more.
+Showcase lets you build previews for your partials, components, view helpers, Stimulus controllers and more — Rails engines included!
 
-Add a template to `app/views/showcase/previews` and it'll show up in Showcase's menu.
+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:
 
-Here's how to showcase a standard button component:
-
-```erb
-<%# app/views/showcase/previews/_button.html.erb %>
+```html
+<%# 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 %>
 <% end %>
 
-<% showcase.sample "Large" do %>
+<% showcase.sample "Large", description: "This is our larger button" do %>
   <%= render "component/button", content: "Button content", mode: :large %>
 <% end %>
 
@@ -27,7 +26,35 @@ Here's how to showcase a standard button component:
 
 Which will then render the following:
 
-![](/readme/example.png?raw=true "Showcase showing a button component")
+| 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.
+
+## Syntax Highlighting
+
+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.
+
+```erb
+# app/views/showcase/previews/_plain_ruby.ruby
+<% showcase.sample "Basic", syntax: :ruby do %>
+  concat "hello".upcase
+<% end %>
+```
+
+To change the default theme, look at [Loading your own syntax highlighting theme](#loading-your-own-syntax-highlighting-theme).
+
+To use a different syntax highlighter, you can 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
+end
+```
 
 ## Using options contexts
 
@@ -36,7 +63,7 @@ Showcase also supports custom options contexts. They're useful for cases where t
 By default, Showcase ships Nice Partials and Stimulus contexts out of the box. Here's a sample of the Stimulus one:
 
 ```erb
-<% showcase.options.stimulus controller: :welcome do |o| %>
+<% showcase.options.context :stimulus, controller: :welcome do |o| %>
   <% o.optional.targets :greeter, "If the id of the target element must be printed" %>
 <% end %>
 ```
@@ -83,6 +110,14 @@ class ShowcaseTest < Showcase::PreviewsTest
 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).
+
+Showcase respects the Rails views rendering order, allowing you to override a specific preview. So if an engine ships an `app/views/showcase/previews/partials/_alert.html.erb` preview, you can copy that to the same path in your app and tailor it to suit your app's documentation needs. Showcase will then show your override instead of the engine's original.
+
+_📖 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.
@@ -122,23 +157,27 @@ Showcase bundles its own `showcase.js`, `showcase.css` and `showcase.highlights.
 Action View's [javascript_include_tag][] and [stylesheet_link_tag][].
 
 If your assets require more sophisticated loading techniques, declare your own
-versions of the [showcase/engine/_javascripts.html.erb][] and
+version of the [showcase/engine/_head.html.erb][] partial.
+
+If you need to tweak showcase's assets, declare your own versions of
+the [showcase/engine/_javascripts.html.erb][] and
 [showcase/engine/_stylesheets.html.erb][] partials. When customizing those
 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
+### 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 "application", "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") %>
 ```
 
@@ -146,7 +185,7 @@ To use a different theme, override [showcase/engine/_stylesheets.html.erb][] wit
 
 ## Installation
 
-Add this line to your application's Gemfile. To get the automatic integration testing make sure the `showcase-rails` gem is available to your test environment:
+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

data/app/assets/builds/showcase.css

@@ -727,10 +727,6 @@ select {
   height: 100%;
 }
 
-.sc-max-h-20 {
-  max-height: 5rem;
-}
-
 .sc-min-h-screen {
   min-height: 100vh;
 }
@@ -826,6 +822,16 @@ select {
   border-radius: 0.375rem;
 }
 
+.sc-rounded-b-md {
+  border-bottom-right-radius: 0.375rem;
+  border-bottom-left-radius: 0.375rem;
+}
+
+.sc-rounded-t-md {
+  border-top-left-radius: 0.375rem;
+  border-top-right-radius: 0.375rem;
+}
+
 .sc-border {
   border-width: 1px;
 }
@@ -964,9 +970,8 @@ select {
   line-height: 1.375;
 }
 
-.sc-text-black {
-  --tw-text-opacity: 1;
-  color: rgb(0 0 0 / var(--tw-text-opacity));
+.sc-text-inherit {
+  color: inherit;
 }
 
 .sc-text-slate-500 {
@@ -974,6 +979,10 @@ select {
   color: rgb(100 116 139 / var(--tw-text-opacity));
 }
 
+.sc-no-underline {
+  text-decoration-line: none;
+}
+
 .hover\:sc-select-all:hover {
   -webkit-user-select: all;
      -moz-user-select: all;
@@ -985,12 +994,33 @@ select {
   background-color: rgb(238 242 255 / var(--tw-bg-opacity));
 }
 
-.hover\:sc-text-inherit:hover {
-  color: inherit;
-}
+@media (prefers-color-scheme: dark) {
+  .dark\:sc-bg-neutral-700\/50 {
+    background-color: rgb(64 64 64 / 0.5);
+  }
 
-.hover\:sc-no-underline:hover {
-  text-decoration-line: none;
+  .dark\:sc-bg-neutral-800 {
+    --tw-bg-opacity: 1;
+    background-color: rgb(38 38 38 / var(--tw-bg-opacity));
+  }
+
+  .dark\:sc-bg-neutral-900 {
+    --tw-bg-opacity: 1;
+    background-color: rgb(23 23 23 / var(--tw-bg-opacity));
+  }
+
+  .dark\:sc-text-inherit {
+    color: inherit;
+  }
+
+  .dark\:sc-text-white {
+    --tw-text-opacity: 1;
+    color: rgb(255 255 255 / var(--tw-text-opacity));
+  }
+
+  .dark\:hover\:sc-bg-neutral-700\/50:hover {
+    background-color: rgb(64 64 64 / 0.5);
+  }
 }
 
 @media (min-width: 768px) {

data/app/views/layouts/showcase.html.erb

@@ -4,6 +4,7 @@
     <title>Showcase</title>
     <meta name="viewport" content="width=device-width,initial-scale=1">
 
+    <%= render "showcase/engine/head" %>
     <%= render "showcase/engine/stylesheets" %>
     <%= render "showcase/engine/javascripts" %>
   </head>

data/app/views/showcase/engine/_head.html.erb

@@ -0,0 +1,2 @@
+<%= stylesheet_link_tag "application" %>
+<%= javascript_include_tag "application" %>

data/app/views/showcase/engine/_javascripts.html.erb

@@ -1 +1 @@
-<%= javascript_include_tag "application", "showcase" %>
+<%= javascript_include_tag "showcase" %>

data/app/views/showcase/engine/_options.html.erb

@@ -3,7 +3,7 @@
 
   <table class="sc-table sc-border-collapse sc-border sc-border-gray-200">
     <thead>
-      <tr class="sc-bg-slate-50">
+      <tr class="sc-bg-slate-50 dark:sc-bg-neutral-800">
         <% options.headers.each do |header| %>
           <th class="sc-px-4 sc-py-2"><%= header.to_s.humanize %></th>
         <% end %>

data/app/views/showcase/engine/_root.html.erb

@@ -1,4 +1,4 @@
-<main class="sc-flex sc-flex-wrap" aria-labelledby="showcase_main_title">
+<main class="sc-flex sc-flex-wrap dark:sc-bg-neutral-900 dark:sc-text-white" aria-labelledby="showcase_main_title">
   <section class="sc-grid sc-grid-cols-12 sc-w-full">
     <nav class="sc-col-span-3 xl:sc-col-span-2 sc-py-5 sc-h-full sc-border-r">
       <h1 id="showcase_main_title" class="sc-font-black sc-text-2xl sc-py-2 sc-pl-4 sc-cursor-pointer"><%= link_to "Showcase", root_url %></h1>

data/app/views/showcase/engine/_sample.html.erb

@@ -1,11 +1,11 @@
 <section class="sc-mb-4 sc-border sc-border-gray-200 sc-rounded-md" aria-labelledby="showcase_<%= sample.id %>_title">
   <showcase-sample id="<%= sample.id %>" events="<%= sample.events %>">
-    <header class="sc-bg-slate-100/50">
+    <header class="sc-bg-slate-100/50 dark:sc-bg-neutral-700/50 sc-rounded-t-md">
       <div class="sc-flex sc-justify-between">
         <h3 id="showcase_<%= sample.id %>_title" class="sc-px-4 sc-py-2 sc-font-medium sc-text-base md:sc-text-lg sc-leading-snug sc-truncate"><%= link_to sample.name, "##{sample.id}" %></h3>
 
         <% if event = sample.instrumented %>
-          <div class="sc-text-xs sc-grid sc-gap-x-2 sc-m-2 sc-italic sc-text-slate-500">
+          <div class="sc-text-xs sc-grid sc-gap-x-2 sc-m-2 sc-italic sc-text-slate-500 dark:sc-text-inherit">
             <span><%= event.duration.round(1) %>ms</span>
             <span><%= event.allocations %> allocs</span>
           </div>
@@ -25,7 +25,7 @@
 
     <% if sample.source %>
       <details>
-        <summary class="sc-px-4 sc-py-2 hover:sc-bg-indigo-50 sc-cursor-pointer sc-select-none">View Source</summary>
+        <summary class="sc-px-4 sc-py-2 hover:sc-bg-indigo-50 dark:hover:sc-bg-neutral-700/50 sc-cursor-pointer sc-select-none">View Source</summary>
 
         <section class="sc-highlight sc-px-4 sc-py-2 sc-relative sc-overflow-y-auto hover:sc-select-all">
           <pre><%= sample.source %></pre>
@@ -34,10 +34,10 @@
     <% end %>
 
     <% if sample.events.any? %>
-      <section class="sc-px-4 sc-py-2 sc-font-small sc-bg-slate-50" aria-labelledby="showcase_<%= sample.id %>_javascript_events_title">
+      <section class="sc-px-4 sc-py-2 sc-font-small sc-bg-slate-50 dark:sc-bg-neutral-800 sc-rounded-b-md" aria-labelledby="showcase_<%= sample.id %>_javascript_events_title">
         <h4 id="showcase_<%= sample.id %>_javascript_events_title" class="sc-mb-2 sc-font-medium sc-text-base">JavaScript Events</h4>
 
-        <div class="sc-overflow-scroll sc-max-h-20">
+        <div class="sc-overflow-scroll sc-max-h-50">
           <pre data-showcase-sample-target="relay"></pre>
         </div>
       </section>

data/app/views/showcase/engine/_stylesheets.html.erb

@@ -1 +1 @@
-<%= stylesheet_link_tag "application", "showcase", "showcase.highlights" %>
+<%= stylesheet_link_tag "showcase", "showcase.highlights" %>

data/app/views/showcase/engine/index.html.erb

@@ -25,6 +25,9 @@
   <section class="sc-space-y-4">
     <h2 class="sc-font-semibold sc-text-2xl">Additional resources</h2>
     <ul class="sc-list-none">
+      <li>
+        <%= link_to "Showcase documentation", "https://github.com/bullet-train-co/showcase", target: "_blank" %>
+      </li>
       <li>
         <%= link_to "Bullet Train field partials documentation", "https://bullettrain.co/docs/field-partials", target: "_blank" %>
       </li>

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

@@ -1,3 +1,3 @@
-<article class="hover:sc-bg-indigo-50 <%= "sc-bg-indigo-50" if path.id == params[:id] %>">
-  <%= link_to path.basename.titleize, preview_path(path.id), class: "sc-inline-block sc-py-2 sc-px-8 sc-w-full hover:sc-text-inherit hover:sc-no-underline" %>
+<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] %>">
+  <%= 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.summary tree.name.titleize, class: "hover:sc-bg-indigo-50 sc-font-medium sc-text-black sc-text-base sc-py-2 sc-pl-4 sc-cursor-pointer" %>
+  <%= tag.summary tree.name.titleize, class: "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>

data/lib/showcase/version.rb

@@ -1,3 +1,3 @@
 module Showcase
-  VERSION = "0.2.5"
+  VERSION = "0.2.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: showcase-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - Daniel Pence
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-01 00:00:00.000000000 Z
+date: 2023-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -59,6 +59,7 @@ files:
 - app/models/showcase/preview.rb
 - app/models/showcase/sample.rb
 - app/views/layouts/showcase.html.erb
+- app/views/showcase/engine/_head.html.erb
 - app/views/showcase/engine/_javascripts.html.erb
 - app/views/showcase/engine/_options.html.erb
 - app/views/showcase/engine/_preview.html.erb
@@ -101,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.4.8
 signing_key:
 specification_version: 4
 summary: Showcase helps you show off and document your partials, components, view