lookbook 0.4.3 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f5cf46a07c480d8c8c3fe5f0a521ce01a316985f458becf36fb4c73c871f7cf
-  data.tar.gz: 2474c4105e357d9762c5228cee1190194a3b3069c6a9a9dc2afe0cf287339efe
+  metadata.gz: ce922c11cf8df5a1161c555189786265e51e29881c5a5e0948153fa65e855a50
+  data.tar.gz: 38fe97d9e04c6505ebc8e1b8bc877fe761db215b525117b42a044cadf7b2eb50
 SHA512:
-  metadata.gz: 439aad3227d8e1e3c8d0202c4edf6b93983a2182c7a8d32c120c47f7fcd1c1dcdff675084029172c200d25fe052916b5cdcb812acd378b37af5e793ce5bea613
-  data.tar.gz: ab031ca977f442a1203fb059df65fe763db9e4877eeb594e44b09c63b2f0bd58bc7e6ab409ef2a11d7f33fe5b5a90f8b30a0eadd5114566c619dcc9b62be8a1e
+  metadata.gz: d319e159fc2b87e710532dbd6c426360f2a6173e174d3e0eac05c677bdfd945cf0c5a391c426a8f987cb7539797aa10241e45cdddd55048f25af84689d0af9b2
+  data.tar.gz: 80a217bf6303a778676872bd9d6c1412a3811323903031d491e945c0788ebba20cc2ccbb059d011e823b80d74b5342994c9b42f7590fd4fbfd305166b187d345

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,67 @@
     @apply bg-gray-400;
   }
 }
+
+@layer components {
+  #nav > ul > li {
+    @apply py-1;
+  }
+
+  .nav-toggle {
+    @apply flex items-center cursor-pointer pr-3 hover:bg-gray-200 hover:bg-opacity-50;
+  }
+
+  .nav-label {
+    @apply truncate w-full whitespace-nowrap text-left select-none;
+  }
+
+  .code {
+    @apply font-mono;
+  }
+
+  .code pre {
+    @apply block;
+  }
+
+  .code .line {
+    @apply flex items-center leading-relaxed;
+  }
+
+  .code.numbered {
+    @apply relative pt-3;
+  }
+
+  .code.numbered:before {
+    content: "";
+    left: calc(2.7em + 8px);
+    @apply absolute top-0 bottom-0 border-r border-gray-200;
+  }
+
+  .code .line-number {
+    width: calc(2.7em + 8px);
+    padding-top: 3px;
+    padding-bottom: 3px;
+    padding-right: 8px;
+    margin-right: 16px;
+    @apply font-mono text-right text-gray-400 flex-none text-xs;
+  }
+
+  .code .line-content {
+    @apply flex-none pr-4;
+  }
+
+  /* .code .line:before {
+    content: counter(line);
+    width: calc(3em + 8px);
+    padding-top: 2px;
+    padding-bottom: 2px;
+    padding-right: 8px;
+    @apply font-mono inline-block text-right mr-4 text-gray-400 border-r border-gray-200;
+  } */
+}
+
+@layer utilities {
+  .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

@@ -1,64 +1,54 @@
 import { install } from "@github/hotkey";
 import Alpine from "alpinejs";
-import Fern from "@ryangjchandler/fern";
-import AlpineTooltip from "@ryangjchandler/alpine-tooltip";
-import AlpineClipboard from "@ryangjchandler/alpine-clipboard";
-import Screen from "./utils/screen";
-import split from "./utils/split";
-import page from "./page";
-import workbench from "./workbench";
-import preview from "./workbench/preview";
-import inspector from "./workbench/inspector";
-import nav from "./nav";
-import navNode from "./nav/node";
-import navLeaf from "./nav/leaf";
-import sizeObserver from "./utils/size_observer";
-import reloader from "./utils/reloader";
-import clipboard from "./utils/clipboard";
-
-window.Alpine = Alpine;
+import Persist from "@alpinejs/persist";
+import Morph from "@alpinejs/morph";
+import Tooltip from "@ryangjchandler/alpine-tooltip";
+
+import page from "./components/page";
+import inspector from "./components/inspector";
+import previewWindow from "./components/preview-window";
+import filter from "./components/filter";
+import param from "./components/param";
+import nav from "./components/nav";
+import navItem from "./components/nav-item";
+import navGroup from "./components/nav-group";
+import splitter from "./components/splitter";
+import copy from "./components/copy";
+import sizes from "./components/sizes";
+
+import initFilterStore from "./stores/filter";
+import initLayoutStore from "./stores/layout";
+import initNavStore from "./stores/nav";
+import initSidebarStore from "./stores/sidebar";
+import initInspectorStore from "./stores/inspector";
 
 // Plugins
 
-Alpine.plugin(Fern);
-Alpine.plugin(AlpineTooltip);
-Alpine.plugin(AlpineClipboard);
-Alpine.plugin(Screen);
+Alpine.plugin(Persist);
+Alpine.plugin(Morph);
+Alpine.plugin(Tooltip);
 
 // Stores
 
-Alpine.store("page", {
-  reflowing: false,
-  doc: window.document,
-});
-
-Alpine.persistedStore("nav", {
-  width: 280,
-  filter: "",
-  open: {},
-});
-
-Alpine.persistedStore("inspector", {
-  height: 200,
-  active: "source",
-});
-
-Alpine.persistedStore("preview", {
-  width: "100%",
-});
+Alpine.store("filter", initFilterStore(Alpine));
+Alpine.store("layout", initLayoutStore(Alpine));
+Alpine.store("nav", initNavStore(Alpine));
+Alpine.store("sidebar", initSidebarStore(Alpine));
+Alpine.store("inspector", initInspectorStore(Alpine));
 
-// Components & utils
+// Components
 
 Alpine.data("page", page);
-Alpine.data("nav", nav);
-Alpine.data("navNode", navNode);
-Alpine.data("navLeaf", navLeaf);
-Alpine.data("workbench", workbench);
-Alpine.data("preview", preview);
+Alpine.data("splitter", splitter);
+Alpine.data("previewWindow", previewWindow);
+Alpine.data("copy", copy);
 Alpine.data("inspector", inspector);
-Alpine.data("clipboard", clipboard);
-Alpine.data("sizeObserver", sizeObserver);
-Alpine.data("split", split);
+Alpine.data("filter", filter);
+Alpine.data("param", param);
+Alpine.data("sizes", sizes);
+Alpine.data("nav", nav);
+Alpine.data("navItem", navItem);
+Alpine.data("navGroup", navGroup);
 
 // Init
 
@@ -66,9 +56,5 @@ for (const el of document.querySelectorAll("[data-hotkey]")) {
   install(el);
 }
 
-if (window.SOCKET_PATH) {
-  reloader(window.SOCKET_PATH).start();
-}
-
 window.Alpine = Alpine;
 Alpine.start();

data/app/assets/lookbook/js/components/copy.js

@@ -0,0 +1,16 @@
+export default function copy(id) {
+  return {
+    get content() {
+      const target = document.getElementById(id);
+      return (target ? target.innerHTML : "").trim();
+    },
+    done: false,
+    async save() {
+      await window.navigator.clipboard.writeText(this.content);
+      this.done = true;
+      setTimeout(() => {
+        this.done = false;
+      }, 1000);
+    },
+  };
+}

data/app/assets/lookbook/js/components/filter.js

@@ -0,0 +1,24 @@
+export default function filter() {
+  return {
+    get active() {
+      return this.$store.filter.active;
+    },
+    checkEsc($event) {
+      if ($event.key === "Escape") {
+        this.active ? this.clear() : this.blur();
+      }
+    },
+    clear() {
+      this.$store.filter.raw = "";
+    },
+    focus($event) {
+      if ($event.target.tagName === "INPUT") {
+        return;
+      }
+      setTimeout(() => this.$refs.input.focus(), 0);
+    },
+    blur() {
+      setTimeout(() => this.$refs.input.blur(), 0);
+    },
+  };
+}

data/app/assets/lookbook/js/components/inspector.js

@@ -0,0 +1,21 @@
+export default function inspector() {
+  return {
+    isActivePanel(panel) {
+      return this.$store.inspector.panels.active == panel;
+    },
+    switchPanel(panel) {
+      this.$store.inspector.panels.active = panel;
+    },
+    get showSource() {
+      return this.$store.inspector.preview.source;
+    },
+    toggleSource() {
+      this.$store.inspector.preview.source =
+        !this.$store.inspector.preview.source;
+    },
+    preview: {
+      width: null,
+      height: null,
+    },
+  };
+}