lookbook 0.4.2 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea3c9193679ce30a8af8657a1c02c78f7651a54aeffcb67f1a64585f7ad6b6cc
-  data.tar.gz: df6c3467fb9d9414efabb6b8939df401629c3540ba77640f23177303f7e2a615
+  metadata.gz: 93eda55ac8a014e5027a7a1176653a8ecbf9f1b5a95b26820c68ef93f2402269
+  data.tar.gz: c5a4dde94d4ce0c84298dfe5d8592d3ccaf887fe56fa21a9cb0bbc78b797604f
 SHA512:
-  metadata.gz: c2df05db3f8a2f88fd3099e49ec6c2b510b16008f6c45f13e82c1bf6f2959e18ab68a0fdde304743ec5da00e6eb5c00de64de78f8c0e36bc410ab5577676076a
-  data.tar.gz: 4c6814008e6e8360cdb6e6592e099e26fc74df31840bb9fba2569984c0a019284b0c7f4a3f0c27e186697ef0425d94f7d6940dee5a00461a6009dc49c2f43ab6
+  metadata.gz: 704265eb0b3c0b15417b47446ac900f14ca3bf746f9bbbabbbeb563eefe672f907d01ebbe5ab70d77633235d228ca509738826d674035528b12a0eb96dfcfa17
+  data.tar.gz: 562c86882d1a2da3eb06b660006dc3d37223c80273d9aaaacafb9a85ee8a009081eecd1acfd8d451e850d34b4055400b9d9e8e5d452f7dcc66c2428a3928db7d

data/README.md

@@ -28,12 +28,15 @@ 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
 
 If you want to have a quick play with Lookbook, the easiest way is to [give the demo app](https://github.com/allmarkedup/lookbook-demo) a spin. It's a basic Rails/ViewComponent app with a few test components included to tinker with.
 
-The [demo app repo](https://github.com/allmarkedup/lookbook-demo) contains instructions on how to get it up and running.
+**Online demo: https://lookbook-demo-app.herokuapp.com/lookbook**
+
+If you'd rather dig in a bit more and run the demo app locally, the [demo repo](https://github.com/allmarkedup/lookbook-demo) contains instructions on how to get it up and running.
 
 ## Installing
 
@@ -76,7 +79,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 +93,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 +157,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 +201,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 +245,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 +291,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 +494,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]
@@ -105,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: {
@@ -139,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
@@ -174,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 || 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>

data/lib/lookbook/engine.rb

@@ -8,6 +8,10 @@ module Lookbook
     def config
       @config ||= Engine.config.lookbook
     end
+
+    def logger
+      @logger ||= config.debug == true ? Rails.logger : Lookbook::NullLogger.new
+    end
   end
 
   class Engine < Rails::Engine
@@ -35,6 +39,8 @@ module Lookbook
       options.listen_paths = options.listen_paths.map(&:to_s)
       options.listen_paths += options.preview_paths
       options.listen_paths << (vc_options.view_component_path || Rails.root.join("app/components"))
+
+      options.experimental_features = false unless options.experimental_features.present?
     end
 
     initializer "lookbook.cable.config" do |app|

data/lib/lookbook/features.rb

@@ -0,0 +1,24 @@
+module Lookbook
+  module Features
+    EXPERIMENTAL_FEATURES = [:params]
+
+    def self.experimental_feature?(name)
+      EXPERIMENTAL_FEATURES.include?(name.to_sym)
+    end
+
+    def self.enabled?(name)
+      return true unless experimental_feature?(name)
+      enabled.include?(name.to_sym)
+    end
+
+    def self.enabled
+      if Lookbook.config.experimental_features == true
+        EXPERIMENTAL_FEATURES
+      elsif Lookbook.config.experimental_features.blank?
+        []
+      else
+        Lookbook.config.experimental_features.map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/lookbook/params.rb

@@ -0,0 +1,110 @@
+module Lookbook
+  module Params
+    class << self
+      def build_param(param, default)
+        input, options_str = param.text.present? ? param.text.split(" ", 2) : [nil, ""]
+        type = param.types&.first
+        options = YAML.safe_load(options_str || "~")
+        input ||= guess_input(type, default)
+        type ||= guess_type(input, default)
+        {
+          name: param.name,
+          input: input_text?(input) ? "text" : input,
+          input_type: (input if input_text?(input)),
+          options: options,
+          type: type,
+          default: default
+        }
+      end
+
+      def parse_method_param_str(param_str)
+        return nil if param_str[0].nil? || param_str[1].nil?
+        name = param_str[0].chomp(":")
+        value = param_str[1]&.strip
+        value = case value
+        when "nil"
+          nil
+        else
+          if value&.first == ":"
+            value.delete_prefix(":").to_sym
+          else
+            YAML.safe_load(value)
+          end
+        end
+        [name, value]
+      end
+
+      def cast(value, type = "String")
+        case type.downcase
+        when "symbol"
+          value.delete_prefix(":").to_sym
+        when "hash"
+          result = safe_parse_yaml(value, {})
+          unless result.is_a? Hash
+            Lookbook.logger.debug "Failed to parse '#{value}' into a Hash"
+            result = {}
+          end
+          result
+        when "array"
+          result = safe_parse_yaml(value, [])
+          unless result.is_a? Array
+            Lookbook.logger.debug "Failed to parse '#{value}' into an Array"
+            result = []
+          end
+          result
+        else
+          begin
+            type_class = "ActiveModel::Type::#{type}".constantize
+            type_class.new.cast(value)
+          rescue NameError
+            raise ArgumentError, "'#{type}' is not a valid param type to cast to."
+          end
+        end
+      end
+
+      private
+
+      def guess_input(type, default)
+        if type&.downcase == "boolean" || (type.blank? && boolean?(default))
+          "toggle"
+        else
+          "text"
+        end
+      end
+
+      def guess_type(input, default)
+        if input&.downcase == "toggle"
+          "Boolean"
+        elsif input&.downcase == "number"
+          "Integer"
+        elsif boolean?(default)
+          "Boolean"
+        elsif default.is_a? Symbol
+          "Symbol"
+        else
+          "String"
+        end
+      end
+
+      def input_text?(input)
+        [
+          "email",
+          "number",
+          "tel",
+          "text",
+          "url"
+        ].include? input
+      end
+
+      def safe_parse_yaml(value, fallback)
+        value.present? ? YAML.safe_load(value) : fallback
+      rescue Psych::SyntaxError
+        fallback
+      end
+
+      def boolean?(value)
+        value == true || value == false
+      end
+    end
+  end
+end

data/lib/lookbook/parser.rb

@@ -5,7 +5,7 @@ module Lookbook
     YARDOC_FILE_PATH = Rails.root.join("tmp/storage/.yardoc").to_s
 
     def initialize(paths)
-      @paths = paths.map { |p| "#{p}/**/*_preview.rb" }
+      @paths = paths.map { |p| "#{p}/**/*preview.rb" }
       YARD::Registry.yardoc_file = YARDOC_FILE_PATH
     end
 

data/lib/lookbook/preview.rb

@@ -71,7 +71,7 @@ module Lookbook
     end
 
     def lookbook_id
-      lookbook_path.tr("_", "-")
+      lookbook_path.tr("/", "-").tr("_", "-")
     end
 
     def lookbook_layout

data/lib/lookbook/preview_example.rb

@@ -10,7 +10,7 @@ module Lookbook
     end
 
     def id
-      path.underscore.tr("_", "-")
+      path.underscore.tr("/", "-").tr("_", "-")
     end
 
     def path
@@ -25,6 +25,12 @@ module Lookbook
       @preview.display_params.merge(lookbook_display_params)
     end
 
+    def params
+      @params || code_object&.tags("param")&.map do |param|
+        Lookbook::Params.build_param(param, parameter_defaults[param.name])
+      end
+    end
+
     def method_source
       code_object.source.split("\n")[1..-2].join("\n").strip_heredoc
     end
@@ -55,6 +61,12 @@ module Lookbook
 
     private
 
+    def parameter_defaults
+      @parameter_defaults || code_object&.parameters&.map do |param_str|
+        Lookbook::Params.parse_method_param_str(param_str)
+      end&.compact&.to_h
+    end
+
     def taggable_object_path
       "#{@preview.name}##{name}"
     end

data/lib/lookbook/preview_group.rb

@@ -11,7 +11,7 @@ module Lookbook
     end
 
     def id
-      path.underscore.tr("_", "-")
+      path.underscore.tr("/", "-").tr("_", "-")
     end
 
     def path
@@ -26,6 +26,10 @@ module Lookbook
       :group
     end
 
+    def params
+      []
+    end
+
     def hidden?
       false
     end

data/lib/lookbook/taggable.rb

@@ -27,8 +27,8 @@ module Lookbook
           parts = tag.text.strip.match(/^([^\s]*)\s?(.*)$/)
           if parts.present?
             begin
-              display_params[parts[1]] = JSON.parse parts[2]
-            rescue JSON::ParserError => err
+              display_params[parts[1]] = YAML.safe_load(parts[2] || "~")
+            rescue SyntaxError => err
               Rails.logger.error("\n👀 [Lookbook] Invalid JSON in @display tag.\n👀 [Lookbook] (#{err})\n")
             end
           end

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "0.4.2"
+  VERSION = "0.4.6"
 end

data/lib/lookbook.rb

@@ -5,6 +5,8 @@ module Lookbook
   extend ActiveSupport::Autoload
 
   autoload :Lang, "lookbook/lang"
+  autoload :Params, "lookbook/params"
+  autoload :Features, "lookbook/features"
   autoload :Collection, "lookbook/collection"
   autoload :Parser, "lookbook/parser"
   autoload :Preview, "lookbook/preview"

data/public/lookbook-assets/app.css

@@ -1,4 +1,4 @@
-/*! tailwindcss v2.2.17 | MIT License | https://tailwindcss.com */
+/*! tailwindcss v2.2.19 | MIT License | https://tailwindcss.com */
 
 /*! modern-normalize v1.1.0 | MIT License | https://github.com/sindresorhus/modern-normalize */
 
@@ -606,6 +606,9 @@ video {
   --tw-transform: translateX(var(--tw-translate-x)) translateY(var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y));
   --tw-border-opacity: 1;
   border-color: rgba(229, 231, 235, var(--tw-border-opacity));
+  --tw-ring-offset-shadow: 0 0 #0000;
+  --tw-ring-shadow: 0 0 #0000;
+  --tw-shadow: 0 0 #0000;
   --tw-ring-inset: var(--tw-empty,/*!*/ /*!*/);
   --tw-ring-offset-width: 0px;
   --tw-ring-offset-color: #fff;
@@ -820,12 +823,6 @@ pre[class*="language-"] {
   fill: none;
 }
 
-.min-h-fill {
-  min-height: -webkit-fill-available;
-  min-height: -moz-available;
-  min-height: fill-available;
-}
-
 ::-webkit-scrollbar {
   width: 8px;
   height: 8px;
@@ -1563,6 +1560,10 @@ pre[class*="language-"] {
   display: flex;
 }
 
+.inline-flex {
+  display: inline-flex;
+}
+
 .hidden {
   display: none;
 }
@@ -1599,6 +1600,10 @@ pre[class*="language-"] {
   height: 11px;
 }
 
+.h-6 {
+  height: 1.5rem;
+}
+
 .w-full {
   width: 100%;
 }
@@ -1631,10 +1636,22 @@ pre[class*="language-"] {
   width: 1.25rem;
 }
 
+.w-\[200px\] {
+  width: 200px;
+}
+
+.w-11 {
+  width: 2.75rem;
+}
+
 .max-w-xs {
   max-width: 20rem;
 }
 
+.max-w-\[800px\] {
+  max-width: 800px;
+}
+
 .flex-none {
   flex: none;
 }
@@ -1643,6 +1660,10 @@ pre[class*="language-"] {
   flex: 1 1 auto;
 }
 
+.flex-shrink-0 {
+  flex-shrink: 0;
+}
+
 .flex-grow {
   flex-grow: 1;
 }
@@ -1657,6 +1678,16 @@ pre[class*="language-"] {
   transform: var(--tw-transform);
 }
 
+.translate-x-5 {
+  --tw-translate-x: 1.25rem;
+  transform: var(--tw-transform);
+}
+
+.translate-x-0 {
+  --tw-translate-x: 0px;
+  transform: var(--tw-transform);
+}
+
 .transform {
   transform: var(--tw-transform);
 }
@@ -1692,6 +1723,10 @@ pre[class*="language-"] {
   flex-direction: column;
 }
 
+.items-start {
+  align-items: flex-start;
+}
+
 .items-center {
   align-items: center;
 }
@@ -1751,6 +1786,10 @@ pre[class*="language-"] {
   white-space: nowrap;
 }
 
+.rounded-full {
+  border-radius: 9999px;
+}
+
 .rounded-b {
   border-bottom-right-radius: 0.25rem;
   border-bottom-left-radius: 0.25rem;
@@ -1768,6 +1807,10 @@ pre[class*="language-"] {
   border-width: 1px;
 }
 
+.border-2 {
+  border-width: 2px;
+}
+
 .border-r {
   border-right-width: 1px;
 }
@@ -1835,6 +1878,16 @@ pre[class*="language-"] {
   background-color: rgba(249, 250, 251, var(--tw-bg-opacity));
 }
 
+.bg-indigo-500 {
+  --tw-bg-opacity: 1;
+  background-color: rgba(99, 102, 241, var(--tw-bg-opacity));
+}
+
+.bg-gray-300 {
+  --tw-bg-opacity: 1;
+  background-color: rgba(209, 213, 219, var(--tw-bg-opacity));
+}
+
 .p-4 {
   padding: 1rem;
 }
@@ -1882,6 +1935,11 @@ pre[class*="language-"] {
   padding-bottom: 0px;
 }
 
+.py-3 {
+  padding-top: 0.75rem;
+  padding-bottom: 0.75rem;
+}
+
 .pr-3 {
   padding-right: 0.75rem;
 }
@@ -2000,11 +2058,22 @@ pre[class*="language-"] {
   opacity: 0.5;
 }
 
+.shadow {
+  --tw-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
+  box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow);
+}
+
 .outline-none {
   outline: 2px solid transparent;
   outline-offset: 2px;
 }
 
+.ring-0 {
+  --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(0px + 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);
+}
+
 .blur {
   --tw-blur: blur(8px);
   filter: var(--tw-filter);
@@ -2022,6 +2091,44 @@ pre[class*="language-"] {
   transition-duration: 150ms;
 }
 
+.transition-colors {
+  transition-property: background-color, border-color, color, fill, stroke;
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+  transition-duration: 150ms;
+}
+
+.duration-200 {
+  transition-duration: 200ms;
+}
+
+.ease-in-out {
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.min-h-fill {
+  min-height: -webkit-fill-available;
+  min-height: -moz-available;
+  min-height: fill-available;
+}
+
+.form-input {
+  width: 100%;
+  border-radius: 0.125rem;
+  --tw-border-opacity: 1;
+  border-color: rgba(209, 213, 219, var(--tw-border-opacity));
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  --tw-text-opacity: 1;
+  color: rgba(55, 65, 81, var(--tw-text-opacity));
+}
+
+.form-input:focus {
+  --tw-border-opacity: 1;
+  border-color: rgba(165, 180, 252, var(--tw-border-opacity));
+  --tw-ring-opacity: 1;
+  --tw-ring-color: rgba(165, 180, 252, var(--tw-ring-opacity));
+}
+
 .tippy-box[data-animation=fade][data-state=hidden]{
   opacity:0
 }
@@ -2463,6 +2570,21 @@ pre[class*="language-"] {
   box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000);
 }
 
+.focus\:ring-2:focus {
+  --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);
+}
+
+.focus\:ring-indigo-400:focus {
+  --tw-ring-opacity: 1;
+  --tw-ring-color: rgba(129, 140, 248, var(--tw-ring-opacity));
+}
+
+.focus\:ring-offset-2:focus {
+  --tw-ring-offset-width: 2px;
+}
+
 .group:hover .group-hover\:text-indigo-800 {
   --tw-text-opacity: 1;
   color: rgba(55, 48, 163, var(--tw-text-opacity));

data/public/lookbook-assets/app.js

@@ -7333,7 +7333,9 @@ Expression: "${expression}"
   var module_default3 = src_default3;
 
   // node_modules/@ryangjchandler/alpine-clipboard/src/index.js
-  function src_default4(Alpine3) {
+  var onCopy = () => {
+  };
+  function Clipboard(Alpine3) {
     Alpine3.magic("clipboard", () => {
       return function(target) {
         if (typeof target === "function") {
@@ -7342,10 +7344,17 @@ Expression: "${expression}"
         if (typeof target === "object") {
           target = JSON.stringify(target);
         }
-        return window.navigator.clipboard.writeText(target);
+        return window.navigator.clipboard.writeText(target).then(onCopy);
       };
     });
   }
+  Clipboard.configure = (config) => {
+    if (config.hasOwnProperty("onCopy") && typeof config.onCopy === "function") {
+      onCopy = config.onCopy;
+    }
+    return Clipboard;
+  };
+  var src_default4 = Clipboard;
 
   // app/assets/lookbook/js/utils/screen.js
   function screen_default(Alpine3) {
@@ -8359,6 +8368,9 @@ Expression: "${expression}"
         if (fromEl.isEqualNode(toEl)) {
           return false;
         }
+        if (fromEl.hasAttribute("skip-morph")) {
+          return false;
+        }
         return true;
       }
     }, opts));
@@ -8395,7 +8407,12 @@ Expression: "${expression}"
       render() {
         if (this.ready) {
           morph_default(this.$el, store2.doc.getElementById(this.$el.id));
+          this.$dispatch("document:patched");
         }
+      },
+      navigateTo(path2) {
+        history.pushState({}, null, path2);
+        this.$dispatch("popstate");
       }
     };
   }
@@ -8469,6 +8486,27 @@ Expression: "${expression}"
     };
   }
 
+  // app/assets/lookbook/js/workbench/param.js
+  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 path2 = location.href.replace(location.search, "");
+        this.navigateTo(`${path2}?${searchParams.toString()}`);
+      },
+      validate() {
+        return this.$el.reportValidity ? this.$el.reportValidity() : true;
+      }
+    };
+  }
+
   // app/assets/lookbook/js/nav.js
   function nav_default() {
     return {
@@ -8492,13 +8530,12 @@ Expression: "${expression}"
         });
       },
       navigate(path2) {
-        if (path2 instanceof Event) {
-          path2 = path2.currentTarget.href;
-        }
-        history.pushState({}, null, path2);
-        this.$dispatch("popstate");
+        this.navigateTo(path2 instanceof Event ? path2.currentTarget.href : path2);
       },
-      focusFilter() {
+      focusFilter($event) {
+        if ($event.target.tagName === "INPUT") {
+          return;
+        }
         this.currentFocus = this.$refs.filter;
         setTimeout(() => this.$refs.filter.focus(), 0);
       },
@@ -8666,6 +8703,7 @@ Expression: "${expression}"
   module_default.data("workbench", workbench);
   module_default.data("preview", preview);
   module_default.data("inspector", inspector);
+  module_default.data("param", param);
   module_default.data("clipboard", clipboard);
   module_default.data("sizeObserver", sizeObserver);
   module_default.data("split", split_default);

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lookbook
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.6
 platform: ruby
 authors:
 - Mark Perkins
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-22 00:00:00.000000000 Z
+date: 2021-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -202,11 +202,13 @@ files:
 - app/assets/lookbook/js/utils/split.js
 - app/assets/lookbook/js/workbench.js
 - app/assets/lookbook/js/workbench/inspector.js
+- app/assets/lookbook/js/workbench/param.js
 - app/assets/lookbook/js/workbench/preview.js
 - app/channels/lookbook/connection.rb
 - app/channels/lookbook/reload_channel.rb
 - app/controllers/lookbook/app_controller.rb
 - app/helpers/lookbook/application_helper.rb
+- app/helpers/lookbook/preview_helper.rb
 - app/views/lookbook/app/error.html.erb
 - app/views/lookbook/app/index.html.erb
 - app/views/lookbook/app/not_found.html.erb
@@ -226,13 +228,20 @@ files:
 - app/views/lookbook/workbench/_preview.html.erb
 - app/views/lookbook/workbench/inspector/_code.html.erb
 - app/views/lookbook/workbench/inspector/_notes.html.erb
+- app/views/lookbook/workbench/inspector/_params.html.erb
 - app/views/lookbook/workbench/inspector/_plain.html.erb
+- app/views/lookbook/workbench/inspector/params/_select.html.erb
+- app/views/lookbook/workbench/inspector/params/_text.html.erb
+- app/views/lookbook/workbench/inspector/params/_textarea.html.erb
+- app/views/lookbook/workbench/inspector/params/_toggle.html.erb
 - config/routes.rb
 - lib/lookbook.rb
 - lib/lookbook/collection.rb
 - lib/lookbook/engine.rb
+- lib/lookbook/features.rb
 - lib/lookbook/lang.rb
 - lib/lookbook/null_logger.rb
+- lib/lookbook/params.rb
 - lib/lookbook/parser.rb
 - lib/lookbook/preview.rb
 - lib/lookbook/preview_controller.rb
@@ -263,7 +272,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: A native development UI for ViewComponent