showcase-rails 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '081d707dee9578e786c17cb621826f685bf2a4f9eab5221037b2394ac3b6805b'
-  data.tar.gz: 46fad2bf9b84aba2bf22bf0a627eb225ee904cd67da55cda4c0690b34d8d5a07
+  metadata.gz: aead2040b7c095f85df0c152c6d96aa3bec927e52f49db09f407926536ce36ae
+  data.tar.gz: c5fd847fd56d1ffa39a4d9aae681106685c71aef2e199bbb637158ec80f43cbc
 SHA512:
-  metadata.gz: 480d2d5a3c891703603caec5131d3990e19d31c97e815c622d8c6152ec2c1519a430e55416fc63caab1d7f136dd0fe96bf9e45a39bbf854e39134339822f6157
-  data.tar.gz: d35a92bd276b05225cdb827a9d3ec832665e1b0978b2ec02294ecc3d0810fee926fbb5f58d989612177ebe879d833ea8a476057efa04ca845d5e3e2b1808694a
+  metadata.gz: 3ffe05a31b2be808620a735573c1cbaf705cceb75bdf03f750193f0ad5534096cb3bc81a4d98e51b80712408ca7b3b60465e85a23828ae469da9af3fdb348db5
+  data.tar.gz: f6ec194dec60349be7b4effd48a20517c8af04e45604b104687a6479a4bba92087ae11b36d702fac03e8d1faebb22521b6d49e62d816b5a42d187e027ce9ce00

data/README.md

@@ -54,11 +54,34 @@ if defined?(Showcase)
 end
 ```
 
-## Automatic integration testing
+## Automatic previews testing
 
-Showcase automatically runs integration tests for all your Showcases by rendering them and asserting they respond with `200 OK`. As long as `gem "showcase-rails"` is in the `:test` group you're set.
+Showcase automatically runs tests for all your Showcases by rendering them. As long as `gem "showcase-rails"` is in the `:test` group you're set.
 
-If you want to tweak this, run `bin/rails showcase:install:integration_test` and open `test/integration/showcase_test.rb`. You can then add your own `setup` and `teardown` hooks, as well as override the provided `assert_showcase_preview` to add custom assertions.
+If you want to tweak this, run `bin/rails showcase:install:previews_test` and open `test/views/showcase_test.rb`. You can then add your own `setup` and `teardown` hooks, as well as override the provided `assert_showcase_preview` to add custom assertions.
+
+If you need custom assertions for specific previews and their samples, 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", id: "basic" do
+    # This test block runs within the #button container element's #basic sample.
+    assert_button class: ["text-xs"]
+  end
+
+  test "some non-Showcase test" do
+    # You can still use the regular Rails `test` method too.
+  end
+end
+```
 
 ## View examples
 
@@ -95,7 +118,7 @@ copy the file from our repo `app/views` directory into your `app/views` director
 
 ### Loading your own assets
 
-Showcase bundles its own `showcase.js` and `showcase.css` asset files through
+Showcase bundles its own `showcase.js`, `showcase.css` and `showcase.highlights.css` asset files through
 Action View's [javascript_include_tag][] and [stylesheet_link_tag][].
 
 If your assets require more sophisticated loading techniques, declare your own
@@ -103,12 +126,24 @@ 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/_javascripts.html.erb]: ./showcase/engine/_javascripts.html.erb
 [showcase/engine/_stylesheets.html.erb]: ./showcase/engine/_stylesheets.html.erb
 
+#### 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.
+<%= tag.style Rouge::Theme.find(:magritte).render(scope: ".sc-highlight") %>
+```
+
+[rouge-themes]: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
+
 ## 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:
@@ -129,6 +164,12 @@ Or install it yourself as:
 $ 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)
+```
+
 ## Contributing
 Contribution directions go here.
 

data/app/assets/builds/showcase.css

@@ -985,6 +985,14 @@ select {
   background-color: rgb(238 242 255 / var(--tw-bg-opacity));
 }
 
+.hover\:sc-text-inherit:hover {
+  color: inherit;
+}
+
+.hover\:sc-no-underline:hover {
+  text-decoration-line: none;
+}
+
 @media (min-width: 768px) {
   .md\:sc-text-lg {
     font-size: 1.125rem;

data/app/assets/builds/showcase.highlights.css

@@ -0,0 +1,112 @@
+.sc-highlight table td { padding: 5px; }
+.sc-highlight table pre { margin: 0; }
+.sc-highlight, .sc-highlight .w {
+  color: #24292f;
+  background-color: #f6f8fa;
+}
+.sc-highlight .k, .sc-highlight .kd, .sc-highlight .kn, .sc-highlight .kp, .sc-highlight .kr, .sc-highlight .kt, .sc-highlight .kv {
+  color: #cf222e;
+}
+.sc-highlight .gr {
+  color: #f6f8fa;
+}
+.sc-highlight .gd {
+  color: #82071e;
+  background-color: #ffebe9;
+}
+.sc-highlight .nb {
+  color: #953800;
+}
+.sc-highlight .nc {
+  color: #953800;
+}
+.sc-highlight .no {
+  color: #953800;
+}
+.sc-highlight .nn {
+  color: #953800;
+}
+.sc-highlight .sr {
+  color: #116329;
+}
+.sc-highlight .na {
+  color: #116329;
+}
+.sc-highlight .nt {
+  color: #116329;
+}
+.sc-highlight .gi {
+  color: #116329;
+  background-color: #dafbe1;
+}
+.sc-highlight .kc {
+  color: #0550ae;
+}
+.sc-highlight .l, .sc-highlight .ld, .sc-highlight .m, .sc-highlight .mb, .sc-highlight .mf, .sc-highlight .mh, .sc-highlight .mi, .sc-highlight .il, .sc-highlight .mo, .sc-highlight .mx {
+  color: #0550ae;
+}
+.sc-highlight .sb {
+  color: #0550ae;
+}
+.sc-highlight .bp {
+  color: #0550ae;
+}
+.sc-highlight .ne {
+  color: #0550ae;
+}
+.sc-highlight .nl {
+  color: #0550ae;
+}
+.sc-highlight .py {
+  color: #0550ae;
+}
+.sc-highlight .nv, .sc-highlight .vc, .sc-highlight .vg, .sc-highlight .vi, .sc-highlight .vm {
+  color: #0550ae;
+}
+.sc-highlight .o, .sc-highlight .ow {
+  color: #0550ae;
+}
+.sc-highlight .gh {
+  color: #0550ae;
+  font-weight: bold;
+}
+.sc-highlight .gu {
+  color: #0550ae;
+  font-weight: bold;
+}
+.sc-highlight .s, .sc-highlight .sa, .sc-highlight .sc, .sc-highlight .dl, .sc-highlight .sd, .sc-highlight .s2, .sc-highlight .se, .sc-highlight .sh, .sc-highlight .sx, .sc-highlight .s1, .sc-highlight .ss {
+  color: #0a3069;
+}
+.sc-highlight .nd {
+  color: #8250df;
+}
+.sc-highlight .nf, .sc-highlight .fm {
+  color: #8250df;
+}
+.sc-highlight .err {
+  color: #f6f8fa;
+  background-color: #82071e;
+}
+.sc-highlight .c, .sc-highlight .ch, .sc-highlight .cd, .sc-highlight .cm, .sc-highlight .cp, .sc-highlight .cpf, .sc-highlight .c1, .sc-highlight .cs {
+  color: #6e7781;
+}
+.sc-highlight .gl {
+  color: #6e7781;
+}
+.sc-highlight .gt {
+  color: #6e7781;
+}
+.sc-highlight .ni {
+  color: #24292f;
+}
+.sc-highlight .si {
+  color: #24292f;
+}
+.sc-highlight .ge {
+  color: #24292f;
+  font-style: italic;
+}
+.sc-highlight .gs {
+  color: #24292f;
+  font-weight: bold;
+}

data/app/models/showcase/sample.rb

@@ -2,9 +2,9 @@ class Showcase::Sample
   attr_reader :name, :id, :events, :details
   attr_reader :source, :instrumented
 
-  def initialize(view_context, name, description: nil, id: name.parameterize, events: nil, **details)
+  def initialize(view_context, name, description: nil, id: name.parameterize, syntax: :erb, events: nil, **details)
     @view_context = view_context
-    @name, @id, @details = name, id, details
+    @name, @id, @syntax, @details = name, id, syntax, details
     @events = Array(events)
     description description if description
   end
@@ -34,13 +34,13 @@ class Showcase::Sample
   end
 
   def extract(&block)
-    lines = extract_block_lines_via_matched_indentation_from(*block.source_location)
-    @source = @view_context.instance_exec(lines, &Showcase.sample_renderer)
+    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_block_lines_via_matched_indentation_from(file, starting_index)
+  def extract_source_block_via_matched_indentation_from(file, starting_index)
     first_line, *lines = File.readlines(file).from(starting_index - 1)
 
     indentation = first_line.match(/^\s+(?=\b)/).to_s
@@ -48,6 +48,6 @@ class Showcase::Sample
 
     index = lines.index { _1.match?(matcher) }
     lines.slice!(index..) if index
-    lines
+    lines.join.strip_heredoc
   end
 end

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

@@ -1,4 +1,4 @@
-<div class="sc-space-y-8">
+<div class="sc-space-y-8" id="<%= preview.id %>">
   <section>
     <% if preview.title %>
       <div class="sc-flex sc-items-center sc-space-x-2 sc-mb-2">

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

@@ -27,8 +27,8 @@
       <details>
         <summary class="sc-px-4 sc-py-2 hover:sc-bg-indigo-50 sc-cursor-pointer sc-select-none">View Source</summary>
 
-        <section class="sc-px-4 sc-py-2 sc-relative sc-overflow-y-auto hover:sc-select-all">
-          <%= sample.source %>
+        <section class="sc-highlight sc-px-4 sc-py-2 sc-relative sc-overflow-y-auto hover:sc-select-all">
+          <pre><%= sample.source %></pre>
         </section>
       </details>
     <% end %>

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

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

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" %>
+  <%= 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/lib/showcase/engine.rb

@@ -6,8 +6,8 @@ module Showcase
       config.assets.precompile += %w[showcase_manifest]
     end
 
-    initializer "showcase.integration_test.autorun" do
-      Showcase::IntegrationTest.autorun if Rails.env.test?
+    initializer "showcase.previews_test.autorun" do
+      Showcase::PreviewsTest.autorun if Rails.env.test?
     end
   end
 end

data/lib/showcase/previews_test.rb

@@ -0,0 +1,45 @@
+class Showcase::PreviewsTest < ActionView::TestCase
+  def self.inherited(test_class)
+    super
+    test_class.prepare
+  end
+
+  def self.autorun
+    at_exit { prepare unless subclasses.any? }
+  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
+        render "showcase/engine/preview", preview: path.preview_for(view)
+        assert_showcase_preview(path.id)
+      end
+    end
+
+    test "Showcase: isn't empty" do
+      assert_not_empty tree, "Showcase couldn't find any samples to generate tests for"
+    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"
+    else
+      super "Showcase: showcase/previews/#{showcase} #{"sample #{id}" if id}".squish 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) }
+      end
+    end
+  end
+
+  # Override `assert_showcase_preview` to add custom assertions.
+  def assert_showcase_preview(id)
+  end
+end

data/lib/showcase/version.rb

@@ -1,3 +1,3 @@
 module Showcase
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

data/lib/showcase.rb

@@ -1,12 +1,28 @@
 require_relative "showcase/version"
 
+# Activate the app-bundled Rouge gem to setup default syntax highlighting.
+begin
+  gem "rouge"
+  require "rouge"
+rescue LoadError
+end
+
 module Showcase
-  autoload :IntegrationTest, "showcase/integration_test"
-  autoload :RouteHelper,     "showcase/route_helper"
-  autoload :Options,         "showcase/options"
+  autoload :PreviewsTest, "showcase/previews_test"
+  autoload :RouteHelper,  "showcase/route_helper"
+  autoload :Options,      "showcase/options"
 
   singleton_class.attr_accessor :sample_renderer
-  @sample_renderer = ->(lines) { tag.pre lines.join.strip_heredoc }
+  @sample_renderer = proc { _1 }
+
+  if defined?(Rouge)
+    Formatter = Rouge::Formatters::HTML.new
+
+    @sample_renderer = ->(source, syntax) do
+      lexed = Rouge::Lexer.find(syntax).lex(source)
+      Showcase::Formatter.format(lexed).html_safe
+    end
+  end
 
   singleton_class.attr_reader :previews_path
   @previews_path = "showcase/previews"

data/lib/tasks/showcase_tasks.rake

@@ -1,14 +1,14 @@
 namespace :showcase do
   namespace :install do
-    INTEGRATION_TEST_PATH = "test/integration/showcase_test.rb"
+    PREVIEWS_TEST_PATH = "test/views/showcase_test.rb"
 
-    desc "Install Showcase integration testing in #{INTEGRATION_TEST_PATH}"
-    task :integration_test do
-      mkdir_p File.dirname(INTEGRATION_TEST_PATH)
-      File.write INTEGRATION_TEST_PATH, <<~RUBY
+    desc "Install Showcase previews testing in #{PREVIEWS_TEST_PATH}"
+    task :previews_test do
+      mkdir_p File.dirname(PREVIEWS_TEST_PATH)
+      File.write PREVIEWS_TEST_PATH, <<~RUBY
         require "test_helper"
 
-        class ShowcaseTest < Showcase::IntegrationTest
+        class ShowcaseTest < Showcase::PreviewsTest
           def assert_showcase_preview(id)
             # Add any custom preview response body assertions here.
           end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: showcase-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Daniel Pence
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-20 00:00:00.000000000 Z
+date: 2023-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -50,6 +50,7 @@ files:
 - README.md
 - Rakefile
 - app/assets/builds/showcase.css
+- app/assets/builds/showcase.highlights.css
 - app/assets/config/showcase_manifest.js
 - app/assets/javascripts/showcase.js
 - app/controllers/showcase/engine_controller.rb
@@ -73,8 +74,8 @@ files:
 - lib/showcase-rails.rb
 - lib/showcase.rb
 - lib/showcase/engine.rb
-- lib/showcase/integration_test.rb
 - lib/showcase/options.rb
+- lib/showcase/previews_test.rb
 - lib/showcase/route_helper.rb
 - lib/showcase/version.rb
 - lib/tasks/showcase_tasks.rake
@@ -100,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: Showcase helps you show off and document your partials, components, view

data/lib/showcase/integration_test.rb

@@ -1,30 +0,0 @@
-class Showcase::IntegrationTest < ActionDispatch::IntegrationTest
-  def self.inherited(test_class)
-    super
-    test_class.prepare
-  end
-
-  def self.autorun
-    at_exit { prepare unless subclasses.any? }
-  end
-
-  def self.prepare
-    tree = Showcase::Path.tree
-    tree.flat_map(&:ordered_paths).each do |path|
-      test "Showcase: GET showcase/previews/#{path.id} renders successfully" do
-        get showcase.preview_path(path.id)
-
-        assert_response :ok
-        assert_showcase_preview(path.id)
-      end
-    end
-
-    test "Showcase: isn't empty" do
-      assert_not_empty tree, "Showcase couldn't find any samples to generate tests for"
-    end
-  end
-
-  # Override `assert_showcase_preview` to add custom assertions.
-  def assert_showcase_preview(id)
-  end
-end