Add page examples

lookbook-hq · Mar 23, 2022 · af05061 · af05061
1 parent 75f3209
commit af05061
Show file tree

Hide file tree

Showing 9 changed files with 171 additions and 3 deletions.
diff --git a/app/views/layouts/preview.html.erb b/app/views/layouts/preview.html.erb
@@ -8,7 +8,7 @@
 </head>
 <body>
   <div class="p-4">
-    <div class="mx-auto" style="max-width: <%= params[:lookbook][:display][:max_width] || "100%" %>">
+    <div class="mx-auto" style="max-width: <%= params.dig(:lookbook, :display, :max_width) || "100%" %>">
       <%= yield %>
     </div>
   </div>

diff --git a/config/application.rb b/config/application.rb
@@ -6,7 +6,6 @@
 require "active_job/railtie"
 require "active_storage/engine"
 require "action_controller/railtie"
-# require "action_mailer/railtie"
 
 require "action_view/railtie"
 require "action_cable/engine"
@@ -21,10 +20,12 @@
 module LookbookDemo
   class Application < Rails::Application
     config.load_defaults 6.1
+    config.public_file_server.enabled = true
 
     config.view_component.default_preview_layout = "preview"
     config.view_component.preview_controller = "PreviewController"
 
+    config.lookbook.project_name = "Lookbook Demo"
     config.lookbook.experimental_features = true # Opt in to ALL experimental features. Not recommended!
   end
 end
diff --git a/public/images/lookbook_screenshot.png b/public/images/lookbook_screenshot.png
diff --git a/test/components/docs/01_overview.md.erb b/test/components/docs/01_overview.md.erb
@@ -0,0 +1,12 @@
+---
+id: about
+title: Lookbook Demo
+---
+
+**This is a demo of Lookbook, a _ready-to-go_ component development UI for [ViewComponent](http://viewcomponent.org/)-based projects.**
+
+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](<%= page_path :annotations %>) 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.
+
+<%= image_tag "lookbook_screenshot.png" %>
diff --git a/test/components/docs/02_previews/01_annotations.md.erb b/test/components/docs/02_previews/01_annotations.md.erb
@@ -0,0 +1,86 @@
+---
+id: annotations
+title: Annotating preview files
+---
+
+Lookbook parses [Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) in your preview class files to customise and extend the standard ViewComponent preview experience.
+
+**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.
+
+## Example preview file:
+
+```ruby
+# @label Basic Button
+# @display bg_color "#fff"
+class ButtonComponentPreview < ViewComponent::Preview
+
+  # 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
+
+  # Button with icon
+  # ----------------
+  # This example uses dynamic preview parameters
+  # 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
+      text
+    end
+  end
+
+  # Inverted button
+  # ---------------
+  # For light-on-dark screens
+  #
+  # @display bg_color "#000"
+  def secondary
+    render ButtonComponent.new(style: :inverted) do
+      "Click me"
+    end
+  end
+
+  # Unicorn button
+  # ---------------
+  # This button style is still a **work in progress**.
+  #
+  # @hidden
+  def secondary
+    render ButtonComponent.new do
+      "Click me"
+    end
+  end
+
+  # @!group More examples
+
+  def short_text
+    render ButtonComponent.new do
+      "Go"
+    end
+  end
+
+  def long_text
+    render ButtonComponent.new do
+      "Click here to do this thing because it's the best way to do it"
+    end
+  end
+
+  def emoji_text
+    render ButtonComponent.new do
+      "👀📗"
+    end
+  end
+
+  # @!endgroup
+
+end
+```
diff --git a/test/components/docs/03_pages/01_overview.md.erb b/test/components/docs/03_pages/01_overview.md.erb
@@ -0,0 +1,35 @@
+---
+title: Pages Overview
+---
+
+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.
+
+**The documentation you are reading right now** is an example what pages look like when they are rendered.
+
+## Usage
+
+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.
+
+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.
+
+Pages can optionally make use of a **YAML frontmatter block** to customise the behaviour and content of the page itself.
+
+An example page might look like this: 
+
+```markdown
+---
+title: An example page
+label: Nice example
+---
+
+This is an example page. If it has a `.md.erb` file extension its
+contents will be run through a Markdown parser/renderer before display.
+
+Fenced code blocks are fully supported and will be highlighted appropriately.
+
+ERB can be used in here.
+The template will be rendered **before** being parsed as Markdown. 
+
+You can can access data about the page using the `@page` variable.
+The title of this page is "&gt;%= @page.title %&lt;".
+```
diff --git a/test/components/docs/03_pages/02_embedding.md.erb b/test/components/docs/03_pages/02_embedding.md.erb
@@ -0,0 +1,26 @@
+---
+label: Embedding Previews
+---
+
+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.
+
+An embedded component preview looks like this:
+
+<%= embed Feedback::BlankSlateComponentPreview, :default, params: { icon: true } %>
+
+To specify which preview example to render, the helper accepts a preview class and a method name (as a symbol), like this:
+
+```erb
+&gt;%= embed Feedback:BlankSlateComponentPreview, :default %&lt;
+```
+
+## Preview params
+
+If you have configured your examples to accept preview params then you can supply values for those params when rendering the embedded preview:
+
+```erb
+&gt;%= embed Feedback:BlankSlateComponentPreview, :default, params: {
+  icon: true,
+  title: "No content yet"
+} %&lt;
+```
diff --git a/test/components/docs/04-documentation.md.erb b/test/components/docs/04-documentation.md.erb
@@ -0,0 +1,7 @@
+---
+label: Further info
+---
+
+These pages are only intended to give an example of what documentation pages in Lookbook look like.
+
+For more info and full documentation, check out the [Lookbook repository &rarr;](https://github.com/allmarkedup/lookbook)
diff --git a/test/components/previews/feedback/blank_slate_component_preview.rb b/test/components/previews/feedback/blank_slate_component_preview.rb
@@ -1,5 +1,6 @@
+# @id blankslate
 class Feedback::BlankSlateComponentPreview < ViewComponent::Preview
-  # Another example with multiple editable preview params.
+  # Another example with multiple editable preview params
   #
   # This example also sets uses a `@display`` tag to
   # set a max width that this component can grow to.