lookbook 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30e9c49fca5a575af92323c59fd35018ddcd92798939a87286915060f2f93401
+  data.tar.gz: d90162b2ea72fcc7fc5fe38478b3ced236649421fdc08f0554acead3f5a41213
+SHA512:
+  metadata.gz: 7dcac40f9c516acbb996dae1ab5e26026fe7a98cd607b066572f22a958101d5cdad4b447a9d50348f694f198b5dba3f10682d8236dfc9eb0ea0ff4c415c177e0
+  data.tar.gz: 372f92f28d094d502dafe5acdc7ce243034542432a33ac5fa1075f62cb1aebfeed3f02913cabc08690b467b6bd16b46d380cdfb2c1dfd3c16bd814d03773c18e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 allmarkedup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

data/README.md

@@ -0,0 +1,257 @@
+<div align="center">
+  <h2>Lookbook</h2>
+
+👀 A native development UI for [ViewComponent](http://viewcomponent.org/) 👀
+
+</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) and is intended to integrate seamlessly with existing component libraries.
+
+Lookbook uses [RDoc/Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) to extend the capabilities of ViewComponent's previews whilst maintaining compatability with the standard preview class format, so you can add or remove Lookbook at any time without having to rework your code.
+
+> ⚠️ **PLEASE NOTE!** Lookbook is very much a **work in progress** at the moment. There may be breaking changes on point-releases before a 1.0 version is ready. ⚠️
+
+![Lookbook UI](.github/assets/lookbook_screenshot.png)
+
+### Features
+
+- 👀 Navigate your component previews with ease
+- 🔍 Search/filter previews
+- 🖥 Resizable, responsive preview window
+- 🔦 Highlighted preview source code and HTML output (with one-click copy to clipboard)
+- 📝 Add notes via comments in the preview file (markdown supported)
+- 🚀 Live UI, auto-updates when component or previews files are updated
+- 🙈 Supports 'hidden' previews and examples
+
+## Lookbook demo
+
+If you want to have a quick play with Lookbook, the easiest way is to [give the demo app](https://github.com/allmarkedup/lookbook-demo) a spin. It's a basic Rails/ViewComponent app with a few test components included to tinker with.
+
+The [demo app repo](https://github.com/allmarkedup/lookbook-demo) contains instructions on how to get it up and running.
+
+## Installing
+
+Lookbook is current a work in progress and **has not been published as a Gem** yet.
+
+If you wish to play with it in it's current state you can include it directly from Github using the instructions below.
+
+### 1. Add as a dependency
+
+In your `Gemfile` add:
+
+```ruby
+gem "lookbook", '>= 0.1', git: "https://github.com/allmarkedup/lookbook", branch: "main"
+```
+
+This line should be placed <strong>below</strong> wherever you have specified the `view_component` gem.
+
+### 2. Mount the Lookbook engine
+
+You then need to mount the Lookbook engine (at a path of your choosing) in your `routes.rb` file:
+
+```ruby
+Rails.application.routes.draw do
+  # any other routes...
+  if Rails.env.development?
+    mount Lookbook::Engine, at: "/lookbook"
+  end
+end
+```
+
+The `at` property determines the root URL that the Lookbook UI will be served at.
+
+> If you would like to expose the Lookbook UI in production as well as in development, just remove the `if Rails.env.development?` wrapper from the mount statement.
+
+Then you can start your app as normal and navigate to `http://localhost:3000/lookbook` (or whatever mount path you specified) to view your component previews in the Lookbook UI.
+
+## Usage
+
+You don't need to do anything special to create ViewComponent previews for Lookbook.
+
+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).
+
+> 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.
+
+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.
+
+### Comment tags
+
+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.
+
+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:
+
+```ruby
+# This is a class-level comment.
+# @hidden
+class MyClass
+  # This is a method-level comment.
+  # @hidden
+  def my_method
+  end
+end
+```
+
+Some tags can also require additional arguments. Further informatin on the tags Lookbook uses are detailed in the docs below.
+
+### 📝 Adding notes to previews
+
+Lookbook lets you add notes to your preview examples which are then displayed in the inspector panel. They look something like this:
+
+<img src=".github/assets/preview_example_notes.png" width="400">
+
+Notes are generated from comments above example methods in your preview files. Below is an example of two preview examples that both have notes:
+
+```ruby
+class ButtonComponentPreview < 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.
+  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
+
+Lookbook generates a nested navigation menu based on the file structure of your component preview directories. This can be customised in a number of ways.
+
+#### Preview and example labels
+
+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:
+
+```ruby
+# @label Standard Button
+class BtnPreview < ViewComponent::Preview
+
+  # @label Icon Button
+  def with_icon
+  end
+end
+```
+
+In the example above, the preview and example would be displayed like this:
+
+<img src=".github/assets/nav_labels.png" width="200">
+
+#### Excluding previews and/or examples from the navigation
+
+Sometimes you may want a preview or an individual example to be 'hidden' in 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.
+
+To **hide an entire preview** so that it no longer shows up in the , include the `@hidden` tag in a class comment:
+
+```ruby
+# @hidden
+class MyComponentPreview < ViewComponent::Preview
+  # examples here....
+end
+```
+
+To **hide an individual example**, include the `@hidden` tag in the appropriate method comment:
+
+```ruby
+class MyComponentPreview < ViewComponent::Preview
+
+  # Hidden Example
+  # ----------
+  # You won't see this in the nav!
+  #
+  # @hidden
+  def hidden_example
+    # ...
+  end
+
+  def a_visible_example
+    # ...
+  end
+
+  # @hidden
+  def another_hidden_example
+    # ...
+  end
+end
+```
+
+### 🔦 Viewing source code and rendered HTML output
+
+Lookbook displays the source code of the current preview (or the contents of preview template, if one is being used), right underneath the rendered preview itself:
+
+<img src=".github/assets/preview_source.png" width="400">
+
+You can also inspect the HTML output of the rendered preview (without any of the layout cruft):
+
+<img src=".github/assets/preview_output.png" width="400">
+
+All code panels have a 'copy-to-clipboard' button at the top right of the panel, just click it to copy the un-highlighted code to your clipboard.
+
+<img src=".github/assets/copy_to_clipboard.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.
+
+However the following Lookbook-specific config options are also available:
+
+### UI auto-refresh
+
+Disable/enable the auto-updating of the Lookbook UI when files change. Enabled by default.
+
+```ruby
+config.lookbook.auto_refresh = false # default is true
+```
+
+By default Lookbook will listen for changes in any [preview directories](https://viewcomponent.org/api.html#preview_paths) as well as in the [components directory](config.view_component.preview_paths) itself.
+
+If you wish to add additional paths to listen for changes in, you can use the `listen_paths` option:
+
+```ruby
+config.lookbook.listen_paths << Rails.root.join('app/other/directory')
+```
+
+## 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 😜
+
+However, I'm a frontend developer - not a Rails dev - so any thoughts, advice or PRs on how to improve the codebase will be always much appreciated. 🍻
+
+### Developing on a local version of Lookbook
+
+The quickest way to get a development version of Lookbook up and running is to use the [lookbook-demo](https://github.com/allmarkedup/lookbook-demo) app and link it to a local version of the Lookbook gem:
+
+#### Initial setup:
+
+1. Clone this repository somewhere on your machine - `git clone git@github.com:allmarkedup/lookbook.git`
+2. Also pull down the [lookbook-demo](https://github.com/allmarkedup/lookbook-demo) repository to your machine
+3. In the `Gemfile` of the `lookbook-demo` repository, replace `gem "lookbook", '>= 0.1', git: "https://github.com/allmarkedup/lookbook", branch: "main"` with `gem "lookbook", path: "../path/to/lookbook"` (use the path to your local copy of lookbook)
+4. Install dependencies - from the root of the parent project run `bundle install`
+
+#### Starting development
+
+1. From within the `lookbook` root directory run the comand `npm run dev` (this will make sure the CSS/JS is recompiled if/when you make changes to the UI)
+2. From within the `lookbook-demo` root directory run `npm run start` - this will start a server and build the demo assets
+
+Point your browser to http://localhost:3000/lookbook to see the UI. You can then make and test changes to the Lookbook code in your local copy of lookbook repo. PRs are welcome if you add anything useful :-)
+
+> Note that changes to files in the Lookbook `lib/` directory will require a server restart in order to have them applied.
+
+#### Tests
+
+You can run the tests from within the `lookbook` root directory with the `rake test` command.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -0,0 +1,37 @@
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";
+@import "tippy.js/dist/tippy";
+@import "code_theme";
+@import "tooltip_theme";
+
+@layer base {
+  html {
+    scroll-behavior: smooth;
+  }
+
+  @media screen and (prefers-reduced-motion: reduce) {
+    html {
+      scroll-behavior: auto;
+    }
+  }
+
+  [x-cloak] {
+    display: none !important;
+  }
+
+  pre[class*="language-"] {
+    padding: 0 !important;
+    margin: 0 !important;
+  }
+
+  .feather {
+    width: 24px;
+    height: 24px;
+    stroke: currentColor;
+    stroke-width: 2;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+    fill: none;
+  }
+}

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

@@ -0,0 +1,214 @@
+/*
+ * GitHub style for Pygments
+ * Courtesy of GitHub.com
+ */
+
+.highlight .hll {
+  background-color: #f8f8f8;
+  border: 1px solid #ccc;
+  padding: 6px 10px;
+  border-radius: 3px;
+}
+.highlight .c {
+  color: #999988;
+  font-style: italic;
+}
+.highlight .err {
+  color: #a61717;
+  background-color: #e3d2d2;
+}
+.highlight .k {
+  font-weight: bold;
+}
+.highlight .o {
+  font-weight: bold;
+}
+.highlight .cm {
+  color: #999988;
+  font-style: italic;
+}
+.highlight .cp {
+  color: #999999;
+  font-weight: bold;
+}
+.highlight .c1 {
+  color: #999988;
+  font-style: italic;
+}
+.highlight .cs {
+  color: #999999;
+  font-weight: bold;
+  font-style: italic;
+}
+.highlight .gd {
+  color: #000000;
+  background-color: #ffdddd;
+}
+.highlight .gd .x {
+  color: #000000;
+  background-color: #ffaaaa;
+}
+.highlight .ge {
+  font-style: italic;
+}
+.highlight .gr {
+  color: #aa0000;
+}
+.highlight .gh {
+  color: #999999;
+}
+.highlight .gi {
+  color: #000000;
+  background-color: #ddffdd;
+}
+.highlight .gi .x {
+  color: #000000;
+  background-color: #aaffaa;
+}
+.highlight .go {
+  color: #888888;
+}
+.highlight .gp {
+  color: #555555;
+}
+.highlight .gs {
+  font-weight: bold;
+}
+.highlight .gu {
+  color: #800080;
+  font-weight: bold;
+}
+.highlight .gt {
+  color: #aa0000;
+}
+.highlight .kc {
+  font-weight: bold;
+}
+.highlight .kd {
+  font-weight: bold;
+}
+.highlight .kn {
+  font-weight: bold;
+}
+.highlight .kp {
+  font-weight: bold;
+}
+.highlight .kr {
+  font-weight: bold;
+}
+.highlight .kt {
+  color: #445588;
+  font-weight: bold;
+}
+.highlight .m {
+  color: #009999;
+}
+.highlight .s {
+  color: #dd1144;
+}
+.highlight .n {
+  color: #333333;
+}
+.highlight .na {
+  color: teal;
+}
+.highlight .nb {
+  color: #0086b3;
+}
+.highlight .nc {
+  color: #445588;
+  font-weight: bold;
+}
+.highlight .no {
+  color: teal;
+}
+.highlight .ni {
+  color: purple;
+}
+.highlight .ne {
+  color: #990000;
+  font-weight: bold;
+}
+.highlight .nf {
+  color: #990000;
+  font-weight: bold;
+}
+.highlight .nn {
+  color: #555555;
+}
+.highlight .nt {
+  color: navy;
+}
+.highlight .nv {
+  color: teal;
+}
+.highlight .ow {
+  font-weight: bold;
+}
+.highlight .w {
+  color: #bbbbbb;
+}
+.highlight .mf {
+  color: #009999;
+}
+.highlight .mh {
+  color: #009999;
+}
+.highlight .mi {
+  color: #009999;
+}
+.highlight .mo {
+  color: #009999;
+}
+.highlight .sb {
+  color: #dd1144;
+}
+.highlight .sc {
+  color: #dd1144;
+}
+.highlight .sd {
+  color: #dd1144;
+}
+.highlight .s2 {
+  color: #dd1144;
+}
+.highlight .se {
+  color: #dd1144;
+}
+.highlight .sh {
+  color: #dd1144;
+}
+.highlight .si {
+  color: #dd1144;
+}
+.highlight .sx {
+  color: #dd1144;
+}
+.highlight .sr {
+  color: #009926;
+}
+.highlight .s1 {
+  color: #dd1144;
+}
+.highlight .ss {
+  color: #990073;
+}
+.highlight .bp {
+  color: #999999;
+}
+.highlight .vc {
+  color: teal;
+}
+.highlight .vg {
+  color: teal;
+}
+.highlight .vi {
+  color: teal;
+}
+.highlight .il {
+  color: #009999;
+}
+.highlight .gc {
+  color: #999;
+  background-color: #eaf2f5;
+}