showcase-rails 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf778403a9352a0351175e44992b887820d5336c211e2d3dcfa6975b27240bf3
-  data.tar.gz: aea48794945648e9681c3fa345d5503b99aebb81f4c49d6e527bbc13f38f7da6
+  metadata.gz: bd1db6d9dffe2f19513565919b1e09a1fbd3cccec37917a18ab9e8dbf7791d82
+  data.tar.gz: '08b4a1d6b175dd140189dc3630532559fd3cbb3579b6e3c831a1f86aae5ea293'
 SHA512:
-  metadata.gz: e44e0daed1d4d76efacfd3f261a815ff5a5920335baf2318adea7a72f307c02d45b923905ceca8e6c0d45f179eba3761f7151ed06679a0075cc686fa73f8b6f2
-  data.tar.gz: 845ffb9426a6d1de5892cad9cad0a0bffd06d54a238767115d37f7c68d3643aa6e6eaa4c6308106b7cd071014e0be7faeb52e2d89952b66b5dc841a2df0823cf
+  metadata.gz: ca31f6b03f53ee05c2e5485cfbe0f1507c05c7d26f49e2fd75cec29695c897297bbccb149ff019c585d87a339515090a462f192ec3f81a9cf6eb57e51fed5755
+  data.tar.gz: 31e021098a8a43ad19a8bd3372ed5257dcc37449152a0d265097c62517a476f6a552b8f93db8da9c3d738367d8bb2629ea6759d8d61b461b8cff0e9535156e3a

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.
@@ -131,7 +166,7 @@ partials, make sure to include `"showcase"` in your list of assets.
 [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.
 
@@ -146,7 +181,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

@@ -826,6 +826,11 @@ select {
   border-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,11 +969,6 @@ select {
   line-height: 1.375;
 }
 
-.sc-text-black {
-  --tw-text-opacity: 1;
-  color: rgb(0 0 0 / var(--tw-text-opacity));
-}
-
 .sc-text-slate-500 {
   --tw-text-opacity: 1;
   color: rgb(100 116 139 / var(--tw-text-opacity));
@@ -993,6 +993,35 @@ select {
   text-decoration-line: none;
 }
 
+@media (prefers-color-scheme: dark) {
+  .dark\:sc-bg-neutral-700\/50 {
+    background-color: rgb(64 64 64 / 0.5);
+  }
+
+  .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) {
   .md\:sc-text-lg {
     font-size: 1.125rem;

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>

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] %>">
+<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 hover:sc-text-inherit hover: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.6"
 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.6
 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-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails