showcase-rails 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e84e94d8b861787bdbbcd87577beab2496d60c231b8803e1ba83d0a0e488708
-  data.tar.gz: 7e95b0377b27c9f17df42f35a1491fa6d4aafb821bfc1df1db4c496b42fb86b4
+  metadata.gz: 38aa85b8e5c0a98ee2dbb45f0a184981de8a86371efbb2237e2a06f0d2f56eef
+  data.tar.gz: b4e44e25c0b76afcd33a2dc155cae5bdebe1a5a9ca3cd670d4cc2bae94d7f38b
 SHA512:
-  metadata.gz: a1666dce260d55ba265e654dfd39bde2304bdb130b04b389f38352d16bdbe8771031fa79264ff2e13d479018aa33fb069dcc4e1cf835021e0003b9030c54f213
-  data.tar.gz: f19f23e1545e075bd2f78e1750b3da6838ab78850368a866f2351ac0dacf6aad9b64ea680fefc0618721baf70c025625e29a2fdee7ceb616a4ca74dfaf9309ab
+  metadata.gz: 995f0b2b6f765c93936adb968c501218fccc592befe12df06e0aa19b9b092a0ea385cab086763f0b855e3e86eb784edf8365143b49e69dbda934bd8ce608016d
+  data.tar.gz: 123c59c68801489dec09d40c144c64fbc09dc6c65925833cbeade7a4c8f479595b6d59274d3ab7e74cdd18495dd8276ef60fa714b3f87662c786d6c190d55c39

data/README.md

@@ -1,13 +1,14 @@
 # Showcase
 
-Showcase lets you build previews for partials, components, view helpers and Stimulus controllers.
+Showcase lets you build previews for your partials, components, view helpers, Stimulus controllers and more.
 
-Add a view template to `app/views/showcases` and it'll show up in Showcase's menu.
+Add a template to `app/views/showcase/previews` and it'll show up in Showcase's menu.
 
 Here's how to showcase a standard button component:
 
 ```erb
-<%# app/views/showcases/components/button.html.erb %>
+<%# app/views/showcase/previews/_button.html.erb %>
+<% showcase.title "Button" %> <%# `title` is optional and inferred from the filename, by default. %>
 <% showcase.description "This button component handles what we click on" %>
 
 <% showcase.sample "Basic" do %>
@@ -19,17 +20,85 @@ Here's how to showcase a standard button component:
 <% end %>
 
 <% showcase.options do |o| %>
-  <% o.required :content, String, "The content to output as the button text" %>
-  <% o.optional :mode, default: :small, values: %i[ small medium large ], description: "We support three modes" %>
+  <% o.required :content, "The content to output as the button text" %>
+  <% o.optional :mode, "We support three modes", default: :small, options: %i[ small medium large ] %>
 <% end %>
 ```
 
+Which will then render the following:
+
+![](/readme/example.png?raw=true "Showcase showing a button component")
+
+## Automatic smokescreen testing
+
+Run `bin/rails showcase:install:integration_test` to automatic testing installed in `test/integration/showcase_test.rb`.
+
+This will render every Showcase you've defined and assert they respond with `200 OK`. You can add custom assertions by overriding `assert_showcase_preview`.
+
+## View examples
+
+Clone the repository, run `bundle install`, then run `bin/rails server`, visit localhost:3000 in your browser.
+
+## Overriding Showcase's default rendering
+
+Showcase's rendering happens through two controllers:
+
+1. [`Showcase::EngineController`](app/controllers/showcase/engine_controller.rb)
+1. [`Showcase::PreviewsController`](app/controllers/showcase/previews_controller.rb)
+
+All paths shown here are assumed to be in `app/views`.
+
+The actions all use a `layout "showcase"`, which renders like this:
+
+- [layouts/showcase.html.erb](app/views/layouts/showcase.html.erb)
+  - [showcase/engine/_root.html.erb](app/views/showcase/engine/_root.html.erb)
+    - [showcase/engine/path/_tree.html.erb](app/views/showcase/engine/path/_tree.html.erb)
+
+So for `Showcase::EngineController#index` we render:
+
+- [showcase/engine/index.html.erb](app/views/showcase/engine/index.html.erb)
+
+And for `Showcase::PreviewsController#show` we render:
+
+- [showcase/engine/show.html.erb](app/views/showcase/engine/show.html.erb)
+  - [showcase/engine/_preview.html.erb](app/views/showcase/engine/_preview.html.erb)
+    - [showcase/engine/_sample.html.erb](app/views/showcase/engine/_sample.html.erb)
+    - [showcase/engine/_options.html.erb](app/views/showcase/engine/_options.html.erb)
+
+If you want to override any specific rendering, e.g. how a `Showcase::Preview` is rendered,
+copy the file from our repo `app/views` directory into your `app/views` directory.
+
+### Loading your own assets
+
+Showcase bundles its own `showcase.js` and `showcase.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
+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
+
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's Gemfile. If you're utilizing the
+[Showcase::IntegrationTest](lib/showcase/integration_test.rb) class, make sure
+that the `showcase-rails` gems is available to your test environment:
+
 
 ```ruby
-gem "showcase"
+# nested in the default group
+gem "showcase-rails"
+
+# or nested in the :development and :test groups
+group :development, :test do
+  gem "showcase-rails"
+end
 ```
 
 And then execute:

data/app/assets/builds/showcase.css

@@ -679,280 +679,280 @@ select {
   --tw-backdrop-sepia:  ;
 }
 
-.relative {
+.sc-relative {
   position: relative;
 }
 
-.col-span-3 {
+.sc-col-span-3 {
   grid-column: span 3 / span 3;
 }
 
-.col-span-9 {
+.sc-col-span-9 {
   grid-column: span 9 / span 9;
 }
 
-.mb-2 {
+.sc-mb-2 {
   margin-bottom: 0.5rem;
 }
 
-.mb-4 {
+.sc-mb-4 {
   margin-bottom: 1rem;
 }
 
-.inline-block {
+.sc-inline-block {
   display: inline-block;
 }
 
-.flex {
+.sc-flex {
   display: flex;
 }
 
-.table {
+.sc-table {
   display: table;
 }
 
-.grid {
+.sc-grid {
   display: grid;
 }
 
-.h-full {
+.sc-h-full {
   height: 100%;
 }
 
-.max-h-20 {
+.sc-max-h-20 {
   max-height: 5rem;
 }
 
-.min-h-screen {
+.sc-min-h-screen {
   min-height: 100vh;
 }
 
-.w-full {
+.sc-w-full {
   width: 100%;
 }
 
-.border-collapse {
+.sc-border-collapse {
   border-collapse: collapse;
 }
 
-.cursor-pointer {
+.sc-cursor-pointer {
   cursor: pointer;
 }
 
-.select-none {
+.sc-select-none {
   -webkit-user-select: none;
      -moz-user-select: none;
           user-select: none;
 }
 
-.list-none {
+.sc-list-none {
   list-style-type: none;
 }
 
-.grid-cols-12 {
+.sc-grid-cols-12 {
   grid-template-columns: repeat(12, minmax(0, 1fr));
 }
 
-.flex-col {
+.sc-flex-col {
   flex-direction: column;
 }
 
-.flex-wrap {
+.sc-flex-wrap {
   flex-wrap: wrap;
 }
 
-.items-center {
+.sc-items-center {
   align-items: center;
 }
 
-.space-y-8 > :not([hidden]) ~ :not([hidden]) {
+.sc-space-y-8 > :not([hidden]) ~ :not([hidden]) {
   --tw-space-y-reverse: 0;
   margin-top: calc(2rem * calc(1 - var(--tw-space-y-reverse)));
   margin-bottom: calc(2rem * var(--tw-space-y-reverse));
 }
 
-.space-x-2 > :not([hidden]) ~ :not([hidden]) {
+.sc-space-x-2 > :not([hidden]) ~ :not([hidden]) {
   --tw-space-x-reverse: 0;
   margin-right: calc(0.5rem * var(--tw-space-x-reverse));
   margin-left: calc(0.5rem * calc(1 - var(--tw-space-x-reverse)));
 }
 
-.space-y-4 > :not([hidden]) ~ :not([hidden]) {
+.sc-space-y-4 > :not([hidden]) ~ :not([hidden]) {
   --tw-space-y-reverse: 0;
   margin-top: calc(1rem * calc(1 - var(--tw-space-y-reverse)));
   margin-bottom: calc(1rem * var(--tw-space-y-reverse));
 }
 
-.overflow-hidden {
-  overflow: hidden;
-}
-
-.overflow-scroll {
+.sc-overflow-scroll {
   overflow: scroll;
 }
 
-.overflow-x-auto {
+.sc-overflow-x-auto {
   overflow-x: auto;
 }
 
-.truncate {
+.sc-overflow-y-auto {
+  overflow-y: auto;
+}
+
+.sc-truncate {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.rounded-md {
+.sc-rounded-md {
   border-radius: 0.375rem;
 }
 
-.border {
+.sc-border {
   border-width: 1px;
 }
 
-.border-0 {
+.sc-border-0 {
   border-width: 0px;
 }
 
-.border-r {
-  border-right-width: 1px;
+.sc-border-t {
+  border-top-width: 1px;
 }
 
-.border-t {
-  border-top-width: 1px;
+.sc-border-r {
+  border-right-width: 1px;
 }
 
-.border-b {
+.sc-border-b {
   border-bottom-width: 1px;
 }
 
-.border-gray-200 {
+.sc-border-gray-200 {
   --tw-border-opacity: 1;
   border-color: rgb(229 231 235 / var(--tw-border-opacity));
 }
 
-.bg-slate-50 {
+.sc-bg-slate-50 {
   --tw-bg-opacity: 1;
   background-color: rgb(248 250 252 / var(--tw-bg-opacity));
 }
 
-.bg-slate-100\/50 {
+.sc-bg-slate-100\/50 {
   background-color: rgb(241 245 249 / 0.5);
 }
 
-.bg-indigo-50 {
+.sc-bg-indigo-50 {
   --tw-bg-opacity: 1;
   background-color: rgb(238 242 255 / var(--tw-bg-opacity));
 }
 
-.p-12 {
-  padding: 3rem;
+.sc-p-4 {
+  padding: 1rem;
 }
 
-.p-4 {
-  padding: 1rem;
+.sc-p-12 {
+  padding: 3rem;
 }
 
-.py-5 {
-  padding-top: 1.25rem;
-  padding-bottom: 1.25rem;
+.sc-px-4 {
+  padding-left: 1rem;
+  padding-right: 1rem;
 }
 
-.py-2 {
+.sc-py-2 {
   padding-top: 0.5rem;
   padding-bottom: 0.5rem;
 }
 
-.px-4 {
-  padding-left: 1rem;
-  padding-right: 1rem;
+.sc-py-5 {
+  padding-top: 1.25rem;
+  padding-bottom: 1.25rem;
 }
 
-.px-8 {
+.sc-px-8 {
   padding-left: 2rem;
   padding-right: 2rem;
 }
 
-.pl-4 {
+.sc-pl-4 {
   padding-left: 1rem;
 }
 
-.pt-7 {
+.sc-pt-7 {
   padding-top: 1.75rem;
 }
 
-.text-2xl {
-  font-size: 1.5rem;
-  line-height: 2rem;
-}
-
-.text-xl {
+.sc-text-xl {
   font-size: 1.25rem;
   line-height: 1.75rem;
 }
 
-.text-3xl {
+.sc-text-3xl {
   font-size: 1.875rem;
   line-height: 2.25rem;
 }
 
-.text-base {
+.sc-text-base {
   font-size: 1rem;
   line-height: 1.5rem;
 }
 
-.font-black {
-  font-weight: 900;
+.sc-text-2xl {
+  font-size: 1.5rem;
+  line-height: 2rem;
 }
 
-.font-semibold {
+.sc-font-semibold {
   font-weight: 600;
 }
 
-.font-normal {
+.sc-font-normal {
   font-weight: 400;
 }
 
-.font-medium {
+.sc-font-black {
+  font-weight: 900;
+}
+
+.sc-font-medium {
   font-weight: 500;
 }
 
-.italic {
+.sc-italic {
   font-style: italic;
 }
 
-.leading-snug {
+.sc-leading-snug {
   line-height: 1.375;
 }
 
-.text-black {
+.sc-text-black {
   --tw-text-opacity: 1;
   color: rgb(0 0 0 / var(--tw-text-opacity));
 }
 
-.hover\:select-all:hover {
+.hover\:sc-select-all:hover {
   -webkit-user-select: all;
      -moz-user-select: all;
           user-select: all;
 }
 
-.hover\:bg-indigo-50:hover {
+.hover\:sc-bg-indigo-50:hover {
   --tw-bg-opacity: 1;
   background-color: rgb(238 242 255 / var(--tw-bg-opacity));
 }
 
 @media (min-width: 768px) {
-  .md\:text-lg {
+  .md\:sc-text-lg {
     font-size: 1.125rem;
     line-height: 1.75rem;
   }
 }
 
 @media (min-width: 1280px) {
-  .xl\:col-span-2 {
+  .xl\:sc-col-span-2 {
     grid-column: span 2 / span 2;
   }
 
-  .xl\:col-span-10 {
+  .xl\:sc-col-span-10 {
     grid-column: span 10 / span 10;
   }
 }

data/app/controllers/showcase/engine_controller.rb

@@ -0,0 +1,12 @@
+class Showcase::EngineController < ActionController::Base
+  layout "showcase"
+
+  helper Showcase::RouteHelper
+
+  if defined?(::ApplicationController)
+    helper all_helpers_from_path ::ApplicationController.helpers_path
+  end
+
+  def index
+  end
+end

data/app/controllers/showcase/pages_controller.rb

@@ -1,7 +1,4 @@
-class Showcase::PagesController < Showcase::ApplicationController
-  def index
-  end
-
+class Showcase::PagesController < Showcase::EngineController
   def show
     @page = Showcase::Path.new(params[:id]).page_for view_context
   end

data/app/controllers/showcase/previews_controller.rb

@@ -0,0 +1,5 @@
+class Showcase::PreviewsController < Showcase::EngineController
+  def show
+    @preview = Showcase::Path.new(params[:id]).preview_for view_context
+  end
+end

data/app/models/showcase/{page/options.rb → options.rb}

@@ -1,4 +1,4 @@
-class Showcase::Page::Options
+class Showcase::Options
   include Enumerable
 
   def initialize(view_context)

data/app/models/showcase/path.rb

@@ -1,30 +1,67 @@
 class Showcase::Path
-  class Tree < Struct.new(:id, :paths)
+  class Tree < Struct.new(:id, :children)
+    def initialize(id, children = [])
+      super
+    end
+    delegate :<<, to: :children
+
+    cached_partial_path = "showcase/engine/path/tree"
+    define_method(:to_partial_path) { cached_partial_path }
+
     def name
-      root? ? "Pages" : id
+      root? ? "Previews" : id
     end
 
     def root?
       id == "."
     end
-  end
 
-  def self.tree
-    all.group_by(&:dirname).map { Tree.new _1, _2 }
+    def ordered_children
+      children.partition { !_1.is_a?(Tree) }.flatten
+    end
+
+    def ordered_paths
+      children.flat_map { _1.is_a?(Tree) ? _1.ordered_paths : _1 }
+    end
+
+    def self.index(...)
+      new(:discardable_root).tap { _1.index(...) }.ordered_children
+    end
+
+    def index(paths)
+      paths.each do |path|
+        ids = yield path
+        ids.inject(self, :edge_for) << path
+      end
+    end
+
+    def edge_for(id)
+      find(id) || insert(id)
+    end
+
+    private
+
+    def find(id)   = children.find { _1.id == id }
+    def insert(id) = self.class.new(id).tap { self << _1 }
   end
 
-  def self.all
-    Showcase.filenames.map { new _1 }.sort_by!(&:id)
+  def self.tree
+    paths = Showcase.previews.map { new _1 }.sort_by!(&:id)
+    Tree.index(paths, &:segments)
   end
 
-  attr_reader :id, :dirname, :basename
+  attr_reader :id, :segments, :basename
 
   def initialize(path)
-    @id = path.split(".").first
-    @dirname, @basename = File.split(@id)
+    @id = path.split(".").first.delete_prefix("_").sub(/\/_/, "/")
+    @basename = File.basename(@id)
+    @segments = File.dirname(@id).split("/")
   end
 
-  def page_for(view_context)
-    Showcase::Page.new(view_context, id: id, title: basename.titleize).tap(&:render_template)
+  cached_partial_path = "showcase/engine/path/path"
+  define_method(:to_partial_path) { cached_partial_path }
+
+  def preview_for(view_context)
+    Showcase::Preview.new(view_context, id: id, title: basename.titleize).tap(&:render_associated_partial)
   end
 end

data/app/models/showcase/preview.rb

@@ -0,0 +1,94 @@
+class Showcase::Preview
+  attr_reader :id, :badges, :samples
+
+  def initialize(view_context, id:, title: nil)
+    @view_context, @id = view_context, id
+    @badges, @samples = [], []
+    title title
+  end
+
+  # Set a custom title for the Preview. By default, it's automatically inferred from the sidebar title,
+  # e.g. showcase/previews/_button.html.erb will have Button as the title.
+  def title(content = nil)
+    @title = content if content
+    @title
+  end
+
+  # Describe the Preview in more detail to help guide other developers on what the inner partial/component etc.'s purpose is.
+  #
+  #   <% showcase.description "Our button element" %>
+  #   <% showcase.description do %>
+  #      <h3>Our button element</h3> — <span>but with custom description HTML</span>
+  #   <% end %>
+  def description(content = nil, &block)
+    @description = content || @view_context.capture(&block) if content || block_given?
+    @description
+  end
+
+  # Optional badges you can give to a preview:
+  #
+  #   <% showcase.badge :partial, :view_helper %>
+  def badge(*badges)
+    @badges.concat badges
+  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:
+  #
+  #   <% showcase.sample "Basic" do %>
+  #     <%= render "components/button", content: "Button Content", mode: :small %>
+  #   <% end %>
+  #
+  # This outputs a `<showcase-sample>` custom HTML element.
+  # The sample name is used to generate the `id` via `name.parameterize` by default, pass `id:` to override.
+  #
+  # If more advanced rendering is needed, the sample is available as a block argument:
+  #
+  #   <% showcase.sample "Advanced" do |sample| %>
+  #     <% sample.preview do %>
+  #       <%= render "components/button", content: "Button Content", mode: :small %>
+  #     <% end %>
+  #
+  #     <% sample.extract do %>
+  #       This will be in the source output.
+  #     <% end %>
+  #
+  # The sample also supports several extra options:
+  #
+  #   <% showcase.sample "Basic", id: "custom-id", description: "Please use this", events: "toggle:toggled", custom: "option" do %>
+  #     <%# … %>
+  #   <% end %>
+  #
+  # Here we set:
+  #   - the `sample.id` with the HTML element `id` is overriden
+  #   - the `sample.description`
+  #   - 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) }
+  end
+
+  # Yields an Options object to help define the configuration table for a Preview.
+  #
+  #   <% showcase.options do |o| %>
+  #     <% o.required :content,    "Pass the inner content text that the button should display" %>
+  #     <% o.optional :mode,       "Pass an optional mode override", default: :small, options: %i[ small medium large ] %>
+  #     <% o.optional :method,     "What HTTP method to use", type: "String | Symbol", default: :post %>
+  #     <% o.optional :reversed,   "Whether the inner text should be reversed", default: false %> # type: "Boolean" is inferred from the default here.
+  #     <% o.optional "**options", "Every other option is passed on as options to the inner `button_tag`", type: Hash %>
+  #   <% end %>
+  #
+  # The `type:` is derived if a `default:` is passed, otherwise it's assumed to be a String.
+  #
+  # Showcase outputs the columns with this order [:name, :required, :type, :default, :description], any other passed column is
+  # automatically rendered after those.
+  def options
+    @options ||= Showcase::Options.new(@view_context).tap { yield _1 if block_given? }
+  end
+
+  def render_associated_partial
+    @view_context.render "#{Showcase.previews_path}/#{id}", showcase: self
+    nil
+  end
+end