lookbook 0.9.0 → 1.0.0.beta.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +90 -824
- data/app/assets/lookbook/css/lookbook.css +55 -0
- data/app/assets/lookbook/css/themes/blue.css +42 -0
- data/app/assets/lookbook/css/themes/indigo.css +42 -0
- data/app/assets/lookbook/css/themes/zinc.css +42 -0
- data/app/assets/lookbook/css/{tooltip_theme.css → tooltip.css} +14 -8
- data/app/assets/lookbook/js/app.js +64 -63
- data/app/assets/lookbook/js/components/clipboard.js +47 -0
- data/app/assets/lookbook/js/components/tooltip.js +30 -0
- data/app/assets/lookbook/js/config.js +7 -4
- data/app/assets/lookbook/js/helpers/build.js +22 -0
- data/app/assets/lookbook/js/helpers/dom.js +45 -0
- data/app/assets/lookbook/js/helpers/layout.js +21 -0
- data/app/assets/lookbook/js/helpers/request.js +16 -0
- data/app/assets/lookbook/js/helpers/string.js +11 -0
- data/app/assets/lookbook/js/lib/socket.js +4 -3
- data/app/assets/lookbook/js/lib/tippy.js +8 -0
- data/app/assets/lookbook/js/lookbook.js +61 -0
- data/app/assets/lookbook/js/plugins/logger.js +39 -0
- data/app/assets/lookbook/js/stores/filter.js +2 -2
- data/app/assets/lookbook/js/stores/inspector.js +23 -17
- data/app/assets/lookbook/js/stores/layout.js +101 -5
- data/app/assets/lookbook/js/stores/nav.js +17 -16
- data/app/assets/lookbook/js/stores/pages.js +4 -2
- data/app/assets/lookbook/js/stores/settings.js +7 -0
- data/app/assets/lookbook/js/stores/workbench.js +29 -0
- data/app/components/lookbook/button/component.html.erb +28 -0
- data/app/components/lookbook/button/component.js +55 -0
- data/app/components/lookbook/button/component.rb +39 -0
- data/app/components/lookbook/button_group/component.html.erb +3 -0
- data/app/components/lookbook/button_group/component.rb +18 -0
- data/app/components/lookbook/code/component.css +57 -0
- data/app/components/lookbook/code/component.html.erb +10 -0
- data/app/components/lookbook/code/component.js +3 -0
- data/app/components/lookbook/code/component.rb +56 -0
- data/app/components/lookbook/code/highlight_github_light.css +217 -0
- data/app/components/lookbook/component.rb +41 -0
- data/app/components/lookbook/copy_button/component.html.erb +11 -0
- data/app/components/lookbook/copy_button/component.js +16 -0
- data/app/components/lookbook/copy_button/component.rb +23 -0
- data/app/components/lookbook/dimensions_display/component.html.erb +11 -0
- data/app/components/lookbook/dimensions_display/component.js +37 -0
- data/app/components/lookbook/dimensions_display/component.rb +18 -0
- data/app/components/lookbook/embed/component.html.erb +50 -0
- data/app/components/lookbook/embed/component.js +39 -0
- data/app/components/lookbook/embed/component.rb +22 -0
- data/app/components/lookbook/filter/component.html.erb +17 -0
- data/app/components/lookbook/filter/component.js +21 -0
- data/app/components/lookbook/filter/component.rb +15 -0
- data/app/components/lookbook/header/component.html.erb +79 -0
- data/app/components/lookbook/header/component.rb +9 -0
- data/app/components/lookbook/icon/component.css +11 -0
- data/app/components/lookbook/icon/component.html.erb +5 -0
- data/app/components/lookbook/icon/component.js +5 -0
- data/app/components/lookbook/icon/component.rb +23 -0
- data/app/components/lookbook/nav/component.html.erb +33 -0
- data/app/components/lookbook/nav/component.js +52 -0
- data/app/components/lookbook/nav/component.rb +37 -0
- data/app/components/lookbook/nav/item/component.html.erb +23 -0
- data/app/components/lookbook/nav/item/component.js +66 -0
- data/app/components/lookbook/nav/item/component.rb +84 -0
- data/app/components/lookbook/page_tabs/component.html.erb +18 -0
- data/app/components/lookbook/page_tabs/component.rb +19 -0
- data/app/components/lookbook/params_editor/component.html.erb +3 -0
- data/app/components/lookbook/params_editor/component.js +12 -0
- data/app/components/lookbook/params_editor/component.rb +11 -0
- data/app/components/lookbook/params_editor/field/component.html.erb +50 -0
- data/app/components/lookbook/params_editor/field/component.js +36 -0
- data/app/components/lookbook/params_editor/field/component.rb +41 -0
- data/app/components/lookbook/prose/component.css +12 -0
- data/app/components/lookbook/prose/component.html.erb +3 -0
- data/app/components/lookbook/prose/component.rb +26 -0
- data/app/components/lookbook/split_layout/component.html.erb +13 -0
- data/app/components/lookbook/split_layout/component.js +151 -0
- data/app/components/lookbook/split_layout/component.rb +11 -0
- data/app/components/lookbook/tab_panels/component.html.erb +5 -0
- data/app/components/lookbook/tab_panels/component.js +25 -0
- data/app/components/lookbook/tab_panels/component.rb +20 -0
- data/app/components/lookbook/tab_panels/panel/component.html.erb +8 -0
- data/app/components/lookbook/tab_panels/panel/component.rb +9 -0
- data/app/components/lookbook/tabs/component.css +8 -0
- data/app/components/lookbook/tabs/component.html.erb +20 -0
- data/app/components/lookbook/tabs/component.js +115 -0
- data/app/components/lookbook/tabs/component.rb +28 -0
- data/app/components/lookbook/tabs/dropdown_tab/component.html.erb +20 -0
- data/app/components/lookbook/tabs/dropdown_tab/component.rb +17 -0
- data/app/components/lookbook/tabs/tab/component.html.erb +24 -0
- data/app/components/lookbook/tabs/tab/component.rb +17 -0
- data/app/components/lookbook/tag_component.rb +29 -0
- data/app/components/lookbook/toolbar/component.css +16 -0
- data/app/components/lookbook/toolbar/component.html.erb +5 -0
- data/app/components/lookbook/toolbar/component.rb +26 -0
- data/app/components/lookbook/viewport/component.css +11 -0
- data/app/components/lookbook/viewport/component.html.erb +57 -0
- data/app/{assets/lookbook/js/components/preview-window.js → components/lookbook/viewport/component.js} +57 -14
- data/app/components/lookbook/viewport/component.rb +21 -0
- data/app/controllers/lookbook/application_controller.rb +16 -5
- data/app/controllers/lookbook/pages_controller.rb +17 -8
- data/app/controllers/lookbook/previews_controller.rb +130 -89
- data/app/helpers/lookbook/application_helper.rb +6 -2
- data/app/helpers/lookbook/component_helper.rb +22 -10
- data/app/helpers/lookbook/output_helper.rb +8 -4
- data/app/helpers/lookbook/page_helper.rb +13 -21
- data/app/views/layouts/lookbook/application.html.erb +76 -28
- data/app/views/layouts/lookbook/inspector.html.erb +7 -0
- data/app/views/layouts/lookbook/page.html.erb +53 -0
- data/app/views/layouts/lookbook/shell.html.erb +64 -0
- data/app/views/layouts/lookbook/skeleton.html.erb +27 -10
- data/app/views/layouts/lookbook/standalone.html.erb +5 -0
- data/app/views/lookbook/404.html.erb +15 -0
- data/app/views/lookbook/error.html.erb +34 -34
- data/app/views/lookbook/index.html.erb +11 -6
- data/app/views/lookbook/pages/show.html.erb +37 -91
- data/app/views/{layouts/lookbook → lookbook}/preview.html.erb +6 -8
- data/app/views/lookbook/previews/panels/_content.html.erb +13 -0
- data/app/views/lookbook/previews/panels/_notes.html.erb +19 -25
- data/app/views/lookbook/previews/panels/_output.html.erb +7 -18
- data/app/views/lookbook/previews/panels/_params.html.erb +13 -15
- data/app/views/lookbook/previews/panels/_preview.html.erb +6 -52
- data/app/views/lookbook/previews/panels/_source.html.erb +6 -15
- data/app/views/lookbook/previews/show.html.erb +133 -24
- data/config/routes.rb +5 -5
- data/lib/lookbook/code_formatter.rb +37 -13
- data/lib/lookbook/collection.rb +19 -16
- data/lib/lookbook/config.rb +180 -0
- data/lib/lookbook/engine.rb +66 -59
- data/lib/lookbook/entity.rb +47 -0
- data/lib/lookbook/error.rb +1 -2
- data/lib/lookbook/features.rb +1 -1
- data/lib/lookbook/markdown.rb +3 -4
- data/lib/lookbook/page.rb +40 -34
- data/lib/lookbook/page_collection.rb +8 -0
- data/lib/lookbook/page_section.rb +31 -0
- data/lib/lookbook/params.rb +14 -3
- data/lib/lookbook/preview.rb +16 -7
- data/lib/lookbook/preview_collection.rb +8 -0
- data/lib/lookbook/preview_controller.rb +6 -2
- data/lib/lookbook/preview_example.rb +5 -6
- data/lib/lookbook/preview_group.rb +4 -9
- data/lib/lookbook/{code_inspector.rb → source_inspector.rb} +2 -2
- data/lib/lookbook/store.rb +36 -0
- data/lib/lookbook/theme.rb +29 -0
- data/lib/lookbook/utils.rb +10 -2
- data/lib/lookbook/version.rb +1 -1
- data/lib/lookbook.rb +6 -1
- data/lib/tasks/lookbook_tasks.rake +12 -0
- data/public/lookbook-assets/css/app.css +2340 -1
- data/public/lookbook-assets/css/app.css.map +11 -1
- data/public/lookbook-assets/css/lookbook.css +3069 -0
- data/public/lookbook-assets/css/lookbook.css.map +1 -0
- data/public/lookbook-assets/css/themes/blue.css +44 -0
- data/public/lookbook-assets/css/themes/blue.css.map +1 -0
- data/public/lookbook-assets/css/themes/indigo.css +44 -0
- data/public/lookbook-assets/css/themes/indigo.css.map +1 -0
- data/public/lookbook-assets/css/themes/zinc.css +44 -0
- data/public/lookbook-assets/css/themes/zinc.css.map +1 -0
- data/public/lookbook-assets/js/app.js +10861 -1
- data/public/lookbook-assets/js/app.js.map +2571 -1
- data/public/lookbook-assets/js/embed.js +895 -1
- data/public/lookbook-assets/js/embed.js.map +1 -1
- data/public/lookbook-assets/js/lookbook.js +13541 -0
- data/public/lookbook-assets/js/lookbook.js.map +1 -0
- metadata +133 -116
- data/app/assets/lookbook/css/app.css +0 -161
- data/app/assets/lookbook/css/code_theme.css +0 -214
- data/app/assets/lookbook/js/components/app.js +0 -55
- data/app/assets/lookbook/js/components/code.js +0 -5
- data/app/assets/lookbook/js/components/copy.js +0 -20
- data/app/assets/lookbook/js/components/embed.js +0 -89
- data/app/assets/lookbook/js/components/filter.js +0 -35
- data/app/assets/lookbook/js/components/inspector.js +0 -66
- data/app/assets/lookbook/js/components/nav-group.js +0 -47
- data/app/assets/lookbook/js/components/nav-item.js +0 -29
- data/app/assets/lookbook/js/components/nav.js +0 -28
- data/app/assets/lookbook/js/components/page-tabs.js +0 -9
- data/app/assets/lookbook/js/components/page.js +0 -25
- data/app/assets/lookbook/js/components/param.js +0 -34
- data/app/assets/lookbook/js/components/sidebar.js +0 -18
- data/app/assets/lookbook/js/components/sizes.js +0 -16
- data/app/assets/lookbook/js/components/splitter.js +0 -25
- data/app/assets/lookbook/js/components/tabs.js +0 -52
- data/app/assets/lookbook/js/lib/split.js +0 -15
- data/app/assets/lookbook/js/stores/sidebar.js +0 -26
- data/app/views/layouts/lookbook/basic.html.erb +0 -7
- data/app/views/lookbook/components/_branding.html.erb +0 -8
- data/app/views/lookbook/components/_code.html.erb +0 -17
- data/app/views/lookbook/components/_copy_button.html.erb +0 -11
- data/app/views/lookbook/components/_drawer.html.erb +0 -112
- data/app/views/lookbook/components/_embed.html.erb +0 -39
- data/app/views/lookbook/components/_errors.html.erb +0 -13
- data/app/views/lookbook/components/_filter.html.erb +0 -18
- data/app/views/lookbook/components/_header.html.erb +0 -6
- data/app/views/lookbook/components/_icon.html.erb +0 -5
- data/app/views/lookbook/components/_nav.html.erb +0 -16
- data/app/views/lookbook/components/_nav_collection.html.erb +0 -5
- data/app/views/lookbook/components/_nav_group.html.erb +0 -14
- data/app/views/lookbook/components/_nav_item.html.erb +0 -24
- data/app/views/lookbook/components/_nav_page.html.erb +0 -22
- data/app/views/lookbook/components/_nav_preview.html.erb +0 -13
- data/app/views/lookbook/components/_not_found.html.erb +0 -11
- data/app/views/lookbook/components/_param.html.erb +0 -21
- data/app/views/lookbook/components/_preview.html.erb +0 -77
- data/app/views/lookbook/components/_sidebar.html.erb +0 -69
- data/app/views/lookbook/pages/not_found.html.erb +0 -15
- data/app/views/lookbook/previews/error.html.erb +0 -1
- data/app/views/lookbook/previews/inputs/_select.html.erb +0 -7
- data/app/views/lookbook/previews/inputs/_text.html.erb +0 -8
- data/app/views/lookbook/previews/inputs/_textarea.html.erb +0 -8
- data/app/views/lookbook/previews/inputs/_toggle.html.erb +0 -13
- data/app/views/lookbook/previews/not_found.html.erb +0 -23
data/README.md
CHANGED
@@ -1,896 +1,162 @@
|
|
1
|
-
|
2
|
-
<h1>👀 Lookbook 👀</h1>
|
1
|
+
# Lookbook v1.0 [beta]
|
3
2
|
|
4
|
-
|
3
|
+
This is the **beta development** branch for Lookbook v1.0.
|
5
4
|
|
6
|
-
|
7
|
-
<a href="https://rubygems.org/gems/lookbook"><img src="https://badge.fury.io/rb/lookbook.svg" alt="Gem version">
|
8
|
-
<a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide">
|
9
|
-
<a href="https://github.com/prettier/prettier"><img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg" alt="Code style: Prettier">
|
10
|
-
</div>
|
11
|
-
</div>
|
5
|
+
> See the [main branch](https://github.com/allmarkedup/lookbook/tree/main) for code and documentation for the current stable release.
|
12
6
|
|
13
|
-
|
14
|
-
|
15
|
-
<div align="center">
|
16
|
-
<a href="#installing">Installing</a> • <a href="#previews">Previews</a> • <a href="#pages">Pages</a> • <a href="#deployment">Deployment</a> • <a href="#config">Config</a>
|
17
|
-
</div>
|
18
|
-
|
19
|
-
---
|
20
|
-
|
21
|
-
**Lookbook gives [ViewComponent](http://viewcomponent.org/)-based projects a _ready-to-go_ development UI for navigating, inspecting and interacting with component previews.**
|
22
|
-
|
23
|
-
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.
|
24
|
-
|
25
|
-
Lookbook uses [RDoc/Yard-style comment tags](#annotating-preview-files) 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.
|
26
|
-
|
27
|
-
![Lookbook UI](.github/assets/lookbook_screenshot.png)
|
28
|
-
|
29
|
-
### Features
|
30
|
-
|
31
|
-
- Tree-style navigation menu with live search/filter
|
32
|
-
- Resizable preview window for responsive testing
|
33
|
-
- Highlighted preview source code and HTML output
|
34
|
-
- Auto-updating UI when component or preview files are updated _(Rails v6.0+ only)_
|
35
|
-
- Use comment tag annotations for granular customisation of the preview experience
|
36
|
-
- Fully compatible with standard the ViewComponent preview system
|
37
|
-
- In-browser live-editable preview parameters (similar to basic Storybook Controls/Knobs)
|
38
|
-
- [**Experimental**] Markdown-powerered documentation pages with embeddable previews
|
7
|
+
## 🚀 Release focus
|
39
8
|
|
40
|
-
|
9
|
+
The main goals of the v1.0 release are:
|
41
10
|
|
42
|
-
|
11
|
+
- [x] Rebuild app UI using ViewComponent components
|
12
|
+
- [x] Improve usability of the small screen/mobile layout
|
13
|
+
- [x] Add support for some limited UI color theme customisation
|
14
|
+
- [x] Remove the `experimental` flag from the [Pages](https://github.com/allmarkedup/lookbook#pages)
|
15
|
+
- [x] Improve the development/debugging setup, and allow previewing Lookbook's own components in Lookbook :-)
|
16
|
+
- [ ] Improve the test setup and test coverage, switch to RSpec **[in progress]**
|
43
17
|
|
44
|
-
**
|
18
|
+
**No breaking changes** are planned for user-facing features, although the app UI will include some minor visual updates and usability improvements.
|
45
19
|
|
46
|
-
|
20
|
+
## Demo app
|
47
21
|
|
48
|
-
|
22
|
+
There is a demo of the current v1.0-beta here: https://lookbook-demo-app-v1-0-beta.herokuapp.com/lookbook/
|
49
23
|
|
50
|
-
|
24
|
+
[![Lookbook UI](.github/assets/lookbook_screenshot_v1.0_beta.png)](https://lookbook-demo-app-v1-0-beta.herokuapp.com/lookbook/)
|
51
25
|
|
52
|
-
|
26
|
+
## 👋 Testing and feedback - help wanted!
|
53
27
|
|
54
|
-
|
55
|
-
gem "view_component", require: "view_component/engine"
|
56
|
-
gem "lookbook"
|
57
|
-
```
|
58
|
-
|
59
|
-
### 2. Mount the Lookbook engine
|
60
|
-
|
61
|
-
You then need to mount the Lookbook engine (at a path of your choosing) in your `routes.rb` file:
|
62
|
-
|
63
|
-
```ruby
|
64
|
-
Rails.application.routes.draw do
|
65
|
-
if Rails.env.development?
|
66
|
-
mount Lookbook::Engine, at: "/lookbook"
|
67
|
-
end
|
68
|
-
end
|
69
|
-
```
|
28
|
+
The bulk of the v1.0 'new feature' development work is now mostly complete, although testing and bug fixing is ongoing.
|
70
29
|
|
71
|
-
|
30
|
+
**If you are an existing Lookbook user** I'd greatly appreciate if you can kick the tyres on the v1.0 beta and open an issue with any bug reports, suggestions or feedback you might have.
|
72
31
|
|
73
|
-
|
32
|
+
### Main areas/points for testing:
|
74
33
|
|
34
|
+
- Existing Lookbook setups should continue to work **with no changes required**
|
35
|
+
- There have been a number of small UI changes - do any of them negatively affect your experience of using Lookbook?
|
36
|
+
- The Pages feature should work without opting in to any experimental features.
|
37
|
+
- It's now possible to pick from one of a small set of pre-defined UI themes (finer-grained customisation coming soon!). [See below](#ui-theming) for details. Any thoughts on this?
|
75
38
|
|
76
|
-
|
39
|
+
> However absolutely any thoughts, comments or bug reports (even if unrelated to the specific areas above) would be much appreciated!
|
77
40
|
|
78
|
-
|
41
|
+
## New features
|
79
42
|
|
80
|
-
|
43
|
+
There are a number of new features that are planned for inclusion in the v1.0 release. They are:
|
81
44
|
|
82
|
-
###
|
45
|
+
### UI theming
|
83
46
|
|
84
|
-
Lookbook
|
47
|
+
Lookbook now ships with a small set of pre-defined UI themes, which can be set using the `ui_theme` config option:
|
85
48
|
|
86
49
|
```ruby
|
87
|
-
#
|
88
|
-
|
89
|
-
class ButtonComponentPreview < ViewComponent::Preview
|
90
|
-
|
91
|
-
# Primary button
|
92
|
-
# ---------------
|
93
|
-
# This is the button style you should use for most things.
|
94
|
-
#
|
95
|
-
# @label Primary
|
96
|
-
def default
|
97
|
-
render ButtonComponent.new do
|
98
|
-
"Click me"
|
99
|
-
end
|
100
|
-
end
|
101
|
-
|
102
|
-
# Button with icon
|
103
|
-
# ----------------
|
104
|
-
# This example uses dynamic preview parameters
|
105
|
-
# which can be edited live in the Lookbook UI
|
106
|
-
#
|
107
|
-
# @param text
|
108
|
-
# @param icon select [heart, cog, alert]
|
109
|
-
def icon(text: "Spread the love", icon: "heart")
|
110
|
-
render ButtonComponent.new(icon: icon) do
|
111
|
-
text
|
112
|
-
end
|
113
|
-
end
|
114
|
-
|
115
|
-
# Inverted button
|
116
|
-
# ---------------
|
117
|
-
# For light-on-dark screens
|
118
|
-
#
|
119
|
-
# @display bg_color "#000"
|
120
|
-
def secondary
|
121
|
-
render ButtonComponent.new(style: :inverted) do
|
122
|
-
"Click me"
|
123
|
-
end
|
124
|
-
end
|
125
|
-
|
126
|
-
# Unicorn button
|
127
|
-
# ---------------
|
128
|
-
# This button style is still a **work in progress**.
|
129
|
-
#
|
130
|
-
# @hidden
|
131
|
-
def secondary
|
132
|
-
render ButtonComponent.new do
|
133
|
-
"Click me"
|
134
|
-
end
|
135
|
-
end
|
136
|
-
|
137
|
-
# @!group More examples
|
138
|
-
|
139
|
-
def short_text
|
140
|
-
render ButtonComponent.new do
|
141
|
-
"Go"
|
142
|
-
end
|
143
|
-
end
|
144
|
-
|
145
|
-
def long_text
|
146
|
-
render ButtonComponent.new do
|
147
|
-
"Click here to do this thing because it's the best way to do it"
|
148
|
-
end
|
149
|
-
end
|
150
|
-
|
151
|
-
def emoji_text
|
152
|
-
render ButtonComponent.new do
|
153
|
-
"👀📗"
|
154
|
-
end
|
155
|
-
end
|
156
|
-
|
157
|
-
# @!endgroup
|
158
|
-
|
159
|
-
end
|
50
|
+
# config/application.rb (or similar)
|
51
|
+
config.lookbook.ui_theme = "blue"
|
160
52
|
```
|
161
53
|
|
162
|
-
|
54
|
+
Currently available themes are:
|
163
55
|
|
164
|
-
|
56
|
+
- `indigo` (default)
|
57
|
+
- `blue`
|
58
|
+
- `zinc`
|
165
59
|
|
166
|
-
|
167
|
-
* [`@display`](#display-tag)
|
168
|
-
* [`@!group ... @!endgroup`](#group-tag)
|
169
|
-
* [`@hidden`](#hidden-tag)
|
170
|
-
* [`@param`](#param-tag)
|
60
|
+
> More themes and finer-grained customisation of theme colours is coming soon!
|
171
61
|
|
172
|
-
|
62
|
+
### Inspector panels customisation
|
173
63
|
|
174
|
-
|
64
|
+
It is now possible to add, remove or customise tabbed panels in the preview inspector by editing the `lookbook.inspector_panels` configuration option.
|
175
65
|
|
176
|
-
|
177
|
-
@label <text>
|
178
|
-
```
|
179
|
-
|
180
|
-
> Available for preview classes & example methods.
|
181
|
-
|
182
|
-
```ruby
|
183
|
-
# @label Preview Label
|
184
|
-
class FooComponentPreview < ViewComponent::Preview
|
66
|
+
By default Lookbook comes with **five** panels split between two resizable panes:
|
185
67
|
|
186
|
-
|
187
|
-
|
188
|
-
end
|
189
|
-
end
|
190
|
-
```
|
191
|
-
|
192
|
-
<h3 id="display-tag">🏷 @display</h3>
|
68
|
+
1. The `main` pane - by default includes the `preview` and `output` (HTML) panels
|
69
|
+
2. The `drawer` pane - by default includes the `source`, `notes` and `params` panels
|
193
70
|
|
194
|
-
|
195
|
-
|
196
|
-
```ruby
|
197
|
-
# @display bg_color "#eee"
|
198
|
-
class FooComponentPreview < ViewComponent::Preview
|
71
|
+
These can be hidden, moved, reordered and/or added to as your project requires.
|
199
72
|
|
200
|
-
|
201
|
-
# @display wrapper true
|
202
|
-
def default
|
203
|
-
end
|
204
|
-
end
|
205
|
-
```
|
73
|
+
#### Panel config overview
|
206
74
|
|
207
|
-
|
75
|
+
Panels are defined as a hash with the following properties (all of which are actually optional):
|
208
76
|
|
209
77
|
```ruby
|
210
|
-
|
211
|
-
|
212
|
-
|
213
|
-
|
214
|
-
|
215
|
-
|
216
|
-
|
217
|
-
|
218
|
-
|
219
|
-
|
220
|
-
```html
|
221
|
-
<!DOCTYPE html>
|
222
|
-
<html style="background-color: <%= params[:lookbook][:display][:bg_color] %>">
|
223
|
-
<head>
|
224
|
-
<title>Preview Layout</title>
|
225
|
-
</head>
|
226
|
-
<body>
|
227
|
-
<div style="max-width: <%= params[:lookbook][:display][:max_width] || '100%' %>">
|
228
|
-
<% if params[:lookbook][:display][:wrapper] == true %>
|
229
|
-
<div class="wrapper"><%= yield %></div>
|
230
|
-
<% else %>
|
231
|
-
<%= yield %>
|
232
|
-
<% end %>
|
233
|
-
</div>
|
234
|
-
</body>
|
235
|
-
</html>
|
236
|
-
```
|
237
|
-
|
238
|
-
> 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.
|
239
|
-
|
240
|
-
Any `@display` params set at the preview (class) level with be merged with those set on individual example methods.
|
241
|
-
|
242
|
-
#### Global display params
|
243
|
-
|
244
|
-
Global (fallback) display params can be defined via a configuration option:
|
245
|
-
|
246
|
-
```ruby
|
247
|
-
# config/application.rb
|
248
|
-
config.lookbook.preview_display_params = {
|
249
|
-
bg_color: "#fff",
|
250
|
-
max_width: "100%"
|
78
|
+
{
|
79
|
+
label: "New Panel",
|
80
|
+
pane: :drawer,
|
81
|
+
position: 1,
|
82
|
+
partial: "path/to/view_partial",
|
83
|
+
content: "Some **markdown** content",
|
84
|
+
hotkey: "ctrl.n",
|
85
|
+
disabled: false,
|
86
|
+
show: true,
|
87
|
+
copy: "Content to be copied",
|
251
88
|
}
|
252
89
|
```
|
253
90
|
|
254
|
-
|
255
|
-
|
256
|
-
|
257
|
-
|
258
|
-
|
91
|
+
* `label`: the text to be displayed in the tab
|
92
|
+
* `pane`: the panel location, either `:drawer` or `:main` (`:drawer` is the default)
|
93
|
+
* `position`: used for ordering the tabs
|
94
|
+
* `partial`: the path to the view template partial used to render the panel
|
95
|
+
* `content`: the default partial renders and displays the contents of this (markdown supported)
|
96
|
+
* `hotkey`: [keyboard shortcut](https://alpinejs.dev/directives/on#keyboard-events) to make panel become the active tab
|
97
|
+
* `disabled`: `true` or `false` - disabled tabs are still accessible but are greyed out in the UI
|
98
|
+
* `show`: `true` or `false` - whether or not to display the tab/panel
|
99
|
+
* `copy`: if present, the panel will display a copy button that copies the value of this property to the clipboard when clicked
|
100
|
+
* `locals`: a `Hash` of local variables that will be made available to the partial when rendering the panel
|
259
101
|
|
260
|
-
|
102
|
+
All panel config values can be provided either as a **simple static value** or as a **lambda function** which will receive a hash of data relating to the current preview/example. For example:
|
261
103
|
|
262
104
|
```ruby
|
263
|
-
|
264
|
-
|
265
|
-
|
266
|
-
render Elements::HeaderComponent.new do
|
267
|
-
"Standard header"
|
268
|
-
end
|
269
|
-
end
|
270
|
-
|
271
|
-
# @!group Sizes
|
272
|
-
|
273
|
-
def small
|
274
|
-
render Elements::HeaderComponent.new(size: 12) do
|
275
|
-
"Small header"
|
276
|
-
end
|
277
|
-
end
|
278
|
-
|
279
|
-
def medium
|
280
|
-
render Elements::HeaderComponent.new(size: 16) do
|
281
|
-
"Small header"
|
282
|
-
end
|
283
|
-
end
|
284
|
-
|
285
|
-
def big
|
286
|
-
render Elements::HeaderComponent.new(size: 24) do
|
287
|
-
"Small header"
|
288
|
-
end
|
289
|
-
end
|
290
|
-
|
291
|
-
# @!endgroup
|
292
|
-
|
293
|
-
end
|
294
|
-
```
|
295
|
-
|
296
|
-
The example above would display the `Sizes` examples grouped together on a single page, rather than as indiviual items in the navigation:
|
297
|
-
|
298
|
-
<img src=".github/assets/nav_group.png">
|
299
|
-
|
300
|
-
You can have as many groups as you like within a single preview class, but each example can only belong to one group.
|
301
|
-
|
302
|
-
<h3 id="hidden-tag">🏷 `@hidden`</h3>
|
303
|
-
|
304
|
-
Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
|
305
|
-
|
306
|
-
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.
|
307
|
-
|
308
|
-
> Available for both preview classes & example methods.
|
309
|
-
|
310
|
-
```ruby
|
311
|
-
# @hidden
|
312
|
-
class FooComponentPreview < ViewComponent::Preview
|
313
|
-
|
314
|
-
# @hidden
|
315
|
-
def default
|
316
|
-
end
|
317
|
-
end
|
318
|
-
```
|
319
|
-
|
320
|
-
<h3 id="param-tag">@param</h3>
|
321
|
-
|
322
|
-
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.
|
323
|
-
|
324
|
-
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.
|
325
|
-
|
326
|
-
The `@param` tag takes the following format:
|
327
|
-
|
328
|
-
```ruby
|
329
|
-
@param <name> <input_type> <opts?>
|
330
|
-
```
|
331
|
-
|
332
|
-
- `<name>` - name of the dynamic preview param
|
333
|
-
- `<input_type>` - input field type to generate in the UI
|
334
|
-
- `<opts?>` - YAML-encoded field options, used for some field types
|
335
|
-
|
336
|
-
#### Input types
|
337
|
-
|
338
|
-
The following **input field types** are available for use:
|
339
|
-
|
340
|
-
📝 **Text-style inputs** - Single line fields, useful for short strings of text or numbers.
|
341
|
-
|
342
|
-
```ruby
|
343
|
-
@param <name> text
|
344
|
-
@param <name> email
|
345
|
-
@param <name> number
|
346
|
-
@param <name> url
|
347
|
-
@param <name> tel
|
348
|
-
```
|
349
|
-
|
350
|
-
> The above types only differ in the validation constraints they impose on the input field.
|
351
|
-
|
352
|
-
📝 **Textarea** - Multi-line textarea field for longer-form content.
|
353
|
-
|
354
|
-
```ruby
|
355
|
-
@param <name> textarea
|
356
|
-
```
|
357
|
-
|
358
|
-
📝 **Select box** - Dropdown select field for selecting from a list of known options.
|
359
|
-
|
360
|
-
```ruby
|
361
|
-
@param <name> select <options>
|
362
|
-
```
|
363
|
-
|
364
|
-
`<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:
|
365
|
-
|
366
|
-
```ruby
|
367
|
-
# Basic options:
|
368
|
-
# @param theme select [primary, secondary, danger]
|
369
|
-
|
370
|
-
# With custom labels (each item itself an array of [label, value]):
|
371
|
-
# @param theme select [[Primary theme, primary], [Secondary theme, secondary], [Danger theme, danger]]
|
372
|
-
|
373
|
-
# With empty option (`~` in YAML)
|
374
|
-
# @param theme select [~, primary, secondary, danger]
|
375
|
-
```
|
376
|
-
|
377
|
-
> **Note**: In most cases YAML does not require quoting of strings, however if you are running into issues check out the [Ruby YAML docs](https://yaml.org/YAML_for_ruby.html) for a complete syntax reference.
|
378
|
-
|
379
|
-
📝 **Toggle** - On/off switch for toggling boolean values.
|
380
|
-
|
381
|
-
```ruby
|
382
|
-
@param <name> toggle
|
383
|
-
```
|
384
|
-
|
385
|
-
#### Default values
|
386
|
-
|
387
|
-
Default values are specified as part of the preview example method parameters in the usual Ruby way:
|
388
|
-
|
389
|
-
```ruby
|
390
|
-
def button(content: "Click me", theme: "primary", arrow: false)
|
391
|
-
# ...
|
392
|
-
end
|
393
|
-
```
|
394
|
-
|
395
|
-
These will be used as the default values for the param fields.
|
396
|
-
|
397
|
-
> Note that the default values are **not** evaluated at runtime, so you cannot use method calls to generate the defaults. Only static default values are supported.
|
398
|
-
|
399
|
-
#### Type casting values
|
400
|
-
|
401
|
-
Most dynamic param values are passed to the example method as strings, with the following exceptions:
|
402
|
-
|
403
|
-
- `toggle` input - values are cast to booleans
|
404
|
-
- `number` input - values are cast to integers
|
405
|
-
|
406
|
-
In some cases, you may want to type cast the parameter value to something else (for example a `Symbol`) before using it when initializing the component.
|
407
|
-
|
408
|
-
To help with this, a `type` option can be specified in the `@param` definition to automatically cast the dynamic value to a different type:
|
409
|
-
|
410
|
-
```ruby
|
411
|
-
# @param <name> [<type>] <input_type> <opts?>
|
412
|
-
```
|
413
|
-
|
414
|
-
In the example below, the value of the `theme` param (by default a string) will be automatically cast to a Symbol, ready for use in instantiating the component.
|
415
|
-
|
416
|
-
```ruby
|
417
|
-
# @param theme [Symbol] select [primary, secondary, danger]
|
418
|
-
def default(theme: :primary)
|
419
|
-
render Elements::ButtonComponent.new(theme: theme) do
|
420
|
-
"Click me"
|
421
|
-
end
|
422
|
-
end
|
423
|
-
```
|
424
|
-
|
425
|
-
The supported types to cast to are:
|
426
|
-
|
427
|
-
- `String` - *default for all except `toggle` inputs*
|
428
|
-
- `Boolean` - *default for `toggle` inputs*
|
429
|
-
- `Symbol`
|
430
|
-
- `Date`
|
431
|
-
- `DateTime`
|
432
|
-
- `Integer`
|
433
|
-
- `Float`
|
434
|
-
|
435
|
-
The following structured types are also available but should be considered **experimental** - you may run into bugs!
|
436
|
-
|
437
|
-
- `Hash` - *value string converted to Hash using the Ruby YAML parser*
|
438
|
-
- `Array` - *value string converted to Array using the Ruby YAML parser*
|
439
|
-
|
440
|
-
#### Full example:
|
441
|
-
|
442
|
-
```ruby
|
443
|
-
class ButtonComponentPreview < ViewComponent::Preview
|
444
|
-
|
445
|
-
# The params defined below will be editable in the UI:
|
446
|
-
#
|
447
|
-
# @param content text
|
448
|
-
# @param theme select [primary, secondary, danger]
|
449
|
-
# @param arrow toggle
|
450
|
-
def default(content: "Click me", theme: "primary", arrow: true)
|
451
|
-
render Elements::ButtonComponent.new(theme: theme, arrow: arrow) do
|
452
|
-
content
|
453
|
-
end
|
454
|
-
end
|
455
|
-
|
456
|
-
end
|
457
|
-
```
|
458
|
-
|
459
|
-
<img src=".github/assets/dynamic_params.png">
|
460
|
-
|
461
|
-
### Adding notes
|
462
|
-
|
463
|
-
All comment text other than tags will be treated as markdown and rendered in the **Notes** panel for that example in the Lookbook UI.
|
464
|
-
|
465
|
-
```ruby
|
466
|
-
# @hidden
|
467
|
-
class ProfileCardComponentPreview < ViewComponent::Preview
|
468
|
-
|
469
|
-
# Profile Card
|
470
|
-
# ------------
|
471
|
-
# Use the default profile card component whenever you need to represent a user.
|
472
|
-
def default
|
473
|
-
end
|
474
|
-
end
|
475
|
-
```
|
476
|
-
|
477
|
-
---
|
478
|
-
|
479
|
-
<h2 id="pages">🚧 Documentation Pages [experimental]</h2>
|
480
|
-
|
481
|
-
If you need to add more long-form documentation to live alongside your component previews you can do so using Lookbook's markdown-powered `pages` system.
|
482
|
-
|
483
|
-
> ⚠️ This feature is currently flagged as an **experimental** feature which requires [feature opt-in](#experimental-features) to use. Its API and implementation may change before it is released.
|
484
|
-
>
|
485
|
-
> To enable support for pages in your project, add `config.lookbook.experimental_features = [:pages]` into your application configuration file.
|
486
|
-
|
487
|
-
### Pages demo
|
488
|
-
|
489
|
-
For an example of some pages in Lookbook, check out the [example pages](https://lookbook-demo-app.herokuapp.com/lookbook) in the Lookbook demo app and the associated [page files](https://github.com/allmarkedup/lookbook-demo/tree/main/test/components/docs) in the demo repo.
|
490
|
-
|
491
|
-
### Usage
|
492
|
-
|
493
|
-
By default, pages should be placed in the `test/components/docs` directory (although this can be customised) and can be nested in directories as deeply as required.
|
494
|
-
|
495
|
-
Pages must have either a `.html.erb` or a `.md.erb` file extension. All pages are rendered as ERB templates but `.md.erb` files will also additionally be run through a markdown parser.
|
496
|
-
|
497
|
-
Pages can optionally make use of a **YAML frontmatter block** to customise the behaviour and content of the page itself.
|
498
|
-
|
499
|
-
An example page might look like this:
|
500
|
-
|
501
|
-
```markdown
|
502
|
-
---
|
503
|
-
title: An example page
|
504
|
-
label: Nice example
|
505
|
-
---
|
506
|
-
|
507
|
-
This is an example page. If it has a `.md.erb` file extension its
|
508
|
-
contents will be run through a Markdown parser/renderer before display.
|
509
|
-
|
510
|
-
Fenced code blocks are fully supported and will be highlighted appropriately.
|
511
|
-
|
512
|
-
ERB can be used in here.
|
513
|
-
The template will be rendered **before** being parsed as Markdown.
|
514
|
-
|
515
|
-
You can can access data about the page using the `@page` variable.
|
516
|
-
The title of this page is "<%= @page.title %>".
|
517
|
-
```
|
518
|
-
|
519
|
-
### YAML Frontmatter
|
520
|
-
|
521
|
-
Pages can use an optional YAML frontmatter block to configure the behaviour of the page and to provide custom data, if required.
|
522
|
-
|
523
|
-
The following page options can be customised via frontmatter:
|
524
|
-
|
525
|
-
* `id` - a custom page ID that can be used for linking to it from other pages
|
526
|
-
* `label` - The name of the page that will be displayed in the navigation (auto-generated from the file name if not set)
|
527
|
-
* `title` - The main page title displayed on the page (defaults to the label value if not set).
|
528
|
-
* `hidden` - If `false` the page will not appear in the navigation but will still be accessible at it's URL (useful for pages that are still in development) [default: `true`]
|
529
|
-
* `landing` - Set to `true` to use the page as the Lookbook landing page [default: `false`]
|
530
|
-
* `header` - Set to `false` to hide the page header containing the page title [default: `true`]
|
531
|
-
* `footer` - Set to `false` to hide the page footer containing the previous/next page links [default: `true`]
|
532
|
-
* `data` - Optional hash of custom data to make available for use in the page - see info on [page variables](#page-variables) below. [default: `{}`]
|
533
|
-
|
534
|
-
#### Frontmatter defaults
|
535
|
-
|
536
|
-
You can set global default values for page options in the application configuration:
|
537
|
-
|
538
|
-
```ruby
|
539
|
-
# config/application.rb
|
540
|
-
config.lookbook.page_options = {
|
541
|
-
footer: false,
|
542
|
-
data: {
|
543
|
-
brand_colors: {
|
544
|
-
red: "#ff0000"
|
545
|
-
}
|
546
|
-
}
|
105
|
+
{
|
106
|
+
label: "Params",
|
107
|
+
disabled: ->(data) { data.preview.params.none? } # grey out the Params tab if no params are set for the current preview
|
547
108
|
}
|
548
109
|
```
|
549
110
|
|
550
|
-
|
551
|
-
|
552
|
-
### Page variables
|
553
|
-
|
554
|
-
All pages have the following variables available for use in the page template:
|
555
|
-
|
556
|
-
* `@page` - The current page object
|
557
|
-
* `@next_page` - The next page object (if available)
|
558
|
-
* `@previous_page` - The previous page object (if available)
|
559
|
-
* `@pages` - Collection of all pages
|
560
|
-
|
561
|
-
Page objects have access to frontmatter variables:
|
562
|
-
|
563
|
-
```ruby
|
564
|
-
The page title is <%= @page.title %>
|
565
|
-
|
566
|
-
Our brand color hex value is <%= @page.data[:brand_colors][:red] %>
|
567
|
-
```
|
568
|
-
|
569
|
-
### Ordering pages and directories
|
570
|
-
|
571
|
-
If you want to enforce a specific order for pages and directories in the Lookbook navigation you can prefix the file/directory basename with an 'order number' integer value followed by an underscore or hyphen.
|
572
|
-
|
573
|
-
For example: `01_example_page.md.erb` will be displayed first in the navigation (`01`) within the directory it is in.
|
574
|
-
|
575
|
-
The integer value will be parsed out from the filename so that it doesn't appear in navigation labels or URLs, and the value itself will be used as a 'position' number when sorting the navigation items.
|
576
|
-
|
577
|
-
For example, an ordered directory of pages might look like:
|
578
|
-
|
579
|
-
```
|
580
|
-
test/components/docs/
|
581
|
-
├── 01_overview.md.erb
|
582
|
-
├── 02_implementation_notes/
|
583
|
-
│ ├── 01_slots.md.erb
|
584
|
-
│ └── 02_html_attributes.md.erb
|
585
|
-
└── 03_helpful_examples/
|
586
|
-
├── 01_basic_components.md.erb
|
587
|
-
└── 02_complex_components.md.erb
|
588
|
-
```
|
589
|
-
|
590
|
-
Without the number prefixes on the file names the pages may not have appeared in the navigation in the desired order.
|
591
|
-
|
592
|
-
### Linking to other pages
|
593
|
-
|
594
|
-
You can get the path to a page using the `page_path` helper. This accepts a page `id` (as a `Symbol`) or a page object:
|
595
|
-
|
596
|
-
```markdown
|
597
|
-
Visit the [about page](<%= page_path :about %>)
|
598
|
-
|
599
|
-
Go to the [next page](<%= page_path @next_page %>)
|
600
|
-
```
|
601
|
-
|
602
|
-
Page ids can be set in the YAML frontmatter block for that page:
|
603
|
-
|
604
|
-
```
|
605
|
-
---
|
606
|
-
id: about
|
607
|
-
---
|
608
|
-
|
609
|
-
This is the about page.
|
610
|
-
```
|
611
|
-
|
612
|
-
### Embedding previews
|
613
|
-
|
614
|
-
You can embed preview examples from your project directly into the documentation pages using the `embed` helper, which renders an iframe with the rendered preview in it at any point in your document.
|
615
|
-
|
616
|
-
The output looks like this:
|
617
|
-
|
618
|
-
<img src=".github/assets/preview_embed.png">
|
619
|
-
|
620
|
-
To specify which preview example to render, the helper accepts a preview class and a method name (as a symbol), like this:
|
621
|
-
|
622
|
-
```erb
|
623
|
-
<%= embed Elements:ButtonComponentPreview, :default %>
|
624
|
-
```
|
625
|
-
|
626
|
-
#### Preview params
|
627
|
-
|
628
|
-
If you have configured your examples to accept preview params (see the [`@param`](#param-tag) docs), then you can supply values for those params when rendering the embedded preview:
|
629
|
-
|
630
|
-
```erb
|
631
|
-
<%= embed Elements:ButtonComponentPreview, :default, params: {
|
632
|
-
icon: "plus",
|
633
|
-
text: "Add new"
|
634
|
-
} %>
|
635
|
-
```
|
636
|
-
|
637
|
-
### Displaying code
|
638
|
-
|
639
|
-
You can use language-scoped [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) in the markdown file to render nicely highlighted code examples.
|
640
|
-
|
641
|
-
However, if you are not using Markdown, or need a little more control, you can use the `code` helper instead:
|
642
|
-
|
643
|
-
```erb
|
644
|
-
<%= code do %>
|
645
|
-
# code goes here
|
646
|
-
<% end %>
|
647
|
-
```
|
648
|
-
|
649
|
-
The default language is `ruby`. To highlight a different language you need to specify it's name as an argument:
|
650
|
-
|
651
|
-
```erb
|
652
|
-
<%= code :html do %>
|
653
|
-
<!-- code goes here -->
|
654
|
-
<% end %>
|
655
|
-
```
|
656
|
-
|
657
|
-
> Lookbook uses [Rouge](https://github.com/rouge-ruby/rouge) for syntax highlighting. You can find a [full list of supported languages here](https://github.com/rouge-ruby/rouge/blob/master/docs/Languages.md).
|
658
|
-
|
659
|
-
### Tabs
|
660
|
-
|
661
|
-
You can break up your page's content into tabs. If your avatar page is named `01_avatar.md.erb`, by declaring a page named `01_avatar[web].md.erb` it will create a **web** tab on the page. Tabs like normal Pages can contain embedded previews and code examples.
|
662
|
-
|
663
|
-
```
|
664
|
-
test/components/docs/
|
665
|
-
├── 01_avatar.md.erb
|
666
|
-
├── 01_avatar[design].md.erb
|
667
|
-
├── 01_avatar[mobile].md.erb
|
668
|
-
├── 01_avatar[web].md.erb
|
669
|
-
```
|
670
|
-
|
671
|
-
By declaring the `label` frontmatter you can change the label shown on the tab:
|
672
|
-
|
673
|
-
```
|
674
|
-
---
|
675
|
-
label: Website
|
676
|
-
---
|
677
|
-
```
|
678
|
-
|
679
|
-
If you want the tabs in a different order, you can use the `position` frontmatter:
|
680
|
-
|
681
|
-
```
|
682
|
-
---
|
683
|
-
label: Web
|
684
|
-
position: 1
|
685
|
-
---
|
686
|
-
```
|
687
|
-
|
688
|
-
---
|
689
|
-
|
690
|
-
### Pages configuration
|
691
|
-
|
692
|
-
These options can be set in your application configuration files to customise the pages behaviour.
|
693
|
-
|
694
|
-
#### `page_paths`
|
695
|
-
|
696
|
-
An array of directories to look for pages in.
|
697
|
-
Default: `["test/previews/docs"]`
|
698
|
-
|
699
|
-
```ruby
|
700
|
-
config.lookbook.page_paths = ["path/to/my/pages"]
|
701
|
-
```
|
702
|
-
|
703
|
-
#### `page_route`
|
704
|
-
|
705
|
-
The URL segment used to prefix page routes.
|
706
|
-
Default: `pages`
|
707
|
-
|
708
|
-
```ruby
|
709
|
-
config.lookbook.page_route = `docs`
|
710
|
-
```
|
711
|
-
|
712
|
-
<h2 id="deployment">Deploying in Production</h2>
|
111
|
+
> **Work in progress!** There is more documentation to come on the data hash passed to lambdas.
|
713
112
|
|
714
|
-
|
113
|
+
#### Removing panels
|
715
114
|
|
716
|
-
|
717
|
-
|
718
|
-
### Differences between development and production
|
719
|
-
|
720
|
-
By default, Lookbook will behave a little differently in production than it does in development:
|
721
|
-
|
722
|
-
1. Watching files for changes is disabled
|
723
|
-
2. Parsing preview files for annotations does **not** happen at runtime. Instead the preview files must be pre-parsed via a Rake task before starting the app (much like asset precompilation).
|
724
|
-
|
725
|
-
### Pre-parsing preview files
|
726
|
-
|
727
|
-
Run the following command to pre-parse the preview files annotations:
|
728
|
-
|
729
|
-
```
|
730
|
-
rake lookbook:previews:preparse
|
731
|
-
```
|
732
|
-
|
733
|
-
If you wish to run this as part of your existing assets precompilation step, you can add the following into your app's `Rakefile`:
|
115
|
+
To remove a pane entirely from the UI, just set it's value to false in your `application.rb` (or wherever you do your configuration):
|
734
116
|
|
735
117
|
```ruby
|
736
|
-
|
737
|
-
Rake::Task['assets:precompile'].enhance do
|
738
|
-
Rake::Task["lookbook:previews:preparse"].invoke
|
739
|
-
end
|
740
|
-
end
|
118
|
+
config.lookbook.inspector_panels.notes = false # remove the notes panel
|
741
119
|
```
|
742
120
|
|
743
|
-
|
121
|
+
#### Customising existing panels
|
744
122
|
|
745
|
-
|
746
|
-
|
747
|
-
You will also need to make sure that the following configuration changes have been made when deploying to production:
|
748
|
-
|
749
|
-
1. Make sure ViewComponent is [configured to show previews in production](https://viewcomponent.org/api.html#show_previews) (by default it is disabled when not in development):
|
123
|
+
Existing panel configuration can be amended as needed. For example, to change the label on one of the default panels:
|
750
124
|
|
751
125
|
```ruby
|
752
|
-
|
753
|
-
config.view_component.show_previews = true
|
754
|
-
```
|
126
|
+
config.lookbook.inspector_panels.notes.label = "Instructions"
|
755
127
|
|
756
|
-
|
757
|
-
|
758
|
-
|
759
|
-
# config/routes.rb
|
760
|
-
Rails.application.routes.draw do
|
761
|
-
# if Rails.env.development? <- remove
|
762
|
-
mount Lookbook::Engine, at: "/lookbook"
|
763
|
-
# end
|
128
|
+
# or use block-style config
|
129
|
+
config.lookbook.inspector_panels do |panels|
|
130
|
+
panels.notes.label = "Instructions"
|
764
131
|
end
|
765
132
|
```
|
766
133
|
|
767
|
-
### Overriding production default behaviours
|
768
|
-
|
769
|
-
If for some reason you wish to enable file watching or runtime preview annotation parsing in production, you can always override the default behaviour using thie following config options:
|
770
|
-
|
771
|
-
```ruby
|
772
|
-
# config/environments/production.rb
|
773
|
-
|
774
|
-
# enable file-change listening
|
775
|
-
config.lookbook.listen = true
|
776
|
-
|
777
|
-
# enable runtime preview parsing
|
778
|
-
config.lookbook.runtime_parsing = true
|
779
|
-
```
|
780
|
-
|
781
|
-
<h2 id="config">General Configuration</h2>
|
782
|
-
|
783
|
-
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 much else separately.
|
784
|
-
|
785
|
-
However the following Lookbook-specific configuration options are also available:
|
786
|
-
|
787
|
-
### UI auto-refresh
|
788
|
-
|
789
|
-
> ⚠️ UI auto-refresh is only supported in Rails v6.0+
|
790
|
-
|
791
|
-
Disable/enable the auto-updating of the Lookbook UI when files change. Enabled by default.
|
792
|
-
|
793
|
-
```ruby
|
794
|
-
config.lookbook.auto_refresh = false # default is true
|
795
|
-
```
|
796
|
-
|
797
|
-
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.
|
798
|
-
|
799
|
-
If you wish to add additional paths to listen for changes in, you can use the `listen_paths` option:
|
800
|
-
|
801
|
-
```ruby
|
802
|
-
config.lookbook.listen_paths << Rails.root.join('app/other/directory')
|
803
|
-
```
|
804
|
-
|
805
|
-
### Custom favicon
|
806
|
-
|
807
|
-
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:
|
808
|
-
|
809
|
-
```ruby
|
810
|
-
config.lookbook.ui_favicon = "/path/to/my/favicon.png"
|
811
|
-
```
|
812
|
-
|
813
|
-
> To disable the favicon entirely, set the value to `false`.
|
814
|
-
|
815
|
-
### Project name
|
816
|
-
|
817
|
-
Specify a project name to display in the top left of the UI (instead of the default "Lookbook"):
|
818
|
-
|
819
|
-
```ruby
|
820
|
-
config.lookbook.project_name = "My Project"
|
821
|
-
```
|
822
|
-
|
823
|
-
> If you don't want to display a project name at all, set the value to `false`.
|
824
134
|
|
825
135
|
|
826
|
-
<h3 id="experimental-features">Experimental features opt-in</h3>
|
827
136
|
|
828
|
-
|
137
|
+
## 🛠 Workbench
|
829
138
|
|
830
|
-
|
139
|
+
As of this release, Lookbook's UI is itself built using ViewComponent components. To help with development it is possible to preview these components (in a Lookbook instance!) by running the included 'Workbench" app, as follows:
|
831
140
|
|
832
|
-
|
141
|
+
1. Clone this repo
|
142
|
+
2. Install dependencies: `bundle install & npm install`
|
143
|
+
3. Start the Workbench: `foreman start`
|
144
|
+
4. Open http://localhost:4545 in your browser to view the Workbench
|
833
145
|
|
834
|
-
|
146
|
+
This will start the Workbench app in development mode and any changes to Lookbooks views or assets will immediately be visible in the UI.
|
835
147
|
|
836
|
-
```ruby
|
837
|
-
config.lookbook.experimental_features = ["feature_name"]
|
838
|
-
```
|
839
148
|
|
840
|
-
|
149
|
+
## 🚦 Running tests
|
841
150
|
|
842
|
-
|
151
|
+
The test suite is in the process of being completely overhauled.
|
843
152
|
|
153
|
+
Tests are now written using RSpec and the system now uses [Combustion](https://github.com/pat/combustion) under the hood.
|
844
154
|
|
845
|
-
|
155
|
+
- Tests can be run using the `rake lookbook:test` or `bundle exec rspec` commands.
|
156
|
+
- The dummy app that the tests are being run against can be viewed by running the `rake lookbook:test:serve` command and then browsing to http://localhost:9292/lookbook
|
846
157
|
|
847
|
-
If you want to live life on the bleeding-edge you can opt-in to all current **and future** experimental features (usual caveats apply):
|
848
158
|
|
849
|
-
|
850
|
-
config.lookbook.experimental_features = true
|
851
|
-
```
|
852
|
-
|
853
|
-
|
854
|
-
## Keyboard shortcuts
|
855
|
-
|
856
|
-
Lookbook provides a few keyboard shortcuts to help you quickly move around the UI.
|
857
|
-
|
858
|
-
- `f` - move focus to the nav filter box
|
859
|
-
- `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
|
860
|
-
- `s` - Switch to Source tab in the drawer
|
861
|
-
- `n` - Switch to Notes tab in the drawer
|
862
|
-
- `v` - Switch to the rendered preview
|
863
|
-
- `o` - Switch to the code preview
|
864
|
-
- `r` - Refresh the preview (useful if using something like Faker to generate randomised data for the preview)
|
865
|
-
- `w` - Open the standalone rendered preview in a new window
|
866
|
-
|
867
|
-
## Contributing
|
868
|
-
|
869
|
-
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 😜
|
870
|
-
|
871
|
-
### Developing on a local version of Lookbook
|
872
|
-
|
873
|
-
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:
|
874
|
-
|
875
|
-
#### Initial setup:
|
876
|
-
|
877
|
-
1. Clone this repository somewhere on your machine - `git clone git@github.com:allmarkedup/lookbook.git`
|
878
|
-
2. Also pull down the [lookbook-demo](https://github.com/allmarkedup/lookbook-demo) repository to your machine
|
879
|
-
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)
|
880
|
-
4. Install dependencies - from the root of the parent project run `bundle install`
|
881
|
-
|
882
|
-
#### Starting development
|
883
|
-
|
884
|
-
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)
|
885
|
-
2. From within the `lookbook-demo` root directory run `npm run start` - this will start a server and build the demo assets
|
886
|
-
|
887
|
-
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 :-)
|
888
|
-
|
889
|
-
> Note that changes to files in the Lookbook `lib/` directory will require a server restart in order to have them applied.
|
890
|
-
|
891
|
-
#### Tests
|
892
|
-
|
893
|
-
You can run the tests from within the `lookbook` root directory with the `rake test` command.
|
159
|
+
---
|
894
160
|
|
895
161
|
## License
|
896
162
|
|