lookbook 2.3.1 → 3.0.0.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 351a34443300be5a8f4a3f1125a915f6e831f1dfb32a3a24515a64d07ef7cbba
-  data.tar.gz: 6394415689d62a66ee39c4715471389a82cdc8116b84c2c0f971fba2813855a0
+  metadata.gz: e001a0495be9b2addbeb92aaf82dfa6152b19e3f038c9cb4846ef9cccbc938e3
+  data.tar.gz: b59f9ddfd438cd2e38d7a99d0196f0a8e98aa2355a50db0ba7e34e253b4cd1e2
 SHA512:
-  metadata.gz: 96cea87def8290537ecf96d5fee445e840e17c54800e1cbd1e9880abdbf6c44aa5c2f52f5e5f9911baec3e7c14c0b7480de89f0a0d3b7763baec5cb166e08225
-  data.tar.gz: 83cee3bec9ab9d4895c5da7ec8d82c5c674275964dbac2117c36d977403cdf70c86d9e0f53b2146ae73f1ca2bb8bf1e7368a9ac87157226d25439419e03ebb41
+  metadata.gz: 4175c9a8b770a18d9b873e94a607f52666cb66be489f9c7e6abf57c5edbc6249a3c54bccc2820efbf2f06a9dd70fd63e8c429eb51d102d905895336eaaf924c5
+  data.tar.gz: d4e4ad273d84d352f765cb7398e4e6b927fa094fd6b4ae9831855b90386c9df91cd6357cf1a98e90ad2de02ae62f1f066f41620e3d83641f5aa9ef3c1e501f97

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 Mark Perkins
+Copyright (c) 2021-present Mark Perkins & Lookbook contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

data/README.md

@@ -1,83 +1,107 @@
-<div align="center">
-<br>
-<p><a href="https://lookbook.build"><img src=".github/assets/lookbook_logo.svg" width="240"></a></p>
+<img src=".github/assets/lookbook_logo.svg" width="240">
 
-<p>A UI development environment for Ruby on Rails applications.</p>
+<hr>
 
-<p><strong><a href="https://lookbook.build">Documentation</a> &nbsp;|&nbsp; <a href="http://demo.lookbook.build/lookbook">Demo site</a></strong></p>
+## Lookbook v3.0 [development branch]
 
-<p><a href="https://rubygems.org/gems/lookbook"><img src="https://img.shields.io/gem/v/lookbook" alt="Gem version"></a>
-<a href="https://github.com/lookbook-hq/lookbook/actions/workflows/ci.yml"><img src="https://github.com/lookbook-hq/lookbook/actions/workflows/ci.yml/badge.svg" alt="CI status"></a></p>
+This branch contains a work-in-progress, exploratory, from-scratch rebuild of Lookbook, intended to form the basis of a future v3.0 release.
 
-</div>
+[Demo](#demo-site)  ・ [Documentation](#documentation)  ・ [Development](#development)
 
----
+![CI status](https://github.com/lookbook-hq/lookbook/actions/workflows/ci.yml/badge.svg?branch=v3)
 
-<div align="center">
-Lookbook combines a powerful <strong>component browser</strong> and <strong>preview system</strong> with an <strong>integrated documentation engine</strong> to help teams build robust, modular, maintainable user interfaces.<br><br>
-It's compatible with <a href="https://viewcomponent.org/">ViewComponent</a>, <a href="https://www.phlex.fun/">Phlex</a>, ActionView partials and more.
-<br><br>
-<a href="https://lookbook.build"><strong>Read the docs &rarr;</strong></a>
+## Demo site
 
-</div>
+You can find a hosted version of the [demo/test app](#demo-app) here: https://v3-demo-app.lookbook.build/lookbook
 
+This pulls directly from the `v3` development branch and so may occasionally be broken.
 
----
+## Documentation
 
-[![Lookbook UI](.github/assets/lookbook_ui.png)](http://lookbook.build/)
+v3-specific documentation is still very much a work in progress. The pages below should provide enough information if you wish to install the latest alpha release and test out some of the new features.
+
+* [Installing/Upgrading](./docs/alpha/01_usage.md)
+* [New features](./docs/alpha/02_new_features.md)
+* [Background and motivation](./docs/alpha/03_motivation.md)
+* [Development status](./docs/alpha/08_status.md)
+* [Troubleshooting/Known issues](./docs/alpha/09_troubleshooting.md)
 
 ## Development
 
-Lookbook is implemented as an isolated [Rails Engine](https://guides.rubyonrails.org/engines.html) and uses [ViewComponent](https://viewcomponent.org), [Tailwind](https://tailwindcss.com/) and [Alpine](https://alpinejs.dev/) for its UI.
+### Demo app
+
+The Lookbook v3 codebase includes a runnable dummy/demo app for development and testing purposes.
+
+To run the app, clone the contents of the `v3` branch to your machine and then run the following commands from within the root directory:
+
+```
+bundle install
+npm install
+bin/dev
+```
+
+Visit http://localhost:4444/lookbook to view the Lookbook UI.
 
-This repository contains:
+> In development mode assets will be rebuilt as changes are made but there is not yet any asset live-reloading in place.
 
-* The Lookbook source code ([`/app`](https://github.com/lookbook-hq/lookbook/tree/main/app), [`/lib`](https://github.com/lookbook-hq/lookbook/tree/main/lib), [`/config`](https://github.com/lookbook-hq/lookbook/tree/main/config), etc)
-* The Lookbook [documentation site](#docs-site) source code and content ([`/docs`](https://github.com/lookbook-hq/lookbook/tree/main/docs)).
-* A [test suite](#testing) with a 'runable' dummy app ([`/spec`](https://github.com/lookbook-hq/lookbook/tree/main/spec)).
+### Testing
+
+Run the tests:
+
+```
+bin/test
+```
+
+> Integration tests run against the demo app.
 
 ### Documentation site
 
-The [Lookbook docs site](https://lookbook.build) is built using [Bridgetown](https://www.bridgetownrb.com/) and the source files can be found in the `./docs` directory.
+Run the docs site locally in dev mode:
 
-To preview changes locally you can run a development version of the docs site:
+```
+bin/docs
+```
 
-1. Clone this repo
-2. Install dependencies: `bundle install`
-3. Start the app: `bin/docs`
-4. Visit http://localhost:4000 
+Visit http://localhost:4000 to view the docs. Not much to see there at the moment!
 
-### Testing
+### Logging and debugging
 
-Lookbook uses [RSpec](https://relishapp.com/rspec) for testing.
+`Lookbook` logs its activity to `Lookbook.logger`.
+This is the primary method of debugging.
 
-Tests can be run using the `rake spec` or `bundle exec rspec` commands.
+#### Custom logger
 
-The dummy app that the tests are being run against can be viewed by running the `bin/dummy` command and then browsing to http://localhost:9292/lookbook
+You can call `Lookbook.logger =` to set a custom `Lookbook` logger for the process. For example:
 
-### Releases
+```rb
+Lookbook.logger = Rails.logger
+```
 
-Lookbook uses [Release It!](https://github.com/release-it/release-it) to automate the release process.
+#### Default logger
 
-Running `npm run release` will start the process of publishing a new release and walks though all the steps from picking a version number to publishing the updated gem.
+If no custom logger is set, a default `Lookbook` logger which logs to to `STDERR` will be created and assigned to `Lookbook.logger`.
 
-Publishing a release requires write permissions for this repository (lookbook-hq/lookbook) and 2FA publish permissions for Lookbook on RubyGems.
+The default logger defaults to the `error` logging level (severity).
+You can override the logging level by setting the environment variable `LOOKBOOK_LOG_LEVEL=<level>`.
+For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
 
-## Contributing
+```bash
+export LOOKBOOK_LOG_LEVEL=debug
+export LOOKBOOK_LOG_LEVEL=info
+export LOOKBOOK_LOG_LEVEL=warn
+export LOOKBOOK_LOG_LEVEL=fatal
+export LOOKBOOK_LOG_LEVEL=error
+```
 
-Lookbook is an un-funded open source project and contributions of all types and sizes are most welcome!
+The default of `error` will be used if an unsupported value is set.
 
-Please take the time to read over the [Contributing](./CONTRIBUTING.md) guide before making your first contribution and if anything isn't clear then [start a discussion](https://github.com/lookbook-hq/lookbook/discussions) and we will do our best to help you out.
+#### Disabling logging
 
-## Contributors 
+If you want to disable `Lookbook` logging, set
 
-Lookbook was created by [Mark Perkins](https://github.com/allmarkedup) and continues to grow
-&amp; improve thanks to the ideas, suggestions and hard work of all of [these excellent humans](https://github.com/lookbook-hq/lookbook/graphs/contributors):
-<br>
-<br>
-<a href="https://github.com/lookbook-hq/lookbook/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=lookbook-hq/lookbook&columns=14" width="800" />
-</a>
+```rb
+Lookbook.logger = ::Logger.new('/dev/null')
+```
 
 ## License
 

data/app/components/lookbook/ui/app/app.css

@@ -0,0 +1,13 @@
+[data-component="app"] {
+  height: 100vh;
+  display: grid;
+  grid-template-rows: min-content 1fr;
+
+  &[data-status-bar="true"] {
+    grid-template-rows: min-content 1fr min-content;
+  }
+
+  main {
+    display: contents;
+  }
+}

data/app/components/lookbook/ui/app/app.html.erb

@@ -0,0 +1,24 @@
+<%= render component_tag(x: {data: "app", bind: "bindings.root"}, data: {status_bar: status_bar?.to_json}) do %>
+  <div id="app-header">
+    <%= header %>
+  </div>
+  
+  <% if pages.any? || previews.any? %>    
+    <%=
+      lb_pane_group("app-body", tag: :div, opts: body_split) do |body|
+        body.with_pane do
+          sidebar
+        end
+        body.with_pane { main }
+      end
+    %>
+  <% else %>
+    <%= main %>
+  <% end %>
+
+  <% if status_bar? %>
+    <footer id="app-status-bar">
+      <%= status_bar %>
+    </footer>  
+  <% end %>
+<% end %>

data/app/components/lookbook/ui/app/app.js

@@ -0,0 +1,30 @@
+import AlpineComponent from "@js/alpine/component";
+import Cookies from "js-cookie";
+
+export default AlpineComponent("app", () => {
+  return {
+    reflowing: false,
+
+    resetUI() {
+      Cookies.remove("lookbook-display-options");
+      Cookies.remove("lookbook-color-scheme");
+      Alpine.store("app").clear();
+      window.location.reload();
+      this.$logger.info(`Local storage cleared`);
+    },
+
+    bindings: {
+      root: {
+        ["@ui:resizing-start"]() {
+          this.reflowing = true;
+        },
+        ["@ui:resizing-end"]() {
+          this.reflowing = false;
+        },
+        ["@ui:reset"]() {
+          this.resetUI();
+        },
+      },
+    },
+  };
+});

data/app/components/lookbook/ui/app/app.rb

@@ -0,0 +1,26 @@
+module Lookbook
+  module UI
+    class App < BaseComponent
+      with_slot :header, Lookbook::UI::Header
+      with_slot :sidebar, Lookbook::UI::Sidebar
+      with_slot :main
+      with_slot :status_bar, Lookbook::UI::StatusBar
+
+      def body_split
+        {
+          orientation: :vertical,
+          sizes: ["280px", "auto"],
+          min_sizes: [200, 200]
+        }
+      end
+
+      def pages
+        Lookbook::Pages
+      end
+
+      def previews
+        Lookbook::Previews
+      end
+    end
+  end
+end

data/app/components/lookbook/ui/app/header/color_scheme_switcher/color_scheme_switcher.css

@@ -0,0 +1,69 @@
+[data-component="color-scheme-switcher"] {
+  display: block;
+  height: fit-content;
+  line-height: 1;
+
+  .switcher-button {
+    &,
+    &:hover,
+    &:active,
+    &.active {
+      color: currentColor;
+    }
+  }
+
+  .switcher-icon-light,
+  .switcher-icon-dark {
+    display: none;
+  }
+
+  [data-color-scheme="light"] & {
+    .switcher-icon-light {
+      display: block;
+    }
+  }
+
+  [data-color-scheme="dark"] & {
+    .switcher-icon-dark {
+      display: block;
+    }
+  }
+
+  .switcher-dropdown {
+    background-color: var(--lb-dropdown-background-color);
+    padding-block: var(--lb-spacing-2xs);
+    min-width: 9em;
+  }
+
+  .switcher-option {
+    color: var(--lb-color-scheme-switcher-button-color);
+    padding-block: var(--lb-spacing-xs);
+    padding-left: var(--lb-spacing-md);
+    padding-right: var(--lb-spacing-lg);
+    display: flex;
+    align-items: center;
+    column-gap: var(--lb-spacing-sm);
+    width: 100%;
+
+    .icon {
+      color: var(--lb-color-scheme-switcher-icon-color);
+    }
+
+    &:hover {
+      color: var(--lb-color-scheme-switcher-button-color-hover);
+
+      .icon {
+        color: var(--lb-color-scheme-switcher-icon-color-hover);
+      }
+    }
+
+    &.selected {
+      font-weight: var(--lb-font-weight-semibold);
+      color: var(--lb-color-scheme-switcher-button-color-selected);
+
+      .icon {
+        color: var(--lb-color-scheme-switcher-icon-color-selected);
+      }
+    }
+  }
+}

data/app/components/lookbook/ui/app/header/color_scheme_switcher/color_scheme_switcher.html.erb

@@ -0,0 +1,23 @@
+<%= render component_tag do %>
+  <%= lb_toolbar_button(class: "switcher-button") do |button| %>
+      <% button.with_dropdown do %>
+        <div class="switcher-dropdown" x-data="colorSchemeSwitcher">
+          <button class="switcher-option" @click="setScheme('light')" :class="{selected: isActiveScheme('light')}">
+            <%= lb_icon(:sun) %>
+            <span class="switcher-label">Light</span>
+          </button>
+          <button class="switcher-option" @click="setScheme('dark')" :class="{selected: isActiveScheme('dark')}">
+            <%= lb_icon(:moon) %>
+            <span class="switcher-label">Dark</span>
+          </button>
+          <button class="switcher-option" @click="setScheme('system')" :class="{selected: isActiveScheme('system')}">
+            <%= lb_icon(:monitor) %>
+            <span class="switcher-label">System</span>
+          </button>
+        </div>
+      <% end %>
+
+      <%= render Lookbook::UI::Icon.new(name: :sun, class: "switcher-icon-light") %>
+      <%= render Lookbook::UI::Icon.new(name: :moon, class: "switcher-icon-dark") %>
+    <% end %>
+<% end %>

data/app/components/lookbook/ui/app/header/color_scheme_switcher/color_scheme_switcher.js

@@ -0,0 +1,51 @@
+import AlpineComponent from "@js/alpine/component";
+import Cookies from "js-cookie";
+
+const colorSchemeCookie = "lookbook-color-scheme";
+
+export default AlpineComponent("colorSchemeSwitcher", () => {
+  const store = Alpine.store("app");
+  store.setDefault("colorScheme", "light");
+
+  return {
+    init() {
+      this.onSystemSchemeChange = this.onSystemSchemeChange.bind(this);
+      window
+        .matchMedia("(prefers-color-scheme: dark)")
+        .addEventListener("change", this.onSystemSchemeChange);
+    },
+
+    onSystemSchemeChange(event) {
+      this.applyScheme(event.matches ? "dark" : "light");
+    },
+
+    applyScheme(scheme) {
+      const schemeValue = scheme === "system" ? this.systemScheme : scheme;
+      document.documentElement.setAttribute("data-color-scheme", schemeValue);
+      Cookies.set(colorSchemeCookie, schemeValue);
+    },
+
+    setScheme(scheme) {
+      store.set("colorScheme", scheme);
+      this.applyScheme(scheme);
+      this.$nextTick(() => this.$dispatch("color-scheme:change"));
+    },
+
+    isActiveScheme(scheme) {
+      return store.get("colorScheme") === scheme;
+    },
+
+    destroy() {
+      window
+        .matchMedia("(prefers-color-scheme: dark)")
+        .removeEventListener("change", this.onSystemSchemeChange);
+    },
+
+    get systemScheme() {
+      return window.matchMedia &&
+        window.matchMedia("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light";
+    },
+  };
+});

data/app/components/lookbook/ui/app/header/color_scheme_switcher/color_scheme_switcher.rb

@@ -0,0 +1,6 @@
+module Lookbook
+  module UI
+    class ColorSchemeSwitcher < BaseComponent
+    end
+  end
+end

data/app/components/lookbook/ui/app/header/header.css

@@ -0,0 +1,68 @@
+[data-component="header"] {
+  height: var(--lb-size-3xl);
+  color: var(--lb-header-color);
+  background-color: var(--lb-header-background-color);
+  padding-inline: var(--lb-spacing-md);
+  padding-bottom: 1px;
+  display: flex;
+  align-items: center;
+
+  .header-branding {
+    display: flex;
+    align-items: center;
+    column-gap: var(--lb-spacing-sm);
+    margin-right: auto;
+  }
+
+  .header-project-logo {
+    height: 18px;
+    svg {
+      height: 100%;
+    }
+  }
+
+  .header-project-branding {
+  }
+
+  .header-project-links {
+    display: flex;
+    align-items: center;
+    column-gap: var(--lb-spacing-sm);
+
+    & + .header-color-scheme-switcher {
+      border-left: 1px solid var(--lb-color-content-1-accent);
+      margin-left: var(--lb-spacing-xl);
+    }
+  }
+
+  .header-project-link {
+    display: flex;
+    align-items: center;
+    white-space: nowrap;
+    column-gap: var(--lb-spacing-2xs);
+    font-size: var(--lb-font-size-xs);
+    padding-inline: var(--lb-spacing-2xs);
+    padding-block: var(--lb-spacing-xs);
+
+    span {
+      transition: opacity 300ms;
+      opacity: 0.8;
+    }
+
+    .icon {
+      width: 12px;
+      margin-left: 1px;
+      opacity: 0.6;
+    }
+
+    &:hover {
+      span {
+        opacity: 1;
+      }
+    }
+  }
+
+  .header-color-scheme-switcher {
+    margin-right: calc(-1 * var(--lb-spacing-md));
+  }
+}

data/app/components/lookbook/ui/app/header/header.html.erb

@@ -0,0 +1,33 @@
+<%= render component_tag(:header, x: {data: "header"}) do %>
+  <a href="<%= root_path %>" class="header-branding">
+    <div class="header-project-logo">
+      <svg viewBox="0 0 18 22" xmlns="http://www.w3.org/2000/svg">
+        <g stroke="currentColor" stroke-width="2" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M3.5 1H17v20H3.5A2.5 2.5 0 0 1 1 18.5v-15A2.5 2.5 0 0 1 3.5 1Z"></path>
+          <path d="M1.153 19.36c0-.737.261-1.188.596-1.57.417-.475.985-.79 1.751-.79H17M6.801 5.1v7.554L6.8 12.7h5.57"></path>
+        </g>
+      </svg>
+    </div>
+    <div class="header-project-name">
+      <%= project_name %>
+    </div>
+  </a>
+  
+  <% if project_links.any? %>
+    <nav class="header-project-links">
+      <% project_links.each do |link| %>
+        <%= link_to link.url, **(link.attrs || {}), class: "header-project-link" do %>
+          <span><%= link.label %></span>
+          <%= lb_icon(:external_link) %>
+        <% end %>
+      <% end %>
+    </nav>
+  <% end %>
+
+    
+  <% if config.ui_color_scheme_switcher %>
+    <div class="header-color-scheme-switcher">
+      <%= render Lookbook::UI::ColorSchemeSwitcher.new %>
+    </div>  
+  <% end %>
+<% end %>

data/app/components/lookbook/ui/app/header/header.js

@@ -0,0 +1,5 @@
+import AlpineComponent from "@js/alpine/component";
+
+export default AlpineComponent("header", () => {
+  return {};
+});

data/app/components/lookbook/ui/app/header/header.rb

@@ -0,0 +1,13 @@
+module Lookbook
+  module UI
+    class Header < BaseComponent
+      def project_name
+        Project.name.presence || "Lookbook"
+      end
+
+      def project_links
+        Project.links.reject { _1.show == false }
+      end
+    end
+  end
+end

data/app/components/lookbook/ui/app/router/router.css

@@ -0,0 +1,3 @@
+[data-component="router"] {
+  display: contents;
+}

data/app/components/lookbook/ui/app/router/router.html.erb

@@ -0,0 +1,13 @@
+<%= render component_tag(
+  :router,
+  x: {
+    data: "router(#{events_endpoint})",
+    "@click": "handleClick",
+    "@lookbook:visit": "visit($event.detail.url)",
+    "@lookbook:update": "updatePage",
+    "@error.window": "handleError",
+    "@popstate.window": "visit(location, false)",
+    "@visibilitychange.document": "handleVisibilityChange"
+  }) do %>
+  <%= content %>
+<% end %>