lookbook 0.2.2 → 0.3.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8a93baa87f47304f68676fd5884b61eb32782f552e89316e4abb702373003f
-  data.tar.gz: ada4f4b935bc63066b980a8faf7fcf81f4f7a594790f4f4ddd8a01a630b880f5
+  metadata.gz: 6b0d42f049a62be24079955f108c14f4b7b73b8b0f0a677639cce865e2260006
+  data.tar.gz: db6d156648495478cdcd55101065cb3875cfbdfb2b9bce3f924e37a11b2b789b
 SHA512:
-  metadata.gz: 8cc694ae333a50382654e9c36f52a9cfe964a20bd6715ce365dd55adcca44c564e1a742c053625286dad9f929bf9640919d961277d4c426ab7c9584cb57fd5da
-  data.tar.gz: ef0fc829bf1528cc521f2cd98887fc67476ed1d0a316e8ebefd9813e744714a0145b897091f7cc6768c2b459b1c3e5bf3982b2ee7ae451f2b2e512fa35e67b4a
+  metadata.gz: 15a7f9761f859bfdc9965801aba418e30fc95520635fc1a03dd9ff63af5e73e98563bc8d16420ae705824f18dffcdc9f834b57547815c4ab5cf899aba831e2e3
+  data.tar.gz: 889cea13089b40fa493c7ca39e6ff871f9db6432b9fffa1b57ab1a3a686b6e04ee2d0e3859093abcea386ccd67e2d7fe3aeaf2acf239632c535332d2a35e2ae3

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,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: 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,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,

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];
+      },
+    },
+  };
+}