lookbook 0.4.1 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6556e23e693e27f706b4989f25c13c75a453ce5582e835e6c380a226840feff8
-  data.tar.gz: c28f4d88136a02522fb23adc826ec1066c0800ef6a223451149b4516448d318c
+  metadata.gz: 676b8a78237532971ec7d22d7265b3da7d3b896aa8020d7ab1c514edc3859b45
+  data.tar.gz: dfb016bf927d7492afdeacd3b10a2425563e227b5cbd4ebd4d3f7a5bfa97609f
 SHA512:
-  metadata.gz: 92076777e5a0e2ca449eec799a4702965bc78c12ae1d48f0a7de9276832f02b320f25ecc5384d56aeb5138a953b26a8251ad44756d6a36a58c7fbe84255078e4
-  data.tar.gz: e840534cd52b19c9db2b39316739b7ee8df820c96837f59cfd03e96fe99d90778eddc5518ffc5ac0167f61e27f74a2fafaa83642eb7697fd433d34cd09f28550
+  metadata.gz: 2e5aeb26c2db3322e7aa127e176b691744d5af3cfbd207159f65d0e9dee1362382f418b07bda2fa7b75d7f85b35f522efe106707e665c6e12f9ab5e4ca1f4cd1
+  data.tar.gz: be2908ed45f9645dd9387adf6547c8c45ba262310325438197de22d6db9909705fa3e45de0912914004d516c4546618ccc73fd96fea3fbdc86f2affa5e7ebb3d

data/README.md

@@ -28,6 +28,7 @@ Lookbook uses [RDoc/Yard-style comment tags](#annotating-preview-files) to exten
 - Auto-updating UI when component or preview files are updated _(Rails v6.0+ only)_
 - Use comment tag annotations for granular customisation of the preview experience
 - Fully compatible with standard the ViewComponent preview system
+- [**Experimental**] In-browser live editable preview parameters (similar to Storybook Controls/Knobs)
 
 ## Lookbook demo
 
@@ -76,7 +77,7 @@ Lookbook parses [Yard-style comment tags](https://rubydoc.info/gems/yard/file/do
 
 ```ruby
 # @label Basic Button
-# @display bg_color "#fff"
+# @display bg_color #fff
 class ButtonComponentPreview < ViewComponent::Preview
 
   # Primary button
@@ -90,11 +91,24 @@ class ButtonComponentPreview < ViewComponent::Preview
     end
   end
 
+  # Button with icon
+  # ----------------
+  # This example uses dynamic preview parameters
+  # which can be edited live in the Lookbook UI 
+  #
+  # @param text
+  # @param icon select [heart, cog, alert]
+  def icon(text: "Spread the love", icon: "heart")
+    render ButtonComponent.new(icon: icon) do
+      text
+    end
+  end
+
   # Inverted button
   # ---------------
   # For light-on-dark screens
   #
-  # @display bg_color "#000"
+  # @display bg_color #000
   def secondary
     render ButtonComponent.new(style: :inverted) do
       "Click me"
@@ -141,54 +155,41 @@ end
 
 The following Lookbook-specific tags are available for use:
 
-* `@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`](#label-tag)
+* [`@display`](#display-tag)
+* [`@!group ... @!endgroup`](#group-tag)
+* [`@hidden`](#hidden-tag)
+* [`@param`](#param-tag) [⚠️ **experimental!** - requires [feature opt-in](#experimental-features) ⚠️]
 
-### 🔖 `@label <text>`
+<h3 id="label-tag">🏷 @label</h3>
 
 Used to replace the auto-generated navigation label for the item with `<text>`.
 
-> Available for preview classes & example methods.
-
 ```ruby
-# @label Preview Label
-class FooComponentPreview < ViewComponent::Preview
-
-  # @label Example Label
-  def default
-  end
-end
+@label <text>
 ```
 
-### 🔖 `@hidden`
-
-Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
-
-Can be useful when a component (or a variant of a component) is still in development and is not ready to be shared with the wider team.
-
-> Available for both preview classes & example methods.
+> Available for preview classes & example methods.
 
 ```ruby
-# @hidden
+# @label Preview Label
 class FooComponentPreview < ViewComponent::Preview
 
-  # @hidden
+  # @label Example Label
   def default
   end
 end
 ```
 
-### 🔖 `@display <key> <value>`
+<h3 id="display-tag">🏷 @display</h3>
 
 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"
+# @display bg_color #eee
 class FooComponentPreview < ViewComponent::Preview
 
-  # @display max_width "500px"
+  # @display max_width 500px
   # @display wrapper true
   def default
   end
@@ -198,13 +199,11 @@ 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>
+@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.
+- `<value>` will be parsed using the [Ruby YAML parser](https://yaml.org/YAML_for_ruby.html) to resolve the value
 
 These display parameters can then be accessed via the `params` hash in your preview layout using `params[:lookbook][:display][<key>]`:
 
@@ -244,27 +243,7 @@ config.lookbook.preview_display_params = {
 
 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`
+<h3 id="group-tag">🔖 `@!group ... @!endgroup`</h3>
 
 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.
 
@@ -310,6 +289,167 @@ 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.
 
+<h3 id="hidden-tag">🏷 `@hidden`</h3>
+
+Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
+
+Can be useful when a component (or a variant of a component) is still in development and is not ready to be shared with the wider team.
+
+> Available for both preview classes & example methods.
+
+```ruby
+# @hidden
+class FooComponentPreview < ViewComponent::Preview
+
+  # @hidden
+  def default
+  end
+end
+```
+
+<h3 id="param-tag"> 🚧 @param (experimental)</h3>
+
+> ⚠️ This feature is currently flagged as an **experimental** feature which requires [feature opt-in](#experimental-features) to use. Its API and implementation may change in the future.
+
+The `@param` tag provides the ability to specify **editable preview parameters** which can be changed in the Lookbook UI in order to customise the rendered output on the fly, much like the [Controls (knobs) addon](https://storybook.js.org/addons/@storybook/addon-controls) for Storybook.
+
+Each `@param` will have an associated form field generated for it. The values for each field will be handled as [dynamic preview params](https://viewcomponent.org/guide/previews.html#:~:text=It%E2%80%99s%20also%20possible%20to%20set%20dynamic%20values%20from%20the%20params%20by%20setting%20them%20as%20arguments%3A) when rendering the example.
+
+The `@param` tag takes the following format:
+
+```ruby
+@param <name> <input_type> <opts?>
+```
+
+- `<name>` - name of the dynamic preview param
+- `<input_type>` - input field type to generate in the UI 
+- `<opts?>` - YAML-encoded field options, used for some field types
+
+#### Input types
+
+The following **input field types** are available for use:
+
+📝 **Text-style inputs** - Single line fields, useful for short strings of text or numbers.
+
+```ruby
+@param <name> text
+@param <name> email
+@param <name> number
+@param <name> url
+@param <name> tel
+```
+
+> The above types only differ in the validation constraints they impose on the input field.
+
+📝 **Textarea** - Multi-line textarea field for longer-form content.
+
+```ruby
+@param <name> textarea
+```
+
+📝 **Select box** - Dropdown select field for selecting from a list of known options.
+
+```ruby
+@param <name> select <options>
+```
+
+`<options>` should be a [YAML array](https://yaml.org/YAML_for_ruby.html#simple_inline_array) of options which must be formatted in the same style as the input for Rails' [`options_for_select`](https://apidock.com/rails/v6.0.0/ActionView/Helpers/FormOptionsHelper/options_for_select) helper: 
+
+```ruby
+# Basic options:
+# @param theme select [primary, secondary, danger]
+
+# With custom labels (each item itself an array of [label, value]):
+# @param theme select [[Primary theme, primary], [Secondary theme, secondary], [Danger theme, danger]]
+
+# With empty option (`~` in YAML)
+# @param theme select [~, primary, secondary, danger]
+```
+
+> **Note**: In most cases YAML does not require quoting of strings, however if you are running into issues check out the [Ruby YAML docs](https://yaml.org/YAML_for_ruby.html) for a complete syntax reference.
+
+📝 **Toggle** - On/off switch for toggling boolean values.
+
+```ruby
+@param <name> toggle
+```
+
+#### Default values
+
+Default values are specified as part of the preview example method parameters in the usual Ruby way:
+
+```ruby
+def button(content: "Click me", theme: "primary", arrow: false)
+  # ...
+end
+```
+
+These will be used as the default values for the param fields.
+
+> Note that the default values are **not** evaluated at runtime, so you cannot use method calls to generate the defaults. Only static default values are supported.
+
+#### Type casting values
+
+Most dynamic param values are passed to the example method as strings, with the following exceptions:
+
+- `toggle` input - values are cast to booleans
+- `number` input - values are cast to integers
+
+In some cases, you may want to type cast the parameter value to something else (for example a `Symbol`) before using it when initializing the component.
+
+To help with this, a `type` option can be specified in the `@param` definition to automatically cast the dynamic value to a different type:
+
+```ruby
+# @param <name> [<type>] <input_type> <opts?>
+```
+
+In the example below, the value of the `theme` param (by default a string) will be automatically cast to a Symbol, ready for use in instantiating the component.
+
+```ruby
+# @param theme [Symbol] select [primary, secondary, danger]
+def default(theme: :primary)
+  render Elements::ButtonComponent.new(theme: theme) do
+    "Click me"
+  end
+end
+```
+
+The supported types to cast to are:
+
+- `String` - *default for all except `toggle` inputs*
+- `Boolean` - *default for `toggle` inputs*
+- `Symbol`
+- `Date`
+- `DateTime`
+- `Integer`
+- `Float`
+
+The following structured types are also available but should be considered **experimental** - you may run into bugs!
+
+- `Hash` - *value string converted to Hash using the Ruby YAML parser*
+- `Array` - *value string converted to Array using the Ruby YAML parser*
+
+#### Full example:
+
+```ruby
+class ButtonComponentPreview < ViewComponent::Preview
+  
+  # The params defined below will be editable in the UI:
+  #
+  # @param content text
+  # @param theme select [primary, secondary, danger]
+  # @param arrow toggle
+  def default(content: "Click me", theme: "primary", arrow: true)
+    render Elements::ButtonComponent.new(theme: theme, arrow: arrow) do
+      content
+    end
+  end
+
+end
+```
+
+<img src=".github/assets/dynamic_params.png">
+
 ### 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.
@@ -352,6 +492,33 @@ If you wish to add additional paths to listen for changes in, you can use the `l
 config.lookbook.listen_paths << Rails.root.join('app/other/directory')
 ```
 
+<h3 id="experimental-features">Experimental features opt-in</h3>
+
+Some features may occasionally be released behind a 'experimental' feature flag while they are being tested and refined, to allow people to try them out and provide feedback.
+
+> ⚠️ **Please note:** Experimental features should be considered to be **subject to extensive change** and breaking changes to them may be made within point releases - these features are **not** considered to be covered by [semver](https://semver.org/) whilst flagged as 'experimental'. ⚠️
+
+#### Opting into specific features (recommended)
+
+To opt into individual experimental features, include the name of the feature in the `experimental_features` config option:
+
+```ruby
+config.lookbook.experimental_features = ["feature_name"]
+```
+
+The current experimental features that can be opted into are:
+
+- `params`: Live-editable, dynamic preview parameters ([read more](#param-tag)). Include `"params"` in the `experimental_features` config option to opt in. 
+
+#### Opting into all experimental features (not recommended!)
+
+If you want to live life on the bleeding-edge you can opt-in to all current **and future** experimental features (usual caveats apply):
+
+```ruby
+config.lookbook.experimental_features = true
+```
+
+
 ## Keyboard shortcuts
 
 Lookbook provides a few keyboard shortcuts to help you quickly move around the UI.

data/app/assets/lookbook/css/app.css

@@ -35,14 +35,6 @@
     fill: none;
   }
 
-  .h-fill {
-    height: fill-available;
-  }
-
-  .min-h-fill {
-    min-height: fill-available;
-  }
-
   ::-webkit-scrollbar {
     width: 8px;
     height: 8px;
@@ -63,3 +55,17 @@
     @apply bg-gray-400;
   }
 }
+
+@layer utilities {
+  .h-fill {
+    height: fill-available;
+  }
+
+  .min-h-fill {
+    min-height: fill-available;
+  }
+
+  .form-input {
+    @apply border-gray-300 text-gray-700 focus:ring-indigo-300 focus:border-indigo-300 rounded-sm text-sm w-full;
+  }
+}

data/app/assets/lookbook/js/app.js

@@ -9,6 +9,7 @@ import page from "./page";
 import workbench from "./workbench";
 import preview from "./workbench/preview";
 import inspector from "./workbench/inspector";
+import param from "./workbench/param";
 import nav from "./nav";
 import navNode from "./nav/node";
 import navLeaf from "./nav/leaf";
@@ -56,6 +57,7 @@ Alpine.data("navLeaf", navLeaf);
 Alpine.data("workbench", workbench);
 Alpine.data("preview", preview);
 Alpine.data("inspector", inspector);
+Alpine.data("param", param);
 Alpine.data("clipboard", clipboard);
 Alpine.data("sizeObserver", sizeObserver);
 Alpine.data("split", split);

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

@@ -22,13 +22,12 @@ export default function () {
       });
     },
     navigate(path) {
-      if (path instanceof Event) {
-        path = path.currentTarget.href;
-      }
-      history.pushState({}, null, path);
-      this.$dispatch("popstate");
+      this.navigateTo(path instanceof Event ? path.currentTarget.href : path);
     },
-    focusFilter() {
+    focusFilter($event) {
+      if ($event.target.tagName === "INPUT") {
+        return;
+      }
       this.currentFocus = this.$refs.filter;
       setTimeout(() => this.$refs.filter.focus(), 0);
     },

data/app/assets/lookbook/js/page.js

@@ -27,7 +27,12 @@ export default function page() {
     render() {
       if (this.ready) {
         morph(this.$el, store.doc.getElementById(this.$el.id));
+        this.$dispatch("document:patched");
       }
     },
+    navigateTo(path) {
+      history.pushState({}, null, path);
+      this.$dispatch("popstate");
+    },
   };
 }

data/app/assets/lookbook/js/utils/morph.js

@@ -9,6 +9,9 @@ export default function (from, to, opts = {}) {
       if (fromEl.isEqualNode(toEl)) {
         return false;
       }
+      if (fromEl.hasAttribute("skip-morph")) {
+        return false;
+      }
       return true;
     },
     ...opts,

data/app/assets/lookbook/js/workbench/param.js

@@ -0,0 +1,19 @@
+export default function param() {
+  return {
+    focused: false,
+    setFocus() {
+      if (this.focused && this.$el.focus) {
+        this.$el.focus();
+      }
+    },
+    update(name, value) {
+      const searchParams = new URLSearchParams(window.location.search);
+      searchParams.set(name, value);
+      const path = location.href.replace(location.search, "");
+      this.navigateTo(`${path}?${searchParams.toString()}`);
+    },
+    validate() {
+      return this.$el.reportValidity ? this.$el.reportValidity() : true;
+    },
+  };
+}

data/app/controllers/lookbook/app_controller.rb

@@ -8,7 +8,7 @@ module Lookbook
     prepend_view_path File.expand_path("../../views/lookbook", __dir__)
 
     layout "layouts/app"
-    helper Lookbook::Engine.helpers
+    helper Lookbook::ApplicationHelper
 
     before_action :find_preview, only: [:preview, :show]
     before_action :find_example, only: [:preview, :show]
@@ -96,8 +96,7 @@ module Lookbook
           }
         end
         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)
+        preview_controller.render_in_layout_to_string("lookbook/preview/group", {examples: examples}, @preview.lookbook_layout)
       else
         set_params(@example)
         preview_controller.params[:path] = "#{@preview.preview_name}/#{@example.name}".chomp("/")
@@ -106,6 +105,15 @@ module Lookbook
     end
 
     def set_params(example = nil)
+      if example.present? && enabled?(:params)
+        # cast known params to type
+        example.params.each do |param|
+          if preview_controller.params.key?(param[:name])
+            preview_controller.params[param[:name]] = Lookbook::Params.cast(preview_controller.params[param[:name]], param[:type])
+          end
+        end
+      end
+      # set display params
       example_params = example.nil? ? @preview.display_params : example.display_params
       preview_controller.params.merge!({
         lookbook: {
@@ -114,10 +122,6 @@ module Lookbook
       })
     end
 
-    def current_layout
-      preview_controller.send :_layout, preview_controller.lookup_context, [:html]
-    end
-
     def assign_inspector
       @inspector = {
         panes: {
@@ -144,6 +148,15 @@ module Lookbook
           }
         }
       }
+      if enabled?(:params)
+        @inspector[:panes][:params] = {
+          label: "Params",
+          template: "params",
+          hotkey: "p",
+          items: @source.many? ? [] : @example.params,
+          disabled: @source.many? || @example.params.none?
+        }
+      end
     end
 
     def assign_nav
@@ -179,5 +192,9 @@ module Lookbook
       controller.response = response
       @preview_controller ||= controller
     end
+
+    def enabled?(feature)
+      Lookbook::Features.enabled?(feature)
+    end
   end
 end

data/app/helpers/lookbook/application_helper.rb

@@ -8,7 +8,12 @@ module Lookbook
     end
 
     def markdown(text)
-      Markdown.new(text).to_html.html_safe
+      markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, {
+        tables: true,
+        fenced_code_blocks: true,
+        disable_indented_code_blocks: true
+      })
+      markdown.render(text).html_safe
     end
 
     def highlight(source, language)

data/app/helpers/lookbook/preview_helper.rb

@@ -0,0 +1,7 @@
+module Lookbook
+  module PreviewHelper
+    def lookbook_display(key, fallback = nil)
+      params[:lookbook][:display][key.to_sym] || fallback
+    end
+  end
+end

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

@@ -20,7 +20,12 @@
   </div>
   <div class="flex-auto overflow-auto bg-gray-50">
     <% panes.each do |key, props| %>
-      <div class="flex flex-col h-full relative" x-show="active('<%= key %>')" x-cloak>
+      <div class="flex flex-col h-full relative" x-show="active('<%= key %>')" x-effect="
+        if ($store.inspector.active === '<%= key %>') {
+          const input = $el.querySelector('[data-param-input]');
+          if (input) setTimeout(() => input.focus(), 0)
+        }
+      " x-cloak>
         <% if props[:clipboard].present? %>
           <%= render "shared/clipboard" do %><%= h props[:clipboard].strip %><% end %>
         <% end %>

data/app/views/lookbook/workbench/inspector/_params.html.erb

@@ -0,0 +1,28 @@
+<% if @example.type == :group %>
+  <div class="p-4 prose prose-sm">
+    <em class='opacity-50'>Params are not supported for grouped previews.</em>
+  </div>
+<% elsif items.none? %>
+  <div class="p-4 prose prose-sm">
+    <em class='opacity-50'>No params configured.</em>
+  </div>
+<% else %>
+  <div class="py-3">
+    <% items.each do |param| %>
+      <div class="px-4 py-3" x-data="param" @document:patched="setFocus">
+        <div class="flex items-start max-w-[800px]">
+          <div class="w-[200px] flex-none py-2">
+            <label for="param-<%= param[:name] %>" class="font-bold"><%= param[:name].titleize %></label>
+          </div>
+          <div class="flex-grow" @focus="focussed = true" @blur="focussed = false">
+            <%= render "workbench/inspector/params/#{param[:input]}",
+              **param,
+              value: params.key?(param[:name]) ? params[param[:name]] : param[:default],
+              id: "#{@example.id}-param-#{param[:name]}"
+            %>
+          </div>
+        </div>
+      </div>
+    <% end %>
+  </div>
+<% end %>

data/app/views/lookbook/workbench/inspector/params/_select.html.erb

@@ -0,0 +1,8 @@
+<select
+  name="<%= name %>"
+  id="<%= id %>"
+  class="form-input"
+  @change.stop="update($el.name, $el.value)"
+  data-param-input>
+  <%= options_for_select(options, value) %>
+</select>

data/app/views/lookbook/workbench/inspector/params/_text.html.erb

@@ -0,0 +1,8 @@
+<input
+  id="<%= id %>"
+  class="form-input"
+  type="<%= input_type %>"
+  name="<%= name %>"
+  value="<%= value %>"
+  @keyup.stop.debounce.400="if (validate()) update($el.name, $el.value)"
+  data-param-input>

data/app/views/lookbook/workbench/inspector/params/_textarea.html.erb

@@ -0,0 +1,8 @@
+<textarea
+  id="<%= id %>"
+  class="form-input"
+  name="<%= name %>"
+  rows="4"
+  @keyup.stop.debounce.300="update($el.name, $el.value)"
+  data-param-input
+><%= value %></textarea>

data/app/views/lookbook/workbench/inspector/params/_toggle.html.erb

@@ -0,0 +1,13 @@
+<div id="<%= id %>" x-init="checked = <%= value == "true" ? "true" : "false" %>" data-param-input>
+  <button type="button"
+    class="relative inline-flex flex-shrink-0 h-6 w-11 border-2 border-transparent rounded-full cursor-pointer transition-colors ease-in-out duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-400"
+    :class="{'bg-indigo-500': checked, 'bg-gray-300': !checked}"
+    role="switch"
+    @click.stop="checked = !checked; update('<%= name %>', checked)">
+    <span
+      aria-hidden="true"
+      class="pointer-events-none inline-block h-5 w-5 rounded-full bg-white shadow transform ring-0 transition ease-in-out duration-200"
+      :class="{'translate-x-5': checked, 'translate-x-0': !checked}"
+    ></span>
+  </button>
+</div>