README.md in lookbook-0.5.0.beta.2 vs README.md in lookbook-0.5.0

- old
+ new

@@ -26,11 +26,11 @@ - Resizable preview window for responsive testing - Highlighted preview source code and HTML output - Auto-updating UI when component or preview files are updated _(Rails v6.0+ only)_ - Use comment tag annotations for granular customisation of the preview experience - Fully compatible with standard the ViewComponent preview system -- [**Experimental**] In-browser live editable preview parameters (similar to Storybook Controls/Knobs) +- In-browser live-editable preview parameters (similar to basic Storybook Controls/Knobs) ## 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. @@ -61,14 +61,20 @@ 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?` condition from around 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. +#### Mounting in Production + +If you would like to expose the Lookbook UI in production as well as in development + +1. Remove the `if Rails.env.development?` condition from around the mount statement in `routes.rb` +2. Add `config.view_component.show_previews = true` to `config/environments/production.rb` + + ## Usage 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). @@ -94,11 +100,11 @@ end # Button with icon # ---------------- # This example uses dynamic preview parameters - # which can be edited live in the Lookbook UI + # which can be edited live in the Lookbook UI # # @param text # @param icon select [heart, cog, alert] def icon(text: "Spread the love", icon: "heart") render ButtonComponent.new(icon: icon) do @@ -159,11 +165,11 @@ * [`@label`](#label-tag) * [`@display`](#display-tag) * [`@!group ... @!endgroup`](#group-tag) * [`@hidden`](#hidden-tag) -* [`@param`](#param-tag) [⚠️ **experimental!** - requires [feature opt-in](#experimental-features) ⚠️] +* [`@param`](#param-tag) <h3 id="label-tag">🏷 @label</h3> Used to replace the auto-generated navigation label for the item with `<text>`. @@ -309,14 +315,12 @@ def default end end ``` -<h3 id="param-tag"> 🚧 @param (experimental)</h3> +<h3 id="param-tag">@param</h3> -> ⚠️ This feature is currently flagged as an **experimental** feature which requires [feature opt-in](#experimental-features) to use. Its API and implementation may change in the future. - The `@param` tag provides the ability to specify **editable preview parameters** which can be changed in the Lookbook UI in order to customise the rendered output on the fly, much like the [Controls (knobs) addon](https://storybook.js.org/addons/@storybook/addon-controls) for Storybook. Each `@param` will have an associated form field generated for it. The values for each field will be handled as [dynamic preview params](https://viewcomponent.org/guide/previews.html#:~:text=It%E2%80%99s%20also%20possible%20to%20set%20dynamic%20values%20from%20the%20params%20by%20setting%20them%20as%20arguments%3A) when rendering the example. The `@param` tag takes the following format: @@ -324,11 +328,11 @@ ```ruby @param <name> <input_type> <opts?> ``` - `<name>` - name of the dynamic preview param -- `<input_type>` - input field type to generate in the UI +- `<input_type>` - input field type to generate in the UI - `<opts?>` - YAML-encoded field options, used for some field types #### Input types The following **input field types** are available for use: @@ -355,11 +359,11 @@ ```ruby @param <name> select <options> ``` -`<options>` should be a [YAML array](https://yaml.org/YAML_for_ruby.html#simple_inline_array) of options which must be formatted in the same style as the input for Rails' [`options_for_select`](https://apidock.com/rails/v6.0.0/ActionView/Helpers/FormOptionsHelper/options_for_select) helper: +`<options>` should be a [YAML array](https://yaml.org/YAML_for_ruby.html#simple_inline_array) of options which must be formatted in the same style as the input for Rails' [`options_for_select`](https://apidock.com/rails/v6.0.0/ActionView/Helpers/FormOptionsHelper/options_for_select) helper: ```ruby # Basic options: # @param theme select [primary, secondary, danger] @@ -435,11 +439,11 @@ #### Full example: ```ruby class ButtonComponentPreview < ViewComponent::Preview - + # The params defined below will be editable in the UI: # # @param content text # @param theme select [primary, secondary, danger] # @param arrow toggle @@ -494,10 +498,21 @@ ```ruby config.lookbook.listen_paths << Rails.root.join('app/other/directory') ``` +### Custom favicon + +If you want to change the favicon used by the Lookbook UI, you can provide a path to your own (or a data-uri string) using the `ui_favicon` option: + +```ruby +config.lookbook.ui_favicon = "/path/to/my/favicon.png" +``` + +> To disable the favicon entirely, set the value to `false`. + + <h3 id="experimental-features">Experimental features opt-in</h3> Some features may occasionally be released behind a 'experimental' feature flag while they are being tested and refined, to allow people to try them out and provide feedback. > ⚠️ **Please note:** Experimental features should be considered to be **subject to extensive change** and breaking changes to them may be made within point releases - these features are **not** considered to be covered by [semver](https://semver.org/) whilst flagged as 'experimental'. ⚠️ @@ -508,14 +523,10 @@ ```ruby config.lookbook.experimental_features = ["feature_name"] ``` -The current experimental features that can be opted into are: - -- `params`: Live-editable, dynamic preview parameters ([read more](#param-tag)). Include `"params"` in the `experimental_features` config option to opt in. - #### 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): ```ruby @@ -527,12 +538,13 @@ 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 +- `s` - Switch to Source tab in the drawer +- `n` - Switch to Notes tab in the drawer +- `v` - Switch to the rendered preview +- `o` - Switch to the code preview - `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