lookbook 0.2.1 → 0.3.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f1b2263fb0949354da2aab14aeea2e2c0052810b6eb316249d9796718413614
-  data.tar.gz: 7423d9845627d153a1c46f1adc3fa4a14ed708d97f80a664b67c0e9cc0018528
+  metadata.gz: 0eddf2109917e499486420e62609c84456017efee3429da0370057a0792953eb
+  data.tar.gz: f5713d64d58704467646bebf3bdf979ad905c8e70df08cebb20401ed279b2a31
 SHA512:
-  metadata.gz: b821396d726636b7c633535543c1c4e718181b65809b85ae5b4ffee857914cb6910f554d28c0cced233d0e8419b60545b4115bda573d6b15b473fdf6c9d0fe24
-  data.tar.gz: 902e85067b97aa9371e9708aca1c14c2f73d928603755f63357e1644e7b078e515a2e979cdedfef0e37b206f930e9ac21f7ab15aeb138d2f8e3adc86f0dd1441
+  metadata.gz: 41238edb770517284df464e2a70682abc239dc9efb0212c4f467f596d013ea40ffbbcf391061eba724e2ffb168f9fc4ae3ef5684fe348f1574ea930746b8d796
+  data.tar.gz: c9c78b2399fae7a00185441af62a75568afc3a732ca46889e9314234aabc520f62aa9bbc89c84ba8f4af40d4e64d56d5152b96f48994b6a60d53a06bb9a5de7f

data/README.md

@@ -1,13 +1,18 @@
 <div align="center">
-  <h2>Lookbook</h2>
+<h1>👀 Lookbook 👀</h1>
 
-👀 A native development UI for [ViewComponent](http://viewcomponent.org/) 👀
+<p>A native development UI for <a href="http://viewcomponent.org/">ViewComponent</a></p>
 
+<div>
+<a href="https://rubygems.org/gems/lookbook"><img src="https://badge.fury.io/rb/lookbook.svg" alt="Gem version">
+<a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide">
+<a href="https://github.com/prettier/prettier"><img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg" alt="Code style: Prettier">
+</div>
 </div>
 
 ---
 
-Lookbook gives [ViewComponent](http://viewcomponent.org/)-based projects a _ready-to-go_ development UI for navigating, inspecting and interacting with component previews.
+**Lookbook gives [ViewComponent](http://viewcomponent.org/)-based projects a _ready-to-go_ development UI for navigating, inspecting and interacting with component previews.**
 
 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.
 
@@ -38,18 +43,13 @@ The [demo app repo](https://github.com/allmarkedup/lookbook-demo) contains instr
 
 ### 1. Add as a dependency
 
-In your `Gemfile` add:
+Add Lookbook to your `Gemfile` somewhere **after** the ViewComponent gem. For example:
 
 ```ruby
+gem "view_component", require: "view_component/engine"
 gem "lookbook"
 ```
 
-or
-
-```bash
-gem install lookbook
-```
-
 ### 2. Mount the Lookbook engine
 
 You then need to mount the Lookbook engine (at a path of your choosing) in your `routes.rb` file:
@@ -70,125 +70,179 @@ Then you can start your app as normal and navigate to `http://localhost:3000/loo
 
 ## Usage
 
-You don't need to do anything special to create ViewComponent previews for Lookbook.
+You don't need to do anything special to see your ViewComponent previews and examples in Lookbook - just create them as normal and they'll automatically appear in the Lookbook UI. Preview templates, custom layouts and even bespoke [preview controllers](https://viewcomponent.org/guide/previews.html#configuring-preview-controller) should all work as you would expect.
 
-Lookbook will use the [ViewComponent configuration options](https://viewcomponent.org/api.html#configuration) for your project to find and render your components so you don't need to configure anything separately (unless you want to tweak the behaviour or look of Lookbook itself, of course).
+> 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).
 
-> If you are new to ViewComponent development, checkout the [ViewComponent docs](https://viewcomponent.org/guide/) on how to get started developing your components and creating previews.
+### Annotating preview files
 
-Lookbook uses the exact same [preview files](https://viewcomponent.org/guide/previews.html) as 'regular' ViewComponent previews, so using preview templates, custom layouts and even bespoke [preview controllers](https://viewcomponent.org/guide/previews.html#configuring-preview-controller) all works as you would expect.
+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:
 
-### Comment tags
+```ruby
+# @label Basic Button
+class ButtonComponentPreview < ViewComponent::Preview
 
-Lookbook uses [Yard-style tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) in class and method comments to extract additional information about previews and examples.
+  # Primary button
+  # ---------------
+  # This is the button style you should use for most things.
+  #
+  # @label Primary
+  def default
+    render ButtonComponent.new do
+      "Click me"
+    end
+  end
 
-Tags are just strings identified by their `@` prefix - for example `@hidden`. Tags are always placed in a comment above the relevant preview class or example method. The comments can still contain any other text, and multiple tags can be included in any one comment. For example:
+  # Secondary button
+  # ---------------
+  # This should be used for less important actions.
+  def secondary
+    render ButtonComponent.new(style: :secondary) do
+      "Click me"
+    end
+  end
 
-```ruby
-# This is a class-level comment.
-# @hidden
-class MyClass
-  # This is a method-level comment.
+  # Unicorn button
+  # ---------------
+  # This button style is still a **work in progress**.
+  #
   # @hidden
-  def my_method
+  def secondary
+    render ButtonComponent.new do
+      "Click me"
+    end
   end
+
+  # @!group More examples
+
+  def short_text
+    render ButtonComponent.new do
+      "Go"
+    end
+  end
+
+  def long_text
+    render ButtonComponent.new do
+      "Click here to do this thing because it's the best way to do it"
+    end
+  end
+
+  def emoji_text
+    render ButtonComponent.new do
+      "👀📗"
+    end
+  end
+
+  # @!endgroup
+
 end
 ```
 
-Some tags can also require additional arguments. Further information on the tags Lookbook uses are detailed in the docs below.
+**Tags** are just strings identified by their `@` prefix - for example `@hidden`. Tags are always placed in a comment above the relevant preview class or example method.
 
-### 📝 Adding notes to previews
+The following Lookbook-specific tags are available for use:
 
-Lookbook lets you add notes to your preview examples which are then displayed in the inspector panel. They look something like this:
+#### `@label <text>`
 
-<img src=".github/assets/preview_example_notes.png" width="400">
+Used to replace the auto-generated navigation label for the item with `<text>`.
 
-Notes are generated from comments above example methods in your preview files. Below is an example of two preview examples that both have notes:
+> Available for preview classes & example methods.
 
 ```ruby
-class ButtonComponentPreview < ViewComponent::Preview
+# @label Preview Label
+class FooComponentPreview < ViewComponent::Preview
 
-  # Add notes as comments above the example methods.
-  # Multi-line is just fine and **markdown** is supported too!
-  #
-  # It's a good place to put usage and implementation instructions
-  # for people browsing the component previews in the UI.
+  # @label Example Label
   def default
-    render ButtonComponent.new(text: "Click me")
-  end
-
-  # Each preview example has it's own notes, extracted from the method comments.
-  def danger
-    render ButtonComponent.new(text: "Don't do it!", theme: :danger)
   end
 end
 ```
 
-### 👀 Navigation customisation
+#### `@hidden`
 
-Lookbook generates a nested navigation menu based on the file structure of your component preview directory (or directories). This can be customised in a number of ways.
+Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
 
-#### Preview and example labels
+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.
 
-By default, the labels shown for previews and examples are stripped and 'titlized' versions of the preview file names and the example method names, respectively.
-
-If you wish to override the automatic navigation label generation for a preview or example you can use the `@label` comment tag:
+> Available for both preview classes & example methods.
 
 ```ruby
-# @label Standard Button
-class BtnPreview < ViewComponent::Preview
+# @hidden
+class FooComponentPreview < ViewComponent::Preview
 
-  # @label Icon Button
-  def with_icon
+  # @hidden
+  def default
   end
 end
 ```
 
-In the example above, the preview and example would be displayed like this:
+#### `@!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.
+
+You can group a set of examples by wrapping them in `@!group <name>` / `@!endgroup` tags within your preview file:
 
-<img src=".github/assets/nav_labels.png" width="200">
+```ruby
+class HeaderComponentPreview < ViewComponent::Preview
 
-#### Excluding previews and/or examples from the navigation
+  def standard
+    render Elements::HeaderComponent.new do
+      "Standard header"
+    end
+  end
 
-Sometimes you may want to temporarily hide a preview or an individual example from the Lookbook UI. This means that the preview or example will not show up in the navigation, but will still be accessible via it's URL. You can use the `@hidden` comment tag to manage this.
+  # @!group Sizes
 
-To **hide an entire preview** include the `@hidden` tag in a class comment:
+  def small
+    render Elements::HeaderComponent.new(size: 12) do
+      "Small header"
+    end
+  end
+
+  def medium
+    render Elements::HeaderComponent.new(size: 16) do
+      "Small header"
+    end
+  end
+
+  def big
+    render Elements::HeaderComponent.new(size: 24) do
+      "Small header"
+    end
+  end
+
+  # @!endgroup
 
-```ruby
-# @hidden
-class MyComponentPreview < ViewComponent::Preview
-  # examples here....
 end
 ```
 
-To **hide an individual example** include the `@hidden` tag in the appropriate method comment:
+The example above would display the `Sizes` examples grouped together on a single page, rather than as indiviual items in the navigation:
 
-```ruby
-class MyComponentPreview < ViewComponent::Preview
+<img src=".github/assets/nav_group.png">
 
-  # Hidden Example
-  # ----------
-  # You won't see this in the nav!
-  #
-  # @hidden
-  def hidden_example
-    # ...
-  end
+You can have as many groups as you like within a single preview class, but each example can only belong to one group.
 
-  def a_visible_example
-    # ...
-  end
+#### Adding notes
 
-  # @hidden
-  def another_hidden_example
-    # ...
+All comment text other than tags will be treated as markdown and rendered in the **Notes** panel for that example in the Lookbook UI.
+
+```ruby
+# @hidden
+class ProfileCardComponentPreview < ViewComponent::Preview
+
+  # Profile Card
+  # ------------
+  # Use the default profile card component whenever you need to represent a user.
+  def default
   end
 end
 ```
 
+<img src=".github/assets/preview_example_notes.png" width="400">
+
 ## Configuration
 
-Lookbook uses ViewComponent's configuration options for anything to do with previews, paths and general setup, so you won't need to duplicate any settings.
+Lookbook will use the ViewComponent [configuration](https://viewcomponent.org/api.html#configuration) for your project to find and render your previews so you generally you won't need to configure anything separately.
 
 However the following Lookbook-specific config options are also available:
 
@@ -208,6 +262,30 @@ 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')
 ```
 
+## Keyboard shortcuts
+
+Lookbook provides a few keyboard shortcuts to help you quickly move around the UI.
+
+- `f` - move focus to the nav filter box
+- `Esc` [when focus is in nav filter box] - Clear contents if text is present, or return focus to the UI if the box is already empty
+- `s` - Switch to Source tab in the inspector
+- `o` - Switch to Output tab in the inspector
+- `n` - Switch to Notes tab in the inspector
+- `r` - Refresh the preview (useful if using something like Faker to generate randomised data for the preview)
+- `w` - Open the standalone rendered preview in a new window
+
+## Troubleshooting
+
+#### Blank preview window
+
+Certain setups (for example when using `Rack::LiveReload`) can cause an issue with the way that the preview iframe displays the rendered component preview (i.e. using the `srcdoc` attribute to avoid extra requests).
+
+If you are seeing a blank preview window, but the source and output tabs are both displaying code as expected, you can disable the use of the `srcdoc` attribute using the following configuration option:
+
+```ruby
+config.lookbook.preview_srcdoc = false
+```
+
 ## Contributing
 
 Lookbook is very much a small hobby/side project at the moment. I'd love to hear from anyone who is interested in contributing but I'm terrible at replying to emails or messages, so don't be surprised if I take forever to get back to you. It's not personal 😜

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

@@ -34,4 +34,32 @@
     stroke-linejoin: round;
     fill: none;
   }
+
+  .h-fill {
+    height: -webkit-fill-available;
+  }
+
+  .min-h-fill {
+    min-height: -webkit-fill-available;
+  }
+
+  ::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  ::-webkit-scrollbar-thumb {
+    @apply bg-gray-300 transition-colors;
+    border-radius: 6px;
+    border: 2px solid transparent;
+    background-clip: content-box;
+  }
+
+  ::-webkit-scrollbar-thumb:hover {
+    @apply bg-gray-400;
+  }
 }

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

@@ -1,47 +1,74 @@
+import { install } from "@github/hotkey";
 import Alpine from "alpinejs";
 import Fern from "@ryangjchandler/fern";
-import Tooltip from "@ryangjchandler/alpine-tooltip";
-import Clipboard from "@ryangjchandler/alpine-clipboard";
-import split from "./split";
-import preview from "./preview";
-import observeSize from "./size_observer";
-import reloader from "./reloader";
+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;
 
 // Plugins
 
 Alpine.plugin(Fern);
-Alpine.plugin(Tooltip);
-Alpine.plugin(Clipboard);
-
-// Data
-
-Alpine.data("preview", preview);
-Alpine.data("sizeObserver", observeSize);
-Alpine.data("split", split);
+Alpine.plugin(AlpineTooltip);
+Alpine.plugin(AlpineClipboard);
+Alpine.plugin(Screen);
 
 // Stores
 
-Alpine.store("app", { reflowing: false });
+Alpine.store("page", {
+  reflowing: false,
+  doc: window.document,
+});
+
 Alpine.persistedStore("nav", {
   width: 280,
   filter: "",
   open: {},
-  scrollTop: 0,
-  shouldDisplay(previewName) {
-    const cleanFilter = this.filter.replace(/\s/g, "");
-    return (
-      cleanFilter === "" || previewName.includes(cleanFilter.toLowerCase())
-    );
-  },
 });
-Alpine.persistedStore("preview", {});
+
 Alpine.persistedStore("inspector", {
   height: 200,
   active: "source",
 });
 
+Alpine.persistedStore("preview", {
+  width: "100%",
+});
+
+// Components & utils
+
+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("inspector", inspector);
+Alpine.data("clipboard", clipboard);
+Alpine.data("sizeObserver", sizeObserver);
+Alpine.data("split", split);
+
 // Init
 
+for (const el of document.querySelectorAll("[data-hotkey]")) {
+  install(el);
+}
+
+if (window.SOCKET_PATH) {
+  reloader(window.SOCKET_PATH).start();
+}
+
 window.Alpine = Alpine;
-reloader(window.SOCKET_PATH).start();
 Alpine.start();

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

@@ -0,0 +1,20 @@
+export default function navLeaf() {
+  return {
+    path: null,
+    matchers: [],
+    active: false,
+    hidden: false,
+    setActive() {
+      this.active = this.path === window.location.pathname;
+    },
+    filter() {
+      if (this.$store.nav.filtering) {
+        const text = this.$store.nav.filterText;
+        const matched = this.matchers.map((m) => m.includes(text));
+        this.hidden = !matched.filter((m) => m).length;
+      } else {
+        this.hidden = false;
+      }
+    },
+  };
+}

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

@@ -0,0 +1,31 @@
+export default function navNode() {
+  return {
+    id: null,
+    hidden: true,
+    children: [],
+    init() {
+      this.id = this.$el.id;
+    },
+    open() {
+      return this.$store.nav.open[this.id];
+    },
+    getChildren() {
+      return this.$refs.items
+        ? Array.from(this.$refs.items.querySelectorAll(":scope > li"))
+        : [];
+    },
+    filter() {
+      this.hidden = true;
+      this.getChildren().forEach((child) => {
+        const data = child._x_dataStack[0];
+        data.filter();
+        if (!data.hidden) {
+          this.hidden = false;
+        }
+      });
+    },
+    toggle() {
+      this.$store.nav.open[this.id] = !this.$store.nav.open[this.id];
+    },
+  };
+}

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

@@ -0,0 +1,36 @@
+import morph from "./utils/morph";
+
+export default function () {
+  return {
+    clearFilter() {
+      this.$store.nav.filter = "";
+    },
+    init() {
+      this.$watch("$store.nav.filter", (value) => {
+        const nav = this.$store.nav;
+        nav.filterText = value.replace(/\s/g, "").toLowerCase();
+        nav.filtering = nav.filterText.length > 0;
+      });
+    },
+    updateNav(event) {
+      const nav = document.getElementById("nav");
+      nav.style.height = `${this.$refs.shim.offsetHeight}px`;
+      morph(nav, event.detail.doc.getElementById("nav"));
+      Promise.resolve().then(() => {
+        this.$refs.shim.style.height = "auto";
+        this.$dispatch("nav:updated");
+      });
+    },
+    navigate($event) {
+      history.pushState({}, null, $event.currentTarget.href);
+      this.$dispatch("popstate");
+    },
+    focusFilter() {
+      this.currentFocus = this.$refs.filter;
+      setTimeout(() => this.$refs.filter.focus(), 0);
+    },
+    unfocusFilter() {
+      this.$refs.filter.blur();
+    },
+  };
+}

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

@@ -0,0 +1,33 @@
+import morph from "./utils/morph";
+
+export default function page() {
+  const store = Alpine.store("page");
+  return {
+    ready: false,
+    sidebarOpenMobile: false,
+    init() {
+      this.$nextTick(() => (this.ready = true));
+    },
+    splitProps: {
+      minSize: 200,
+      onDrag(splits) {
+        Alpine.store("nav").width = Math.min(splits[0], 500);
+      },
+    },
+    async fetchHTML() {
+      const response = await fetch(window.document.location);
+      if (!response.ok) return window.location.reload();
+      const html = await response.text();
+      store.doc = new DOMParser().parseFromString(html, "text/html");
+      return store.doc;
+    },
+    updateTitle() {
+      document.title = store.doc.title;
+    },
+    render() {
+      if (this.ready) {
+        morph(this.$el, store.doc.getElementById(this.$el.id));
+      }
+    },
+  };
+}

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

@@ -0,0 +1,13 @@
+export default function clipboard() {
+  return {
+    content: null,
+    done: false,
+    save() {
+      this.$clipboard(this.content);
+      this.done = true;
+      setTimeout(() => {
+        this.done = false;
+      }, 1000);
+    },
+  };
+}

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

@@ -0,0 +1,16 @@
+import morph from "morphdom";
+
+export default function (from, to, opts = {}) {
+  morph(from, to, {
+    onBeforeElUpdated: function (fromEl, toEl) {
+      if (fromEl._x_dataStack) {
+        Alpine.clone(fromEl, toEl);
+      }
+      if (fromEl.isEqualNode(toEl)) {
+        return false;
+      }
+      return true;
+    },
+    ...opts,
+  });
+}

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

@@ -0,0 +1,44 @@
+// Adapted from: https://github.com/alpine-collective/toolkit
+
+export default function (Alpine) {
+  // Create reactive data context
+  let data = Alpine.reactive({ screensize: window.innerWidth });
+
+  // Configuration
+  const defaultBreakpoints = {
+    xs: 0,
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536,
+  };
+
+  const breakpoints =
+    window.AlpineMagicHelpersConfig &&
+    window.AlpineMagicHelpersConfig.breakpoints
+      ? window.AlpineMagicHelpersConfig.breakpoints
+      : defaultBreakpoints;
+
+  window.addEventListener("resize", () => {
+    data.screensize = window.innerWidth;
+  });
+
+  Alpine.magic("screen", () => (breakpoint) => {
+    let width = data.screensize;
+
+    if (Number.isInteger(breakpoint)) return breakpoint <= width;
+
+    // Check if breakpoint exists
+    if (breakpoints[breakpoint] === undefined) {
+      throw Error(
+        "Undefined $screen property: " +
+          breakpoint +
+          ". Supported properties: " +
+          Object.keys(breakpoints).join(", ")
+      );
+    }
+
+    return breakpoints[breakpoint] <= width;
+  });
+}

data/app/assets/lookbook/js/{size_observer.js → utils/size_observer.js}

@@ -1,4 +1,4 @@
-export default function () {
+export default function sizeObserver() {
   return {
     observedWidth: 0,
     observedHeight: 0,