lookbook 0.3.5 → 0.4.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d2f6afc23ec83a6ed2c19314540d26f83406da564385337fe29f9769253a432
-  data.tar.gz: bc239282a1bbbca50a72da683e270efafd60f515cf59a9b56ffc98b73f5e53a6
+  metadata.gz: 870ef6a17d84bca0a9fbbc421e27c2d6d682965d96c646f44d3db817e5a5e4f2
+  data.tar.gz: 669ce3b709792be5bdf46ac806efdca269d694349e74f759b0997cbbb456792e
 SHA512:
-  metadata.gz: '08d4cf77cc06512be08c1f1baf567b55ac4e8d0328281896ddb2dd7381051b9ed538e8c2333a4437629cfc3e7852f5398672d013a271cacfae4dad0bc8769d97'
-  data.tar.gz: b748d37275d69d82522b7e7746d31ed54d296dac939c5610d3559834207fc0488d682ee86b161c42418af71a80eaee79ec10f16cd276b4d510a87e3446379253
+  metadata.gz: b0293806f0d57b130c07ae84b5d30fad2625df0cbf2477303d924dddfd42ece6e49b10f15fc0b395fa65adfca3de3ab1096e72565a175bdab14df2af1ba57050
+  data.tar.gz: 2e5ad4ca7957d2684dc367b3a7d89d9922024cfc01cdbcd2567d30b830fe891b815924d64f5b7048783efd42736f41924354255f847850498fd596ba1c25e977

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.reverse.detect { |candidate| Lookbook::Preview.exists?(candidate) }
+      match = candidates.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
+        set_params
         joined = render_to_string "lookbook/preview_group", locals: {examples: examples}, layout: nil
-        preview_controller.render_in_layout_to_string(joined, @preview.lookbook_layout)
+        preview_controller.render_in_layout_to_string(joined, @preview.lookbook_layout || current_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 = @preview.lookbook_display_params.deep_merge(example ? example.lookbook_display_params : {})
+      preview_controller.params.merge!({
+        lookbook: {
+          display: Lookbook.config.preview_display_params.deep_merge(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/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 ||= {}
 
       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/taggable.rb

@@ -20,6 +20,23 @@ module Lookbook
       code_object&.group
     end
 
+    def lookbook_display_params
+      display_params = {}
+      if code_object&.tags(:display).present?
+        code_object.tags(:display).each do |tag|
+          parts = tag.text.match(/^\s?([^:]*)\s?:\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.to_s})\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.5"
+  VERSION = "0.4.0.beta.1"
 end

data/public/lookbook-assets/app.js

@@ -8523,6 +8523,17 @@ Expression: "${expression}"
       getChildren() {
         return this.$refs.items ? 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) => {
@@ -8535,6 +8546,11 @@ Expression: "${expression}"
       },
       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;
+        });
       }
     };
   }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lookbook
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0.beta.1
 platform: ruby
 authors:
 - Mark Perkins
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-21 00:00:00.000000000 Z
+date: 2021-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -259,9 +259,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.1.2
 signing_key: