showcase-rails 0.2.8 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03270bcd056181e09393db4fb8c701fb082e41d3c30ed2ec00b82004e8c967a6
-  data.tar.gz: d762aea659bfd35a7b7a14126976d8bd56f9edf0ff8a8399e882b37907cbd4c9
+  metadata.gz: 1fcccbcd02f9ffc40e5c1555b816250dd78dace039662c5302ae4149f37a8fed
+  data.tar.gz: b4591324e7afa694e34bc412ae5d4442ecc5308d834b6874a29750e1b522a578
 SHA512:
-  metadata.gz: c7a642d7d0f7bf5dc52cf290116b566f81206650bdbd3880bbee20aefebb83edead2b4688abbc3ae376a89e6a63913880e8be51c908133c4bb4823ce3c2ddd89
-  data.tar.gz: 9ce4be151434d49e3a6acc329cf6c8765786844855fd00319b33ac48fe301bdf6609989acd44e16c72174bbc09a3774a4a736c18d79ef9e4a33acf6ebd76aaa2
+  metadata.gz: 4719a8283d75170d95c789469824aab301df3d822b0d2da6f89a3ecd60c1e0a660c4af275dfffcf1b4967a546799e7193ab1ebedd2c11715e240ac7f4c1fc28d
+  data.tar.gz: b5d74c620b87ca6860d4a7356196ce8f7dd25a0ac2d71caa37b1d9cd440cb6b8f79eea28384dde8cd955766c8d5468b7cc3c6e2f389d81cf4c09914e3089e87a

data/README.md

@@ -99,9 +99,10 @@ class ShowcaseTest < Showcase::PreviewsTest
     assert_text "This is a combobox, for sure."
   end
 
-  test showcase: "button", id: "basic" do
-    # This test block runs within the #button container element's #basic sample.
-    assert_button class: ["text-xs"]
+  test showcase: "button" do
+    assert_selector id: "basic" do
+      assert_button class: ["text-xs"]
+    end
   end
 
   test "some non-Showcase test" do
@@ -110,6 +111,18 @@ class ShowcaseTest < Showcase::PreviewsTest
 end
 ```
 
+## Linking to previews
+
+Call `showcase.link_to` with the URL path to the other Showcase:
+
+```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" %>
+```
+
 ## 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).

data/app/assets/builds/showcase.css

@@ -916,6 +916,10 @@ select {
   padding-top: 1.75rem;
 }
 
+.sc-font-mono {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+}
+
 .sc-text-2xl {
   font-size: 1.5rem;
   line-height: 2rem;
@@ -931,6 +935,11 @@ select {
   line-height: 1.5rem;
 }
 
+.sc-text-sm {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+
 .sc-text-xl {
   font-size: 1.25rem;
   line-height: 1.75rem;

data/app/models/showcase/preview.rb

@@ -32,6 +32,22 @@ class Showcase::Preview
     @badges.concat badges
   end
 
+  # Allows linking out to other Showcases
+  #
+  #   <%= showcase.link_to "components/button", id: "extra-large" %>
+  #   # => <a href="components/button#extra-large"><showcase components/button#extra-large></a>
+  #
+  # Can link to other samples on the current showcase too:
+  #
+  #   # If we're within app/views/showcase/previews/components/_button.html.erb
+  #   <%= showcase.link_to id: "extra-large" %>
+  #   # => <a href="components/button#extra-large"><showcase components/button#extra-large></a>
+  def link_to(preview_id = id, id: nil)
+    @view_context.link_to @view_context.preview_path(preview_id, anchor: id), class: "sc-font-mono sc-text-sm" do
+      "<showcase #{[preview_id, id].compact.join("#").squish}>"
+    end
+  end
+
   # Adds a named sample to demonstrate with the Showcase can do.
   #
   # By default, sample takes a block that'll automatically have its source extracted, like this:
@@ -66,7 +82,7 @@ class Showcase::Preview
   #   - the `sample.events` what JavaScript `events` to listen for on the element
   #   - any other custom options are available in `sample.details`.
   def sample(name, **options, &block)
-    @samples << Showcase::Sample.new(@view_context, name, **options).tap { _1.collect(&block) }
+    @samples << Showcase::Sample.new(@view_context, name, **options).tap { _1.evaluate(&block) }
   end
 
   # Yields an Options object to help define the configuration table for a Preview.
@@ -88,7 +104,7 @@ class Showcase::Preview
   end
 
   def render_associated_partial
-    @view_context.render "#{Showcase.previews_path}/#{id}", showcase: self
+    @view_context.render "showcase/previews/#{id}", showcase: self
     nil
   end
 end

data/app/models/showcase/sample.rb

@@ -1,6 +1,6 @@
 class Showcase::Sample
   attr_reader :name, :id, :events, :details
-  attr_reader :source, :instrumented
+  attr_reader :rendered, :source, :instrumented
 
   def initialize(view_context, name, description: nil, id: name.parameterize, syntax: :erb, events: nil, **details)
     @view_context = view_context
@@ -14,36 +14,39 @@ class Showcase::Sample
     @description
   end
 
-  def collect(&block)
+  def evaluate(&block)
     if block.arity.zero?
-      preview(&block)
-      extract(&block)
+      consume(&block)
     else
       @view_context.capture(self, &block)
     end
   end
 
-  def preview(&block)
-    return @preview unless block_given?
+  def consume(&block)
+    render(&block)
+    extract_source(&block)
+  end
 
+  def render(&block)
     # TODO: Remove `is_a?` check when Rails 6.1 support is dropped.
     assigns = proc { @instrumented = _1 if _1.is_a?(ActiveSupport::Notifications::Event) }
     ActiveSupport::Notifications.subscribed(assigns, "render_partial.action_view") do
-      @preview = @view_context.capture(&block)
+      @rendered = @view_context.capture(&block)
     end
   end
 
-  def extract(&block)
+  def extract_source(&block)
     source = extract_source_block_via_matched_indentation_from(*block.source_location)
     @source = @view_context.instance_exec(source, @syntax, &Showcase.sample_renderer)
   end
 
   private
 
-  def extract_source_block_via_matched_indentation_from(file, starting_index)
-    first_line, *lines = File.readlines(file).from(starting_index - 1)
+  def extract_source_block_via_matched_indentation_from(file, source_location_index)
+    # `Array`s are zero-indexed, but `source_location` indexes are not, hence `pred`.
+    starting_line, *lines = File.readlines(file).slice(source_location_index.pred..)
 
-    indentation = first_line.match(/^\s+(?=\b)/).to_s
+    indentation = starting_line.match(/^\s+/).to_s
     matcher = /^#{indentation}\S/
 
     index = lines.index { _1.match?(matcher) }

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

@@ -19,9 +19,9 @@
       <% end %>
     </header>
 
-    <% if sample.preview %>
+    <% if sample.rendered %>
       <section class="sc-px-4 sc-py-2">
-        <%= sample.preview %>
+        <%= sample.rendered %>
       </section>
     <% 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] %>">
-  <%= link_to path.basename.titleize, showcase.preview_path(path.id), class: "sc-inline-block sc-py-2 sc-px-8 sc-w-full !sc-text-inherit !sc-no-underline" %>
+  <%= 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/config/tailwind.config.js

@@ -4,7 +4,7 @@ module.exports = {
   prefix: 'sc-',
   content: [
     './public/*.html',
-    './app/helpers/**/*.rb',
+    './app/{models,helpers}/**/*.rb',
     './app/javascript/**/*.js',
     './app/views/**/*.{erb,haml,html,slim}'
   ],

data/lib/showcase/previews_test.rb

@@ -1,12 +1,13 @@
 class Showcase::PreviewsTest < ActionView::TestCase
+  extensions = [ Showcase::EngineController._helpers, Showcase::Engine.routes.url_helpers ]
+  setup { view.extend *extensions }
+
   def self.inherited(test_class)
     super
     test_class.prepare
   end
 
   def self.prepare
-    tests Showcase::EngineController._helpers
-
     tree = Showcase::Path.tree
     tree.flat_map(&:ordered_paths).each do |path|
       test "Showcase: automatically renders showcase/previews/#{path.id}" do
@@ -20,17 +21,16 @@ class Showcase::PreviewsTest < ActionView::TestCase
     end
   end
 
-  def self.test(name = nil, showcase: nil, id: nil, &block)
-    case
-    when name then super(name, &block)
-    when id && showcase.nil? then raise ArgumentError, "can't test a sample without a showcase"
+  def self.test(name = nil, showcase: nil, &block)
+    if name
+      super(name, &block)
     else
-      super "Showcase: showcase/previews/#{showcase} #{"sample #{id}" if id}".squish do
+      super "Showcase: showcase/previews/#{showcase}" do
         path = Showcase::Path.new(showcase)
         render "showcase/engine/preview", preview: path.preview_for(view)
 
         assert_showcase_preview(path.id)
-        assert_element(id: id || path.id) { instance_eval(&block) }
+        instance_eval(&block)
       end
     end
   end

data/lib/showcase/version.rb

@@ -1,3 +1,3 @@
 module Showcase
-  VERSION = "0.2.8"
+  VERSION = "0.3.1"
 end

data/lib/showcase.rb

@@ -24,12 +24,9 @@ module Showcase
     end
   end
 
-  singleton_class.attr_reader :previews_path
-  @previews_path = "showcase/previews"
-
   def self.previews
     Showcase::EngineController.view_paths.map(&:path).flat_map do |root|
-      Dir.glob("**/*.*", base: File.join(root, previews_path))
+      Dir.glob("**/*.*", base: File.join(root, "showcase/previews"))
     end.uniq
   end
 

metadata

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