lookbook 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f643b8df09b68fb0e91d8dd522b186d8bcb8e58fa7883841a112a82a4ec81f8d
-  data.tar.gz: f97771056316f5e652a9850c2ac6495fb1c934135fada28af6557c7cd602e90a
+  metadata.gz: 55670a652a3259ba1f28e3c6ec9be4201ce3348e7a7190e2d6ca2b8f05628e72
+  data.tar.gz: a77a7b1b038ba8d4bdd5262cd4e97542244788e1812d86f6ee31ba753e9396d3
 SHA512:
-  metadata.gz: a4dc35a94c6173b687c903f098b5f0c05d8025c9171efa05ed0eb24993685c8495b7497f30df0f7d4550b2609f4dcbd0263624f8b1c9a7ed740bfd66dc48d288
-  data.tar.gz: 1f63d7ae4b684c46f89e0bfe683dbc83e0bf5daca16ced87c6061f0e7ea8c8da0c9131de71b9fd6dad7990211108fcad25d35ff5669b31b95eac78c6db70d48b
+  metadata.gz: 136864d246c2269673654d2dae4dac3b6688abb0b9812a443b7e47d3bf0ab378103b3d070bdf6c0e78b15be56740a88d223cd86b241d0428cde7aa194dbf316f
+  data.tar.gz: 3458476f1781994cc442d11b9142976cd30ddc447bb4afa9cf41911dfbcd5813d56e6e67179288f18325fea61e8bd6e41b34fe2e2e75bb634f278e7639508ba3

data/README.md

@@ -112,6 +112,29 @@ class ButtonComponentPreview < ViewComponent::Preview
       "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
 ```
 
@@ -153,6 +176,52 @@ class FooComponentPreview < ViewComponent::Preview
 end
 ```
 
+#### `@!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:
+
+```ruby
+class HeaderComponentPreview < ViewComponent::Preview
+
+  def standard
+    render Elements::HeaderComponent.new do
+      "Standard header"
+    end
+  end
+
+  # @!group Sizes
+
+  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
+
+end
+```
+
+The example above would display the `Sizes` examples grouped together on a single page, rather than as indiviual items in the navigation:
+
+<img src=".github/assets/nav_group.png">
+
+You can have as many groups as you like within a single preview class, but each example can only belong to one group.
+
 #### Adding notes
 
 All comment text other than tags will be treated as markdown and rendered in the **Notes** panel for that example in the Lookbook UI.
@@ -193,6 +262,18 @@ 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

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

@@ -34,4 +34,32 @@
     stroke-linejoin: round;
     fill: none;
   }
+
+  .h-fill {
+    height: fill-available;
+  }
+
+  .min-h-fill {
+    min-height: 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,49 +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
 
-window.Alpine = Alpine;
+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/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,39 @@
+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(path) {
+      if (path instanceof Event) {
+        path = path.currentTarget.href;
+      }
+      history.pushState({}, null, path);
+      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,

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

@@ -1,7 +1,7 @@
 import Split from "split-grid";
 
 export default function (props) {
-  const app = Alpine.store("app");
+  const page = Alpine.store("page");
   return {
     init() {
       Split({
@@ -11,14 +11,14 @@ export default function (props) {
         minSize: props.minSize,
         writeStyle() {},
         onDrag(dir, track, style) {
-          splits = style.split(" ").map((num) => parseInt(num));
+          const splits = style.split(" ").map((num) => parseInt(num));
           props.onDrag(splits);
         },
         onDragStart() {
-          app.reflowing = true;
+          page.reflowing = true;
         },
         onDragEnd() {
-          app.reflowing = false;
+          page.reflowing = false;
         },
       });
     },

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

@@ -0,0 +1,11 @@
+export default function inspector() {
+  const inspector = Alpine.store("inspector");
+  return {
+    switchTo(id) {
+      inspector.active = id;
+    },
+    active(id) {
+      return inspector.active === id;
+    },
+  };
+}

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

@@ -0,0 +1,39 @@
+export default function preview() {
+  const app = Alpine.store("page");
+  const preview = Alpine.store("preview");
+  return {
+    init() {
+      this.root = this.$el;
+    },
+    onResize(e) {
+      const size =
+        this.resizeStartSize - (this.resizeStartPosition - e.pageX) * 2;
+      const parentSize = this.root.parentElement.clientWidth;
+      const percentSize = (Math.round(size) / parentSize) * 100;
+      const minWidth = (300 / parentSize) * 100;
+      preview.width = `${Math.min(Math.max(percentSize, minWidth), 100)}%`;
+    },
+    onResizeStart(e) {
+      app.reflowing = true;
+      this.onResize = this.onResize.bind(this);
+      this.onResizeEnd = this.onResizeEnd.bind(this);
+      this.resizeStartPosition = e.pageX;
+      this.resizeStartSize = this.root.clientWidth;
+      window.addEventListener("pointermove", this.onResize);
+      window.addEventListener("pointerup", this.onResizeEnd);
+    },
+    onResizeEnd() {
+      window.removeEventListener("pointermove", this.onResize);
+      window.removeEventListener("pointerup", this.onResizeEnd);
+      app.reflowing = false;
+    },
+    toggleFullWidth() {
+      if (preview.width === "100%" && preview.lastWidth) {
+        preview.width = preview.lastWidth;
+      } else {
+        preview.lastWidth = preview.width;
+        preview.width = "100%";
+      }
+    },
+  };
+}

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

@@ -0,0 +1,14 @@
+export default function workbench() {
+  const inspector = Alpine.store("inspector");
+  return {
+    previewViewportHeight: 0,
+    previewViewportWidth: 0,
+    splitProps: {
+      direction: "vertical",
+      minSize: 200,
+      onDrag(splits) {
+        inspector.height = splits[2];
+      },
+    },
+  };
+}