lookbook 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ea30d04c53c14779624094908938ce4c795a75a773f24226c7905e12afcdca
-  data.tar.gz: 15b596f54edd9cff72d28cf2c3b88a5d28e05b3a323f69033bd44c50c890c3c2
+  metadata.gz: 79511e3188b92969dfb927515e82464ad712490ed56d4651316f237f2792d9be
+  data.tar.gz: 7afbe921d118e685c4d7ec1619f9431296099a9690947baca8bc041b609e8b46
 SHA512:
-  metadata.gz: 2c998b17b156fae344b99131d7487ba74052d1aeaba6ac9ff2cd2c13371f6aa0f3fb1cea6d47b806d4cd3479d93e678fd165b8f85bc30b2c7e35bac1b2685ea5
-  data.tar.gz: f347430b5596aaefc63c24a1db82758a86f317cc728bd7c8cb1eefe9efd243e3072186b33fc0144fd7f0fea148d584d3b350b2da09b59ba37be37e41b706f4b2
+  metadata.gz: e300adbcb09915cb48862621e6809a5713c8250e9122c109b3eaadcf770c1c11f4ac7865a78caac233b452f38ca05e499899baf07edcce82d499b3110c4580dc
+  data.tar.gz: 4385b86b3115d4ed88d13f8d7b2cb57a15792ac8ccdeb526ff6ffe3a2e35d45b6047b17b10d322d711d7087b26af7f7352aec717f01932263118fd75d40aa475

data/README.md

@@ -13,7 +13,7 @@
 ---
 
 <div align="center">
-<a href="#installing">Installing</a> • <a href="#previews">Previews</a>  • <a href="#pages">Pages</a> • <a href="#config">Configuration</a> 
+<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> 
 </div>
 
 ---
@@ -72,13 +72,6 @@ The `at` property determines the root URL that the Lookbook UI will be served at
 
 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`
-
 
 <h2 id="previews">Previews</h2>
 
@@ -548,7 +541,7 @@ config.lookbook.page_options = {
   footer: false,
   data: {
     brand_colors: {
-      red: #ff0000
+      red: "#ff0000"
     }
   }
 }
@@ -687,6 +680,75 @@ Default: `pages`
 config.lookbook.page_route = `docs`
 ```
 
+<h2 id="deployment">Deploying in Production</h2>
+
+Lookbook is intended to be a tool for aiding the ViewComponent development process, and so is usually restricted to running only when the app is in `development` mode.
+
+However, it is possible to run Lookbook in a production environment if you wish.
+
+### Differences between development and production
+
+By default, Lookbook will behave a little differently in production than it does in development:
+
+1. Watching files for changes is disabled
+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).
+
+### Pre-parsing preview files
+
+Run the following command to pre-parse the preview files annotations:
+
+```
+rake lookbook:previews:preparse
+```
+
+If you wish to run this as part of your existing assets precompilation step, you can add the following into your app's `Rakefile`:
+
+```ruby
+if Rails.env.production?
+  Rake::Task['assets:precompile'].enhance do
+    Rake::Task["lookbook:previews:preparse"].invoke
+  end
+end
+```
+
+The pre-parsing of preview files will then take place every time `rake assets:precompile` is called and so will not need to be run separately.
+
+### Configuration changes for production
+
+You will also need to make sure that the following configuration changes have been made when deploying to production:
+
+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):
+
+```ruby
+# config/environments/production.rb
+config.view_component.show_previews = true
+```
+
+2. Remove any environment checking from around the Lookbook mounting declaration (if added as per install instructions):
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # if Rails.env.development? <- remove
+    mount Lookbook::Engine, at: "/lookbook"
+  # end
+end
+```
+
+### Overriding production default behaviours
+
+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:
+
+```ruby
+# config/environments/production.rb
+
+# enable file-change listening
+config.lookbook.listen = true 
+
+# enable runtime preview parsing
+config.lookbook.runtime_parsing = true 
+```
+
 <h2 id="config">General Configuration</h2>
 
 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.

data/app/assets/lookbook/js/stores/sidebar.js

@@ -3,13 +3,24 @@ import config from "../config";
 export default function createSidebarStore(Alpine) {
   const { defaultWidth, minWidth, maxWidth } = config.sidebar;
   return {
-    open: Alpine.$persist(true).as("sidebar-open"),
+    openDesktop: Alpine.$persist(true).as("sidebar-open-desktop"),
+    openMobile: Alpine.$persist(false).as("sidebar-open-mobile"),
     width: Alpine.$persist(defaultWidth).as("sidebar-width"),
     panelSplits: Alpine.$persist([1.0, 1.0]).as(`sidebar-panel-splits`),
     minWidth,
     maxWidth,
+    get open() {
+      return Alpine.store("sidebar")[
+        Alpine.store("layout").desktop ? "openDesktop" : "openMobile"
+      ];
+    },
     toggle() {
-      Alpine.store("sidebar").open = !Alpine.store("sidebar").open;
+      const sidebar = Alpine.store("sidebar");
+      if (Alpine.store("layout").desktop) {
+        sidebar.openDesktop = !sidebar.openDesktop;
+      } else {
+        sidebar.openMobile = !sidebar.openMobile;
+      }
     },
   };
 }

data/app/controllers/lookbook/previews_controller.rb

@@ -47,6 +47,9 @@ module Lookbook
         if params[:path] == @preview&.lookup_path
           redirect_to show_path "#{params[:path]}/#{@preview.default_example.name}"
         end
+      else
+        first_example = Lookbook.previews.find(params[:path])&.examples&.first
+        redirect_to show_path(first_example.lookup_path) if first_example
       end
     end
 
@@ -143,10 +146,8 @@ module Lookbook
     end
 
     def preview_controller
-      return @preview_controller if @preview_controller.present?
-      controller_class = Lookbook.config.preview_controller.constantize
-      controller_class.class_eval { include Lookbook::PreviewController }
-      controller = controller_class.new
+      return @preview_controller if @preview_controller
+      controller = Lookbook::Engine.preview_controller.new
       controller.request = request
       controller.response = response
       @preview_controller ||= controller

data/app/views/lookbook/previews/panels/_params.html.erb

@@ -1,4 +1,4 @@
-<div class="bg-gray-50 h-full">
+<div class="bg-gray-50 h-full overflow-auto">
   <% if @example.type == :group %>
     <div class="p-4 prose prose-sm">
       <em class='opacity-50'>Params are not yet supported for grouped examples.</em>

data/lib/lookbook/engine.rb

@@ -49,6 +49,7 @@ module Lookbook
       options.preview_srcdoc = false if options.preview_srcdoc.nil?
       options.preview_display_params ||= {}.with_indifferent_access
 
+      options.listen = Rails.env.development? if options.listen.nil?
       options.listen_paths = options.listen_paths.map(&:to_s)
       options.listen_paths += options.preview_paths
       options.listen_paths << (vc_options.view_component_path || Rails.root.join("app/components"))
@@ -57,6 +58,9 @@ module Lookbook
       options.cable_mount_path ||= "/lookbook-cable"
       options.cable_logger ||= Rails.logger
 
+      options.runtime_parsing = !Rails.env.production? if options.runtime_parsing.nil?
+      options.parser_registry_path ||= Rails.root.join("tmp/storage/.yardoc")
+
       options.experimental_features = false unless options.experimental_features.present?
     end
 
@@ -72,32 +76,44 @@ module Lookbook
     end
 
     config.after_initialize do
-      @preview_listener = Listen.to(*config.lookbook.listen_paths, only: /\.(rb|html.*)$/) do |modified, added, removed|
-        begin
-          parser.parse
-        rescue
-        end
-        Lookbook::Preview.clear_cache
-        Lookbook::Engine.websocket&.broadcast("reload", {
-          modified: modified,
-          removed: removed,
-          added: added
-        })
-      end
-      @preview_listener.start
-
-      if Lookbook::Features.enabled?(:pages)
-        @page_listener = Listen.to(*config.lookbook.page_paths.filter { |dir| Dir.exist? dir }, only: /\.(html.*|md.*)$/) do |modified, added, removed|
+      if config.lookbook.listen
+        @preview_listener = Listen.to(*config.lookbook.listen_paths, only: /\.(rb|html.*)$/) do |modified, added, removed|
+          begin
+            parser.parse
+          rescue
+          end
+          Lookbook::Preview.clear_cache
           Lookbook::Engine.websocket&.broadcast("reload", {
             modified: modified,
             removed: removed,
             added: added
           })
         end
-        @page_listener.start
-      end
+        @preview_listener.start
+
+        if Lookbook::Features.enabled?(:pages)
+          @page_listener = Listen.to(*config.lookbook.page_paths.filter { |dir| Dir.exist? dir }, only: /\.(html.*|md.*)$/) do |modified, added, removed|
+            Lookbook::Engine.websocket&.broadcast("reload", {
+              modified: modified,
+              removed: removed,
+              added: added
+            })
+          end
+          @page_listener.start
+        end
 
-      parser.parse
+        if config.lookbook.runtime_parsing
+          parser.parse
+        else
+          unless File.exist?(config.lookbook.parser_registry_path)
+            Lookbook.logger.warn "
+              Runtime parsing is disabled but no registry file has been found.
+              Did you run `rake lookbook:preparse` before starting the app?
+              Expected to find registry file at #{config.lookbook.parser_registry_path}
+            "
+          end
+        end
+      end
     end
 
     at_exit do
@@ -133,7 +149,14 @@ module Lookbook
       end
 
       def parser
-        @parser ||= Lookbook::Parser.new(config.lookbook.preview_paths)
+        @parser ||= Lookbook::Parser.new(config.lookbook.preview_paths, config.lookbook.parser_registry_path)
+      end
+
+      def preview_controller
+        return @preview_controller if @preview_controller
+        controller = Lookbook.config.preview_controller.constantize
+        controller.class_eval { include Lookbook::PreviewController }
+        @preview_controller || controller
       end
     end
   end

data/lib/lookbook/parser.rb

@@ -2,27 +2,31 @@ require "yard"
 
 module Lookbook
   class Parser
-    YARDOC_FILE_PATH = Rails.root.join("tmp/storage/.yardoc").to_s
-
-    def initialize(paths)
+    attr_reader :registry_path
+    def initialize(paths, registry_path)
       @paths = paths.map { |p| "#{p}/**/*preview.rb" }
-      YARD::Registry.yardoc_file = YARDOC_FILE_PATH
+      @registry_path = registry_path.to_s
+      YARD::Registry.yardoc_file = registry_path
     end
 
     def parse
       YARD::Registry.clear
       YARD::Registry.lock_for_writing do
         YARD.parse(@paths)
-        YARD::Registry.save(false, YARDOC_FILE_PATH)
+        YARD::Registry.save(false, registry_path)
       end
     end
 
     def get_code_object(path)
       registry = YARD::RegistryStore.new
-      registry.load!(YARDOC_FILE_PATH)
+      registry.load!(registry_path)
       registry.get(path)
     end
 
+    # def yardoc_file_path
+    #   Rails&.root ? Rails.root.join(YARDOC_FILE_PATH) : YARDOC_FILE_PATH
+    # end
+
     class << self
       def define_tags
         YARD::Tags::Library.define_tag("Hidden status", :hidden)

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "0.7.3"
+  VERSION = "0.8.0"
 end

data/lib/tasks/lookbook_tasks.rake

@@ -1,6 +1,15 @@
 require_relative "../lookbook"
 
 namespace :lookbook do
+
+  namespace :previews do
+    desc "Preparse the previews"
+    task :preparse do
+      Lookbook::Engine.parser.parse
+      puts "Lookbook preview parsing complete"
+    end
+  end
+
   namespace :release do
     desc "Bump the Lookbook engine version number"
     task :bump_version, [:version] do |t, args|