👀 Lookbook 👀

A native development UI for ViewComponent

> By default ViewComponent will use your default application layout for displaying the rendered example. However it's often better to create a seperate layout that you can customise and use specifically for previewing your components. See the  ViewComponent [preview docs](https://viewcomponent.org/guide/previews.html) for instructions on how to set that up.

Any `@display` params set at the preview (class) level with be merged with those set on individual example methods.

#### Global display params

Global (fallback) display params can be defined via a configuration option:

```ruby
# config/application.rb
config.lookbook.preview_display_params = {
  bg_color: "#fff",
  max_width: "100%"
}

# @display body_classes "bg-red border border-4 border-green"
# @display wrap_in_container true
# @display emojis_to_show 4
# @display page_title "Special example title"

# @display body_classes 'bg-red border border-4 border-green' [❌ single quotes]
# @display wrap_in_container should_wrap [❌ unquoted string, perhaps trying to call a method]
# @display page title "Special example title" [❌ space in key]
# @display bg_color #fff [❌ colors need quotes around them, it's not CSS!]

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

# @hidden
class ProfileCardComponentPreview < ViewComponent::Preview

  # Profile Card
  # ------------
  # Use the default profile card component whenever you need to represent a user.
  def default
  end
end

Lookbook will use the ViewComponent 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

> ⚠️ UI auto-refresh is only supported in Rails v6.0+

Disable/enable the auto-updating of the Lookbook UI when files change. Enabled by default.

config.lookbook.auto_refresh = false # default is true

By default Lookbook will listen for changes in any preview directories as well as in the components directory itself.

If you wish to add additional paths to listen for changes in, you can use the listen_paths option:

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:

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 😜

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 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 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.