README.md in lookbook-0.2.1 vs README.md in lookbook-0.2.2
- old
+ new
@@ -1,15 +1,20 @@
<div align="center">
- <h2>Lookbook</h2>
+<h1>👀 Lookbook 👀</h1>
-👀 A native development UI for [ViewComponent](http://viewcomponent.org/) 👀
+<p>A native development UI for <a href="http://viewcomponent.org/">ViewComponent</a></p>
+<div>
+<a href="https://rubygems.org/gems/lookbook"><img src="https://badge.fury.io/rb/lookbook.svg" alt="Gem version">
+<a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide">
+<a href="https://github.com/prettier/prettier"><img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg" alt="Code style: Prettier">
</div>
+</div>
---
-Lookbook gives [ViewComponent](http://viewcomponent.org/)-based projects a _ready-to-go_ development UI for navigating, inspecting and interacting with component previews.
+**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.
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.
@@ -36,22 +41,17 @@
> ⚠️ **Please note:** Lookbook is still in the early stages of development and has not yet been well tested across a wide range of Rails/ViewComponent versions and setups. If you run into any problems please [open an issue](issues) with as much detail as possible. Thanks! ⚠️
### 1. Add as a dependency
-In your `Gemfile` add:
+Add Lookbook to your `Gemfile` somewhere **after** the ViewComponent gem. For example:
```ruby
+gem "view_component", require: "view_component/engine"
gem "lookbook"
```
-or
-
-```bash
-gem install lookbook
-```
-
### 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
@@ -68,128 +68,113 @@
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.
+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.
-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, of course).
+> 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).
-> 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.
+### Annotating preview files
-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.
+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:
-### Comment tags
+```ruby
+# @label Basic Button
+class ButtonComponentPreview < ViewComponent::Preview
-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.
+ # Primary button
+ # ---------------
+ # This is the button style you should use for most things.
+ #
+ # @label Primary
+ def default
+ render ButtonComponent.new do
+ "Click me"
+ end
+ end
-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:
+ # Secondary button
+ # ---------------
+ # This should be used for less important actions.
+ def secondary
+ render ButtonComponent.new(style: :secondary) do
+ "Click me"
+ end
+ end
-```ruby
-# This is a class-level comment.
-# @hidden
-class MyClass
- # This is a method-level comment.
+ # Unicorn button
+ # ---------------
+ # This button style is still a **work in progress**.
+ #
# @hidden
- def my_method
+ def secondary
+ render ButtonComponent.new do
+ "Click me"
+ end
end
end
```
-Some tags can also require additional arguments. Further information on the tags Lookbook uses are detailed in the docs below.
+**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.
-### 📝 Adding notes to previews
+The following Lookbook-specific tags are available for use:
-Lookbook lets you add notes to your preview examples which are then displayed in the inspector panel. They look something like this:
+#### `@label <text>`
-<img src=".github/assets/preview_example_notes.png" width="400">
+Used to replace the auto-generated navigation label for the item with `<text>`.
-Notes are generated from comments above example methods in your preview files. Below is an example of two preview examples that both have notes:
+> Available for preview classes & example methods.
```ruby
-class ButtonComponentPreview < ViewComponent::Preview
+# @label Preview Label
+class FooComponentPreview < 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.
+ # @label Example Label
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
+#### `@hidden`
-Lookbook generates a nested navigation menu based on the file structure of your component preview directory (or directories). This can be customised in a number of ways.
+Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
-#### Preview and example labels
+Can be useful when a component (or a variant of a component) is still in development and is not ready to be shared with the wider team.
-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.
+> Available for both preview classes & example methods.
-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
+# @hidden
+class FooComponentPreview < ViewComponent::Preview
- # @label Icon Button
- def with_icon
+ # @hidden
+ def default
end
end
```
-In the example above, the preview and example would be displayed like this:
+#### Adding notes
-<img src=".github/assets/nav_labels.png" width="200">
+All comment text other than tags will be treated as markdown and rendered in the **Notes** panel for that example in the Lookbook UI.
-#### Excluding previews and/or examples from the navigation
-
-Sometimes you may want to temporarily hide a preview or an individual example from 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** include the `@hidden` tag in a class comment:
-
```ruby
# @hidden
-class MyComponentPreview < ViewComponent::Preview
- # examples here....
-end
-```
+class ProfileCardComponentPreview < ViewComponent::Preview
-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
- # ...
+ # Profile Card
+ # ------------
+ # Use the default profile card component whenever you need to represent a user.
+ def default
end
-
- def a_visible_example
- # ...
- end
-
- # @hidden
- def another_hidden_example
- # ...
- end
end
```
+<img src=".github/assets/preview_example_notes.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.
+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.
However the following Lookbook-specific config options are also available:
### UI auto-refresh