lookbook 0.3.4 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64f02e35ce90b1e27249752c3ea536ead68b7f6dba3a6bb0991dff8f29f63d92
-  data.tar.gz: effca06a618749eb6be51880929f417d0de03fe180d60e3df026065a7d0718ee
+  metadata.gz: 6556e23e693e27f706b4989f25c13c75a453ce5582e835e6c380a226840feff8
+  data.tar.gz: c28f4d88136a02522fb23adc826ec1066c0800ef6a223451149b4516448d318c
 SHA512:
-  metadata.gz: 3323004e8ea85985c687adfe184b0519b3b168676df1640cdb5ada335ffef304a1266e6ad239e62968261e2c043c98b23589dd28ed3913e22c620500fc76cdde
-  data.tar.gz: a60ed3e4b295875fcac660f560d75dc4ac9ecff3cf26a410c30837326c84e26e8e2cea4ad183879ee94049836ab68fb81b3d59c0aab6c081d239744184cfc374
+  metadata.gz: 92076777e5a0e2ca449eec799a4702965bc78c12ae1d48f0a7de9276832f02b320f25ecc5384d56aeb5138a953b26a8251ad44756d6a36a58c7fbe84255078e4
+  data.tar.gz: e840534cd52b19c9db2b39316739b7ee8df820c96837f59cfd03e96fe99d90778eddc5518ffc5ac0167f61e27f74a2fafaa83642eb7697fd433d34cd09f28550

data/README.md

@@ -16,19 +16,17 @@
 
 It uses (and extends) the native [ViewComponent preview functionality](https://viewcomponent.org/guide/previews.html), so you don't need to learn a new DSL or create any extra files to get up and running.
 
-Lookbook uses [RDoc/Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) to extend the capabilities of ViewComponent's previews whilst maintaining compatability with the standard preview class format, so you can add or remove Lookbook at any time without having to rework your code.
+Lookbook uses [RDoc/Yard-style comment tags](#annotating-preview-files) to extend the capabilities of ViewComponent's previews whilst maintaining compatability with the standard preview class format, so you can add or remove Lookbook at any time without having to rework your code.
 
 ![Lookbook UI](.github/assets/lookbook_screenshot.png)
 
 ### Features
 
-- Tree-style navigation menu
-- Live nav search/filter
+- Tree-style navigation menu with live search/filter
 - Resizable preview window for responsive testing
 - Highlighted preview source code and HTML output
-- Add notes via comments in the preview file (markdown supported)
 - Auto-updating UI when component or preview files are updated _(Rails v6.0+ only)_
-- Hide, group and rename preview examples using comment tags
+- Use comment tag annotations for granular customisation of the preview experience
 - Fully compatible with standard the ViewComponent preview system
 
 ## Lookbook demo
@@ -39,8 +37,6 @@ The [demo app repo](https://github.com/allmarkedup/lookbook-demo) contains instr
 
 ## Installing
 
-> ⚠️ **Please note:** Lookbook is still in the early stages of development and has not yet been well tested across a wide range of Rails/ViewComponent versions and setups. If you run into any problems please [open an issue](issues) with as much detail as possible. Thanks! ⚠️
-
 ### 1. Add as a dependency
 
 Add Lookbook to your `Gemfile` somewhere **after** the ViewComponent gem. For example:
@@ -74,12 +70,13 @@ You don't need to do anything special to see your ViewComponent previews and exa
 
 > If you are new to ViewComponent development, checkout the ViewComponent [documentation](https://viewcomponent.org/guide/) on how to get started developing your components and [creating previews](https://viewcomponent.org/guide/previews.html).
 
-### Annotating preview files
+## Annotating preview files
 
 Lookbook parses [Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) in your preview classes to customise and extend the standard ViewComponent preview experience:
 
 ```ruby
 # @label Basic Button
+# @display bg_color "#fff"
 class ButtonComponentPreview < ViewComponent::Preview
 
   # Primary button
@@ -93,11 +90,13 @@ class ButtonComponentPreview < ViewComponent::Preview
     end
   end
 
-  # Secondary button
+  # Inverted button
   # ---------------
-  # This should be used for less important actions.
+  # For light-on-dark screens
+  #
+  # @display bg_color "#000"
   def secondary
-    render ButtonComponent.new(style: :secondary) do
+    render ButtonComponent.new(style: :inverted) do
       "Click me"
     end
   end
@@ -142,7 +141,12 @@ end
 
 The following Lookbook-specific tags are available for use:
 
-#### `@label <text>`
+* `@label <label>` -[Customise navigation labels](#-label-text)
+* `@hidden` - [Prevent items displaying in the navigation](#-hidden)
+* `@display <key> <value>` - [Specify params to pass into the preview template](#-display-key-value)
+* `@!group <name> ... @!endgroup` - [Render examples in a group on the same page](#-group-name--endgroup)
+
+### 🔖 `@label <text>`
 
 Used to replace the auto-generated navigation label for the item with `<text>`.
 
@@ -158,7 +162,7 @@ class FooComponentPreview < ViewComponent::Preview
 end
 ```
 
-#### `@hidden`
+### 🔖 `@hidden`
 
 Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
 
@@ -176,7 +180,91 @@ class FooComponentPreview < ViewComponent::Preview
 end
 ```
 
-#### `@!group <name> ... @!endgroup`
+### 🔖 `@display <key> <value>`
+
+The `@display` tag lets you pass custom parameters to your preview layout so that the component preview can be customised on a per-example basis.
+
+```ruby
+# @display bg_color "#eee"
+class FooComponentPreview < ViewComponent::Preview
+
+  # @display max_width "500px"
+  # @display wrapper true
+  def default
+  end
+end
+```
+
+The `@display` tag can be applied at the preview (class) or at the example (method) level, and takes the following format:
+
+```ruby
+# @display <key> <value>
+```
+
+- `<key>` must be a valid Ruby hash key name, without quotes or spaces
+- `<value>` must be a valid JSON-parsable value. It can be a string (surrounded by **double** quotes), a boolean or an integer.
+
+> [See below for some examples](#some-display-value-examples) of valid and invalid `@display` values.
+
+These display parameters can then be accessed via the `params` hash in your preview layout using `params[:lookbook][:display][<key>]`:
+
+```html
+<!DOCTYPE html>
+<html style="background-color: <%= params[:lookbook][:display][:bg_color] %>">
+  <head>
+    <title>Preview Layout</title>
+  </head>
+  <body>
+    <div style="max-width: <%= params[:lookbook][:display][:max_width] || '100%' %>">
+      <% if params[:lookbook][:display][:wrapper] == true %>
+        <div class="wrapper"><%= yield %></div>
+      <% else %>
+        <%= yield %>
+      <% end %>
+    </div>
+  </body>
+</html>
+```
+
+> By default ViewComponent will use your default application layout for displaying the rendered example. However it's often better to create a seperate layout that you can customise and use specifically for previewing your components. See the  ViewComponent [preview docs](https://viewcomponent.org/guide/previews.html) for instructions on how to set that up.
+
+Any `@display` params set at the preview (class) level with be merged with those set on individual example methods.
+
+#### Global display params
+
+Global (fallback) display params can be defined via a configuration option:
+
+```ruby
+# config/application.rb
+config.lookbook.preview_display_params = {
+  bg_color: "#fff",
+  max_width: "100%"
+}
+```
+
+Globally defined display params will be available to all previews. Any preview or example-level `@display` values with the same name will take precedence and override a globally-set one.
+
+#### Some `@display` value examples:
+
+Valid:
+
+```ruby
+# @display body_classes "bg-red border border-4 border-green"
+# @display wrap_in_container true
+# @display emojis_to_show 4
+# @display page_title "Special example title"
+```
+
+Invalid:
+
+```ruby
+# @display body_classes 'bg-red border border-4 border-green' [❌ single quotes]
+# @display wrap_in_container should_wrap [❌ unquoted string, perhaps trying to call a method]
+# @display page title "Special example title" [❌ space in key]
+# @display bg_color #fff [❌ colors need quotes around them, it's not CSS!]
+```
+
+### 🔖 `@!group <name> ... @!endgroup`
 
 For smaller components, it can often make sense to render a set of preview examples in a single window, rather than representing them as individual items in the navigation which can start to look a bit cluttered.
 
@@ -222,7 +310,7 @@ The example above would display the `Sizes` examples grouped together on a singl
 
 You can have as many groups as you like within a single preview class, but each example can only belong to one group.
 
-#### Adding notes
+### Adding notes
 
 All comment text other than tags will be treated as markdown and rendered in the **Notes** panel for that example in the Lookbook UI.
 

data/app/assets/lookbook/js/nav/node.js

@@ -14,6 +14,17 @@ export default function navNode() {
         ? Array.from(this.$refs.items.querySelectorAll(":scope > li"))
         : [];
     },
+    navigateToFirstChild() {
+      if (this.open()) {
+        const child = this.firstVisibleChild();
+        if (child) {
+          const link = child.querySelector(":scope > a.nav-link");
+          if (link) {
+            this.navigate(link.getAttribute("href"));
+          }
+        }
+      }
+    },
     filter() {
       this.hidden = true;
       this.getChildren().forEach((child) => {
@@ -27,5 +38,12 @@ export default function navNode() {
     toggle() {
       this.$store.nav.open[this.id] = !this.$store.nav.open[this.id];
     },
+    firstVisibleChild() {
+      return this.getChildren().find((child) => {
+        return child._x_dataStack
+          ? child._x_dataStack[0].hidden === false
+          : false;
+      });
+    },
   };
 }

data/app/controllers/lookbook/app_controller.rb

@@ -50,7 +50,7 @@ module Lookbook
     def find_preview
       candidates = []
       params[:path].to_s.scan(%r{/|$}) { candidates << $` }
-      match = candidates.detect { |candidate| Lookbook::Preview.exists?(candidate) }
+      match = candidates.reverse.detect { |candidate| Lookbook::Preview.exists?(candidate) }
       @preview = match ? Lookbook::Preview.find(match) : nil
     end
 
@@ -95,14 +95,29 @@ module Lookbook
             html: preview_controller.render_example_to_string(@preview, example.name)
           }
         end
-        joined = render_to_string "lookbook/preview_group", locals: {examples: examples}, layout: nil
-        preview_controller.render_in_layout_to_string(joined, @preview.lookbook_layout)
+        set_params
+        layout = @preview.lookbook_layout || Rails.configuration.view_component.default_preview_layout || current_layout
+        preview_controller.render_in_layout_to_string("lookbook/preview/group", {examples: examples}, layout)
       else
-        preview_controller.request.params[:path] = "#{@preview.preview_name}/#{@example.name}".chomp("/")
+        set_params(@example)
+        preview_controller.params[:path] = "#{@preview.preview_name}/#{@example.name}".chomp("/")
         preview_controller.process(:previews)
       end
     end
 
+    def set_params(example = nil)
+      example_params = example.nil? ? @preview.display_params : example.display_params
+      preview_controller.params.merge!({
+        lookbook: {
+          display: example_params
+        }
+      })
+    end
+
+    def current_layout
+      preview_controller.send :_layout, preview_controller.lookup_context, [:html]
+    end
+
     def assign_inspector
       @inspector = {
         panes: {

data/app/views/lookbook/nav/_leaf.html.erb

@@ -5,7 +5,7 @@ label ||= leaf.label
 %>
 <li x-data="navLeaf" :class="{hidden}" x-init="matchers = <%= leaf.matchers.to_json %>; path = '<%= path %>'; setActive()" @popstate.window="setActive">
   <a href="<%= path %>"
-    class="pr-3 py-[5px] flex items-center w-full group transition hover:bg-gray-200 hover:bg-opacity-50"
+    class="nav-link pr-3 py-[5px] flex items-center w-full group transition hover:bg-gray-200 hover:bg-opacity-50"
     style="<%= nav_padding_style(depth) %>"
     :class="{'!bg-indigo-100':active}"
     @click.stop.prevent="navigate"

data/app/views/lookbook/nav/_node.html.erb

@@ -8,7 +8,7 @@
       <svg class="feather h-3.5 w-3.5 mr-1.5 flex-none text-indigo-500">
         <use xlink:href="/lookbook-assets/feather-sprite.svg#<%= node.type == :preview ? 'layers' : 'folder' %>" />
       </svg>
-      <div class="truncate w-full whitespace-nowrap text-left <%= "font-bold" if node.type == :preview %>" @click.stop="toggle(); if (open()) { <%= "navigate('#{path}')" if defined?(path) %>}">
+      <div class="truncate w-full whitespace-nowrap text-left <%= "font-bold" if node.type == :preview %>" @click.stop="toggle(); navigateToFirstChild();">
         <%= node.label %>
       </div>
     </div>

data/app/views/lookbook/nav/_preview.html.erb

@@ -1,4 +1,4 @@
-<% examples = node.get_examples %>
+<% examples = node.get_examples.reject(&:hidden?) %>
 <% if examples.many? %>
   <%= render "nav/node", node: node, path: show_path(examples.first.path) do %>
     <% examples.each do |example| %>

data/app/views/lookbook/workbench/_inspector.html.erb

@@ -3,6 +3,7 @@
     <nav class="-mb-px flex space-x-8 cursor-auto">
       <% panes.each do |key, props| %>
         <a
+          id="inspector-tab-<%= key %>"
           href="#<%= key %>"
           class="whitespace-nowrap py-2 px-1 border-b-2 cursor-pointer <%= "!text-gray-300" if props[:disabled] %>"
           :class="{
@@ -23,7 +24,7 @@
         <% if props[:clipboard].present? %>
           <%= render "shared/clipboard" do %><%= h props[:clipboard].strip %><% end %>
         <% end %>
-        <div class="flex flex-col h-full overflow-auto">
+        <div id="inspector-content-<%= key %>" class="flex flex-col h-full overflow-auto">
           <%= render "workbench/inspector/#{props[:template]}", key: key, **props %>
         </div>
       </div>

data/lib/lookbook/engine.rb

@@ -30,6 +30,7 @@ module Lookbook
 
       options.preview_controller = vc_options.preview_controller if options.preview_controller.nil?
       options.preview_srcdoc = true if options.preview_srcdoc.nil?
+      options.preview_display_params ||= {}.with_indifferent_access
 
       options.listen_paths = options.listen_paths.map(&:to_s)
       options.listen_paths += options.preview_paths

data/lib/lookbook/parser.rb

@@ -27,6 +27,7 @@ module Lookbook
       def define_tags
         YARD::Tags::Library.define_tag("Hidden status", :hidden)
         YARD::Tags::Library.define_tag("Label", :label)
+        YARD::Tags::Library.define_tag("Display", :display)
       end
     end
   end

data/lib/lookbook/preview.rb

@@ -23,8 +23,8 @@ module Lookbook
       return @lookbook_examples if @lookbook_examples.present?
       public_methods = public_instance_methods(false)
       public_method_objects = code_object.meths.filter { |m| public_methods.include?(m.name) }
-      visible = public_method_objects.map { |m| PreviewExample.new(m.name.to_s, self) }.reject(&:hidden?)
-      sorted = Lookbook.config.sort_examples ? visible.sort_by(&:label) : visible
+      examples = public_method_objects.map { |m| PreviewExample.new(m.name.to_s, self) }
+      sorted = Lookbook.config.sort_examples ? examples.sort_by(&:label) : examples
       @lookbook_examples = []
       if code_object.groups.any?
         sorted.group_by { |m| m.group }.each do |name, examples|
@@ -78,6 +78,10 @@ module Lookbook
       defined?(@layout) ? @layout : nil
     end
 
+    def display_params
+      Lookbook.config.preview_display_params.deep_merge(lookbook_display_params)
+    end
+
     class << self
       def all
         ViewComponent::Preview.all.sort_by(&:label)

data/lib/lookbook/preview_controller.rb

@@ -14,9 +14,10 @@ module Lookbook
       render_to_string template, opts
     end
 
-    def render_in_layout_to_string(content, layout_override)
+    def render_in_layout_to_string(template, locals, layout_override = nil)
+      append_view_path Lookbook::Engine.root.join("app/views")
       layout = determine_layout(layout_override, prepend_views: false)[:layout]
-      render_to_string html: content, layout: layout
+      render_to_string template, locals: locals, layout: layout
     end
   end
 end

data/lib/lookbook/preview_example.rb

@@ -21,6 +21,10 @@ module Lookbook
       lookbook_label.presence || name.titleize
     end
 
+    def display_params
+      @preview.display_params.merge(lookbook_display_params)
+    end
+
     def method_source
       code_object.source.split("\n")[1..-2].join("\n").strip_heredoc
     end

data/lib/lookbook/preview_group.rb

@@ -26,6 +26,10 @@ module Lookbook
       :group
     end
 
+    def hidden?
+      false
+    end
+
     def matchers
       [@preview.label, label].map { |m| m.gsub(/\s/, "").downcase }
     end

data/lib/lookbook/taggable.rb

@@ -20,6 +20,23 @@ module Lookbook
       code_object&.group
     end
 
+    def lookbook_display_params
+      display_params = {}.with_indifferent_access
+      if code_object&.tags(:display).present?
+        code_object.tags(:display).each do |tag|
+          parts = tag.text.strip.match(/^([^\s]*)\s?(.*)$/)
+          if parts.present?
+            begin
+              display_params[parts[1]] = JSON.parse parts[2]
+            rescue JSON::ParserError => err
+              Rails.logger.error("\n👀 [Lookbook] Invalid JSON in @display tag.\n👀 [Lookbook] (#{err})\n")
+            end
+          end
+        end
+      end
+      display_params
+    end
+
     # private
 
     def code_object

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "0.3.4"
+  VERSION = "0.4.1"
 end

data/lib/tasks/lookbook_tasks.rake

@@ -11,5 +11,10 @@ namespace :lookbook do
       contents = file.read
       File.write(filename, contents.gsub(current_version, new_version))
     end
+
+    desc "Build Gem and push to RubyGems"
+    task :build_and_push do
+      sh("rake build && gem push pkg/lookbook-#{Lookbook::VERSION}.gem")
+    end
   end
 end

data/public/lookbook-assets/app.css

@@ -1,4 +1,4 @@
-/*! tailwindcss v2.2.7 | MIT License | https://tailwindcss.com */
+/*! tailwindcss v2.2.17 | MIT License | https://tailwindcss.com */
 
 /*! modern-normalize v1.1.0 | MIT License | https://github.com/sindresorhus/modern-normalize */
 
@@ -475,6 +475,18 @@ button,
   cursor: pointer;
 }
 
+/**
+ * Override legacy focus reset from Normalize with modern Firefox focus styles.
+ *
+ * This is actually an improvement over the new defaults in Firefox in our testing,
+ * as it triggers the better focus styles even for links, which still use a dotted
+ * outline in Firefox by default.
+ */
+
+:-moz-focusring {
+  outline: auto;
+}
+
 table {
   border-collapse: collapse;
 }
@@ -627,6 +639,7 @@ video {
   padding-left: 0.75rem;
   font-size: 1rem;
   line-height: 1.5rem;
+  --tw-shadow: 0 0 #0000;
 }
 
 [type='text']:focus, [type='email']:focus, [type='url']:focus, [type='password']:focus, [type='number']:focus, [type='date']:focus, [type='datetime-local']:focus, [type='month']:focus, [type='search']:focus, [type='tel']:focus, [type='time']:focus, [type='week']:focus, [multiple]:focus, textarea:focus, select:focus {
@@ -638,7 +651,7 @@ video {
   --tw-ring-color: #2563eb;
   --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
   --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);
-  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000);
+  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
   border-color: #2563eb;
 }
 
@@ -706,6 +719,7 @@ select {
   background-color: #fff;
   border-color: #6b7280;
   border-width: 1px;
+  --tw-shadow: 0 0 #0000;
 }
 
 [type='checkbox'] {
@@ -725,7 +739,7 @@ select {
   --tw-ring-color: #2563eb;
   --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
   --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);
-  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000);
+  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
 }
 
 [type='checkbox']:checked,[type='radio']:checked {
@@ -2023,6 +2037,7 @@ pre[class*="language-"] {
   border-radius:4px;
   font-size:14px;
   line-height:1.4;
+  white-space:normal;
   outline:0;
   transition-property:transform,visibility,opacity
 }