lookbook 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca448bf7c2f60a27c0cec712165fb3d6eb230739c93e9cee559ebd81a5dcd2ad
-  data.tar.gz: 4ef5134c7853c526ced67e56568250575934f6b25d4e558f21275e13e968e07b
+  metadata.gz: 40ec6640c4c188089ff874cb11fb129ddc6c541d078681b1b3dea133f3afaedf
+  data.tar.gz: 331f4693438b931929b40d58c4b7c0d0cf0ece9089891d8e5863c8971f5e4138
 SHA512:
-  metadata.gz: 75cda1bd9921636c6a76998f4228f6193ad5d8a3da10e2c7fef3434a52ffef937e40b5032245155ff47a340c8976e926db4e1d6fa267606bc923d82f4d7fadb7
-  data.tar.gz: 2e719c65802e23e4e4dfe8308eb01208181454cc76fd043de97916537421016c8b20ef8f7cc2e944c48f04c46ffc31eda50024760425774e89d1544cf4bd5570
+  metadata.gz: a538f52d85d4d5e833c2549442b001e44e749b42e87a5bbe4676e718300405b7b9b32d6efd18b1ce23dedcfefce8c82a4f4128236fa83dcff570b7f609b15004
+  data.tar.gz: a5a6fe4dbba3e951441b5c4fb64b6a268de687c99bb7779892d5e819eeae19fbcee8d740c749808671bf65202fc6af581a958869f3fb67c6f9aac5c5af364007

data/README.md

@@ -12,6 +12,12 @@
 
 ---
 
+<div align="center">
+<a href="#installing">Installing</a> • <a href="#previews">Previews</a>  • <a href="#pages">Pages</a> • <a href="#config">Configuration</a> 
+</div>
+
+---
+
 **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.
@@ -29,6 +35,7 @@ Lookbook uses [RDoc/Yard-style comment tags](#annotating-preview-files) to exten
 - Use comment tag annotations for granular customisation of the preview experience
 - Fully compatible with standard the ViewComponent preview system
 - In-browser live-editable preview parameters (similar to basic Storybook Controls/Knobs)
+- [**Experimental**] Markdown-powerered documentation pages with embeddable previews
 
 ## Lookbook demo
 
@@ -73,13 +80,13 @@ If you would like to expose the Lookbook UI in production as well as in developm
 2. Add `config.view_component.show_previews = true` to `config/environments/production.rb`
 
 
-## Usage
+<h2 id="previews">Previews</h2>
 
 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.
 
 > 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).
 
-## Annotating preview files
+### Annotating preview files
 
 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:
 
@@ -474,11 +481,217 @@ class ProfileCardComponentPreview < ViewComponent::Preview
 end
 ```
 
-## Configuration
+---
+
+<h2 id="pages">🚧 Documentation Pages [experimental]</h2>
+
+If you need to add more long-form documentation to live alongside your component previews you can do so using Lookbook's markdown-powered `pages` system.
+
+> ⚠️ This feature is currently flagged as an **experimental** feature which requires [feature opt-in](#experimental-features) to use. Its API and implementation may change before it is released.
+> 
+> To enable support for pages in your project, add `config.lookbook.experimental_features = [:pages]` into your application configuration file.
+
+### Pages demo 
+
+For an example of some pages in Lookbook, check out the [example pages](https://lookbook-demo-app.herokuapp.com/lookbook) in the Lookbook demo app and the associated [page files](https://github.com/allmarkedup/lookbook-demo/tree/main/test/components/docs) in the demo repo.
+
+### Usage
+
+By default, pages should be placed in the `test/components/docs` directory (although this can be customised) and can be nested in directories as deeply as required.
+
+Pages must have  either a `.html.erb` or a `.md.erb` file extension. All pages are rendered as ERB templates but `.md.erb` files will also additionally be run through a markdown parser.
+
+Pages can optionally make use of a **YAML frontmatter block** to customise the behaviour and content of the page itself.
+
+An example page might look like this: 
+
+```markdown
+---
+title: An example page
+label: Nice example
+---
+
+This is an example page. If it has a `.md.erb` file extension its
+contents will be run through a Markdown parser/renderer before display.
+
+Fenced code blocks are fully supported and will be highlighted appropriately.
+
+ERB can be used in here.
+The template will be rendered **before** being parsed as Markdown. 
+
+You can can access data about the page using the `@page` variable.
+The title of this page is "<%= @page.title %>".
+```
+
+### YAML Frontmatter
+
+Pages can use an optional YAML frontmatter block to configure the behaviour of the page and to provide custom data, if required.
+
+The following page options can be customised via frontmatter:
+
+* `id` - a custom page ID that can be used for linking to it from other pages
+* `label` - The name of the page that will be displayed in the navigation (auto-generated from the file name if not set)
+* `title` - The main page title displayed on the page (defaults to the label value if not set).
+* `hidden` - If `false` the page will not appear in the navigation but will still be accessible at it's URL (useful for pages that are still in development) [default: `true`]
+* `landing` - Set to `true` to use the page as the Lookbook landing page [default: `false`]
+* `header` - Set to `false` to hide the page header containing the page title [default: `true`]
+* `footer` - Set to `false` to hide the page footer containing the previous/next page links [default: `true`]
+* `data` - Optional hash of custom data to make available for use in the page - see info on [page variables](#page-variables) below. [default: `{}`]
 
-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.
+#### Frontmatter defaults
 
-However the following Lookbook-specific config options are also available:
+You can set global default values for page options in the application configuration:
+
+```ruby
+# config/application.rb
+config.lookbook.page_options = {
+  footer: false,
+  data: {
+    brand_colors: {
+      red: #ff0000
+    }
+  }
+}
+```
+
+These will be merged with any page-level frontmatter data. Options set in the frontmatter will override those set at the global level (apart from `data`, which will be deep-merged with the any globally defined data).
+
+### Page variables
+
+All pages have the following variables available for use in the page template:
+
+* `@page` - The current page object
+* `@next_page` - The next page object (if available)
+* `@previous_page` - The previous page object (if available)
+* `@pages` - Collection of all pages
+
+Page objects have access to frontmatter variables:
+
+```ruby
+The page title is <%= @page.title %>
+
+Our brand color hex value is <%= @page.data[:brand_colors][:red] %>
+```
+
+### Ordering pages and directories
+
+If you want to enforce a specific order for pages and directories in the Lookbook navigation you can prefix the file/directory basename with an 'order number' integer value followed by an underscore or hyphen.
+
+For example: `01_example_page.md.erb` will be displayed first in the navigation (`01`) within the directory it is in.
+
+The integer value will be parsed out from the filename so that it doesn't appear in navigation labels or URLs, and the value itself will be used as a 'position' number when sorting the navigation items.
+
+For example, an ordered directory of pages might look like:
+
+```
+test/components/docs/
+  ├── 01_overview.md.erb
+  ├── 02_implementation_notes/
+  │   ├── 01_slots.md.erb
+  │   └── 02_html_attributes.md.erb
+  └── 03_helpful_examples/
+      ├── 01_basic_components.md.erb
+      └── 02_complex_components.md.erb
+```
+
+Without the number prefixes on the file names the pages may not have appeared in the navigation in the desired order.
+
+### Linking to other pages
+
+You can get the path to a page using the `page_path` helper. This accepts a page `id` (as a `Symbol`) or a page object:
+
+```markdown
+Visit the [about page](<%= page_path :about %>)
+
+Go to the [next page](<%= page_path @next_page %>)
+```
+
+Page ids can be set in the YAML frontmatter block for that page:
+
+```
+---
+id: about
+---
+
+This is the about page.
+```
+
+### Embedding previews
+
+You can embed preview examples from your project directly into the documentation pages using the `embed` helper, which renders an iframe with the rendered preview in it at any point in your document.
+
+The output looks like this:
+
+<img src=".github/assets/preview_embed.png">
+
+To specify which preview example to render, the helper accepts a preview class and a method name (as a symbol), like this:
+
+```erb
+<%= embed Elements:ButtonComponentPreview, :default %>
+```
+
+#### Preview params
+
+If you have configured your examples to accept preview params (see the [`@param`](#param-tag) docs), then you can supply values for those params when rendering the embedded preview:
+
+```erb
+<%= embed Elements:ButtonComponentPreview, :default, params: {
+  icon: "plus",
+  text: "Add new"
+} %>
+```
+
+### Displaying code
+
+You can use language-scoped [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) in the markdown file to render nicely highlighted code examples.
+
+However, if you are not using Markdown, or need a little more control, you can use the `code` helper instead:
+
+```erb
+<%= code do %>
+  # code goes here
+<% end %>
+```
+
+The default language is `ruby`. To highlight a different language you need to specify it's name as an argument:
+
+```erb
+<%= code :html do %>
+  <!-- code goes here -->
+<% end %>
+```
+
+> Lookbook uses [Rouge](https://github.com/rouge-ruby/rouge) for syntax highlighting. You can find a [full list of supported languages here](https://github.com/rouge-ruby/rouge/blob/master/docs/Languages.md).
+
+---
+
+### Pages configuration
+
+These options can be set in your application configuration files to customise the pages behaviour.
+
+#### `page_paths`
+
+An array of directories to look for pages in.
+Default: `["test/previews/docs"]`
+
+```ruby
+config.lookbook.page_paths = ["path/to/my/pages"]
+```
+
+#### `page_route`
+
+The URL segment used to prefix page routes.
+Default: `pages`
+
+```ruby
+config.lookbook.page_route = `docs`
+```
+
+<h2 id="config">General Configuration</h2>
+
+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 much else separately.
+
+However the following Lookbook-specific configuration options are also available:
 
 ### UI auto-refresh
 
@@ -508,6 +721,16 @@ config.lookbook.ui_favicon = "/path/to/my/favicon.png"
 
 > To disable the favicon entirely, set the value to `false`.
 
+### Project name
+
+Specify a project name to display in the top left of the UI (instead of the default "Lookbook"):
+
+```ruby
+config.lookbook.project_name = "My Project" 
+```
+
+> If you don't want to display a project name at all, set the value to `false`.
+
 
 <h3 id="experimental-features">Experimental features opt-in</h3>
 
@@ -523,6 +746,11 @@ To opt into individual experimental features, include the name of the feature in
 config.lookbook.experimental_features = ["feature_name"]
 ```
 
+The current experimental features that can be opted into are:
+
+- `pages`: Markdown-powered documentation pages with embeddable previews
+
+
 #### 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):

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

@@ -58,7 +58,7 @@
 }
 
 @layer components {
-  #nav > ul > li > div {
+  .unsectioned > #nav > ul > li > div {
     @apply py-1 border-b border-gray-300;
   }
 
@@ -87,7 +87,7 @@
   }
 
   .code.numbered {
-    @apply relative pt-3;
+    @apply relative;
   }
 
   .code.numbered:before {
@@ -97,7 +97,7 @@
   }
 
   .code.numbered .line {
-    padding-left: calc(2.7em + 8px);
+    padding-left: calc(2.7em + 14px);
     @apply relative;
   }
 
@@ -115,6 +115,18 @@
     @apply flex-none pr-4;
   }
 
+  .prose .code {
+    @apply !bg-white border border-gray-300 text-gray-600 my-8 text-sm rounded-md py-4 overflow-auto max-w-3xl w-full mx-auto;
+  }
+
+  .prose .code:not(.numbered) .line {
+    @apply px-4;
+  }
+
+  .prose .embed {
+    @apply my-8;
+  }
+
   .resize-handle {
     @apply flex items-center justify-center h-full w-full border-gray-300 bg-white hover:bg-indigo-100 hover:bg-opacity-20 text-gray-400 hover:text-gray-700 transition select-none touch-none;
   }

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

@@ -4,11 +4,13 @@ import Persist from "@alpinejs/persist";
 import Morph from "@alpinejs/morph";
 import Tooltip from "@ryangjchandler/alpine-tooltip";
 
+import app from "./components/app";
 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 sidebar from "./components/sidebar";
 import nav from "./components/nav";
 import navItem from "./components/nav-item";
 import navGroup from "./components/nav-group";
@@ -17,12 +19,14 @@ import tabs from "./components/tabs";
 import copy from "./components/copy";
 import code from "./components/code";
 import sizes from "./components/sizes";
+import embed from "./components/embed";
 
 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";
+import initPagesStore from "./stores/pages";
 
 // Plugins
 
@@ -37,10 +41,13 @@ Alpine.store("layout", initLayoutStore(Alpine));
 Alpine.store("nav", initNavStore(Alpine));
 Alpine.store("sidebar", initSidebarStore(Alpine));
 Alpine.store("inspector", initInspectorStore(Alpine));
+Alpine.store("pages", initPagesStore(Alpine));
 
 // Components
 
+Alpine.data("app", app);
 Alpine.data("page", page);
+Alpine.data("sidebar", sidebar);
 Alpine.data("splitter", splitter);
 Alpine.data("previewWindow", previewWindow);
 Alpine.data("copy", copy);
@@ -53,6 +60,7 @@ Alpine.data("nav", nav);
 Alpine.data("tabs", tabs);
 Alpine.data("navItem", navItem);
 Alpine.data("navGroup", navGroup);
+Alpine.data("embed", embed);
 
 // Init
 

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

@@ -0,0 +1,55 @@
+import createSocket from "../lib/socket";
+
+const morphOpts = {
+  key(el) {
+    return el.getAttribute("key") ? el.getAttribute("key") : el.id;
+  },
+  lookahead: false,
+  updating(el, toEl, childrenOnly, skip) {
+    if (
+      el.getAttribute &&
+      el.getAttribute("data-morph-strategy") === "replace"
+    ) {
+      el.innerHTML = toEl.innerHTML;
+      return skip();
+    }
+  },
+};
+
+export default function app() {
+  return {
+    init() {
+      if (window.SOCKET_PATH) {
+        const socket = createSocket(window.SOCKET_PATH);
+        socket.addListener("Lookbook::ReloadChannel", () => this.refresh());
+      }
+    },
+    async update() {
+      const response = await fetch(window.document.location);
+      if (!response.ok) return window.location.reload();
+      const html = await response.text();
+      const newDoc = new DOMParser().parseFromString(html, "text/html");
+      this.morph(newDoc);
+      document.title = newDoc.title;
+    },
+    setLocation(loc) {
+      let path;
+      if (loc instanceof Event) {
+        path = loc.currentTarget.href;
+        loc.preventDefault();
+      } else {
+        path = loc;
+      }
+      history.pushState({}, null, path);
+      this.$dispatch("popstate");
+    },
+    refresh() {
+      this.$dispatch("refresh");
+    },
+    morph(dom) {
+      const pageHtml = dom.getElementById(this.$root.id).outerHTML;
+      Alpine.morph(this.$root, pageHtml, morphOpts);
+      this.$dispatch("page:morphed");
+    },
+  };
+}

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

@@ -0,0 +1,89 @@
+import "iframe-resizer/js/iframeResizer";
+
+export default function embed() {
+  return {
+    init() {
+      if (!this.$store.pages.embeds[this.$root.id]) {
+        this.$store.pages.embeds[this.$root.id] = {
+          width: "100%",
+        };
+      }
+    },
+    lastWidth: null,
+    reflowing: false,
+    get resizer() {
+      if (this.$refs.iframe) {
+        if (!this.$refs.iframe.iFrameResizer) {
+          window.iFrameResize(
+            {
+              heightCalculationMethod: "lowestElement",
+              onResized: this.onIframeResized.bind(this),
+            },
+            this.$refs.iframe
+          );
+        }
+        return this.$refs.iframe.iFrameResizer;
+      }
+      return null;
+    },
+    set width(value) {
+      this.store.width = value;
+    },
+    get width() {
+      return this.store.width || "100%";
+    },
+    get height() {
+      return this.store.height;
+    },
+    get parentWidth() {
+      return Math.round(this.$root.parentElement.clientWidth);
+    },
+    get maxWidth() {
+      return this.width === "100%" ? "100%" : `${this.width}px`;
+    },
+    get store() {
+      return this.$store.pages.embeds[this.$root.id];
+    },
+    recaclulateIframeHeight() {
+      if (this.resizer) this.resizer.resize();
+    },
+    onIframeResized({ iframe, height }) {
+      if (iframe.isSameNode(this.$refs.iframe)) {
+        this.store.height = height;
+      }
+    },
+    onResizeWidth(e) {
+      const width =
+        this.resizeStartWidth - (this.resizeStartPositionX - e.pageX);
+      const boundedWidth = Math.min(
+        Math.max(Math.round(width), 200),
+        this.parentWidth
+      );
+      this.width = boundedWidth === this.parentWidth ? "100%" : boundedWidth;
+      this.recaclulateIframeHeight();
+    },
+    onResizeWidthStart(e) {
+      this.reflowing = true;
+      this.onResizeWidth = this.onResizeWidth.bind(this);
+      this.onResizeWidthEnd = this.onResizeWidthEnd.bind(this);
+      this.resizeStartPositionX = e.pageX;
+      this.resizeStartWidth = this.$refs.resizer.clientWidth;
+      window.addEventListener("pointermove", this.onResizeWidth);
+      window.addEventListener("pointerup", this.onResizeWidthEnd);
+    },
+    onResizeWidthEnd() {
+      window.removeEventListener("pointermove", this.onResizeWidth);
+      window.removeEventListener("pointerup", this.onResizeWidthEnd);
+      this.reflowing = false;
+    },
+    toggleFullWidth() {
+      if (this.width === "100%" && this.lastWidth) {
+        this.width = this.lastWidth;
+      } else {
+        this.lastWidth = this.width;
+        this.width = "100%";
+      }
+      this.$nextTick(() => this.recaclulateIframeHeight());
+    },
+  };
+}

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

@@ -3,6 +3,7 @@ export default function filter() {
     get active() {
       return this.$store.filter.active;
     },
+    focussed: false,
     checkEsc($event) {
       if ($event.key === "Escape") {
         this.active ? this.clear() : this.blur();
@@ -15,10 +16,20 @@ export default function filter() {
       if ($event && $event.target.tagName === "INPUT") {
         return;
       }
-      setTimeout(() => this.$refs.input.focus(), 0);
+      setTimeout(() => {
+        this.$dispatch("filter:focus");
+        this.$nextTick(() => {
+          this.focussed = true;
+          this.$refs.input.focus();
+        });
+      }, 0);
     },
     blur() {
-      setTimeout(() => this.$refs.input.blur(), 0);
+      setTimeout(() => {
+        this.focussed = false;
+        this.$refs.input.blur();
+        this.$dispatch("filter:blur");
+      }, 0);
     },
   };
 }

data/app/assets/lookbook/js/components/nav-group.js

@@ -1,5 +1,3 @@
-import { getAlpineData } from "../lib/utils";
-
 export default function navGroup() {
   return {
     hidden: false,
@@ -32,7 +30,7 @@ export default function navGroup() {
     filter(text) {
       this.hidden = true;
       this.getChildren().forEach((child) => {
-        const data = getAlpineData(child);
+        const data = Alpine.$data(child);
         data.filter(text);
         if (!data.hidden) {
           this.hidden = false;
@@ -41,9 +39,8 @@ export default function navGroup() {
     },
     firstVisibleChild() {
       return this.getChildren().find((child) => {
-        return child._x_dataStack
-          ? child._x_dataStack[0].hidden === false
-          : false;
+        const data = Alpine.$data(child);
+        return data.hidden === false;
       });
     },
   };

data/app/assets/lookbook/js/components/nav-item.js

@@ -12,7 +12,9 @@ export default function navItem(matchers) {
     },
     navigate() {
       this.setLocation(this.path);
-      this.$store.sidebar.open = false;
+      if (this.$store.layout.mobile) {
+        this.$store.sidebar.open = false;
+      }
     },
     filter(text) {
       this.hidden = false;

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

@@ -1,19 +1,18 @@
-import { getAlpineData } from "../lib/utils";
-
-export default function nav() {
+export default function nav(filterable = true) {
   return {
     empty: false,
     init() {
-      this.$watch("$store.filter.text", () => this.filter());
-      this.$nextTick(() => {
-        this.setActive();
-        this.filter();
-      });
+      if (filterable) {
+        this.$watch("$store.filter.text", () => this.filter());
+        this.$nextTick(() => {
+          this.filter();
+        });
+      }
     },
     filter() {
       this.empty = true;
       this.getChildren().forEach((child) => {
-        const data = getAlpineData(child);
+        const data = Alpine.$data(child);
         data.filter(this.$store.filter.text);
         if (!data.hidden) {
           this.empty = false;
@@ -25,11 +24,5 @@ export default function nav() {
         ? Array.from(this.$refs.items.querySelectorAll(":scope > li > div"))
         : [];
     },
-    setActive() {
-      const target = this.$el.querySelector(
-        `[data-path="${window.location.pathname}"]`
-      );
-      this.$store.nav.active = target ? target.id : "";
-    },
   };
 }