lookbook 2.0.0.beta.3 → 2.0.0.beta.5

data/lib/lookbook/engine.rb

@@ -14,14 +14,21 @@ module Lookbook
       )
     end
 
+    initializer "lookbook.set_autoload_paths" do
+      unless opts.preview_paths.empty?
+        paths_to_add = opts.preview_paths - ActiveSupport::Dependencies.autoload_paths
+        ActiveSupport::Dependencies.autoload_paths.concat(paths_to_add) if paths_to_add.any?
+      end
+    end
+
     config.before_configuration do
       config.lookbook = Lookbook.config
 
       if defined?(ViewComponent)
-        config.lookbook.using_view_component = true
+        config.lookbook.using_view_component ||= true
       else
         require "view_component"
-        config.lookbook.using_view_component = false
+        config.lookbook.using_view_component ||= false
       end
     end
 
@@ -79,7 +86,10 @@ module Lookbook
       end
 
       def auto_refresh?
-        reloading? && runtime_context.web? && FileWatcher.evented?
+        opts.live_updates == true &&
+          reloading? &&
+          runtime_context.web? &&
+          FileWatcher.evented?
       end
 
       def preview_embeds_allowed?
@@ -111,7 +121,7 @@ module Lookbook
       end
 
       def hooks
-        @_hooks ||= HookStore.init_from_config
+        @_hooks ||= HookStore.new
       end
 
       def run_hooks(event_name, *args)
@@ -130,8 +140,8 @@ module Lookbook
 
       def view_paths
         # handle view path registry changes in Rails 7.1
-        paths = if defined?(ActionView::ViewPaths::Registry)
-          ActionView::ViewPaths::Registry.all_file_system_resolvers.map(&:path)
+        paths = if defined?(ActionView::PathRegistry)
+          ActionView::PathRegistry.all_file_system_resolvers.map(&:path)
         else
           ActionView::ViewPaths.all_view_paths.flat_map(&paths)
         end
@@ -156,10 +166,10 @@ module Lookbook
       end
 
       def preview_watch_paths
-        return @_preview_watch_paths if @_preview_watch_paths
-
-        paths = [*opts.preview_paths, *opts.component_paths, *opts.listen_paths, *view_paths].uniq
-        @_preview_watch_paths ||= PathUtils.normalize_paths(paths)
+        @_preview_watch_paths ||= begin
+          paths = [*opts.preview_paths, *opts.component_paths, *opts.listen_paths, *view_paths].uniq
+          PathUtils.normalize_paths(paths)
+        end
       end
 
       def pages
@@ -181,13 +191,17 @@ module Lookbook
         changed_files = [*changes[:added], *changes[:modified]] if changes
         parser.parse(changed_files) do |code_objects|
           previews.load(code_objects.all(:class), changes)
-          mark_changed
         end
+      rescue => e
+        Lookbook.logger.error(e)
+        raise e
       end
 
       def load_pages(changes = nil)
         pages.load(Engine.page_paths, changes)
-        mark_changed
+      rescue => e
+        Lookbook.logger.error(e)
+        raise e
       end
 
       def notify_clients(changes = nil)
@@ -202,15 +216,6 @@ module Lookbook
         reloaders.register_changes(changes)
         notify_clients(changes)
       end
-
-      def mark_changed
-        @_last_changed = (Time.now.to_f * 1000).to_i
-      end
-
-      def last_changed
-        mark_changed unless @_last_changed
-        @_last_changed
-      end
     end
 
     at_exit do

data/lib/lookbook/entities/concerns/annotatable_entity.rb

@@ -1,23 +1,48 @@
 module Lookbook
-  # @api private
   module AnnotatableEntity
     extend ActiveSupport::Concern
 
     included do
       delegate :has_tag?, to: :code_object
 
+      # @!group Annotations
+
+      # Any notes added to the entity.
+      # Returns the raw (unrendered) string which may contain markdown formatting.
+      #
+      # @return [String] The notes, or an empty string if none have been added
       def notes
         code_object.docstring.to_s.strip
       end
 
+      # All tags that have been added to the entity.
+      # Can be filtered by tag name by providing the name as an argument.
+      #
+      # @example :ruby
+      #   all_tags = entity.tags
+      #   display_tags = entity.tags(:display)
+      #
+      # @param name [Symbol] Optional tag type to filter by
+      # @return [Array<YardTag>] Array of tags
       def tags(name = nil)
         code_object.tags(name)
       end
 
+      # The first tag (optionally of a particular type)
+      # added to the entity.
+      #
+      # @example :ruby
+      #   first_tag = entity.tag
+      #   first_display_tag = entity.tag(:display)
+      #
+      # @param name [Symbol] Optional tag type to filter by
+      # @return [Array<YardTag>] Array of tags
       def tag(name = nil)
         tags(name).first
       end
 
+      # @!endgroup
+
       protected
 
       attr_reader :code_object

data/lib/lookbook/entities/concerns/inspectable_entity.rb

@@ -1,9 +1,13 @@
 module Lookbook
-  # @api private
   module InspectableEntity
     extend ActiveSupport::Concern
 
     included do
+      # @!group Source
+
+      # Scenario method source code
+      #
+      # @return [String] The source code0
       def source
         source_code = if custom_source?
           File.read(source_file_path)
@@ -19,10 +23,21 @@ module Lookbook
         source_code.strip_heredoc.strip
       end
 
+      # Source code language info.
+      #
+      # Returns a Hash with `name`, `ext` & `label` entries.
+      #
+      # @example :ruby
+      #   source_lang_name = entity.lang[:name]
+      #
+      # @return [Hash] Language info hash
       def source_lang
         custom_source? ? Lang.guess(source_file_path, :ruby) : Lang.find(:ruby)
       end
 
+      # @!endgroup
+
+      # @api private
       def custom_source?
         source_file_path.present?
       end
@@ -35,7 +50,7 @@ module Lookbook
         @_source_path ||= if code_object.has_tag?(:source)
           source_path = code_object.tag(:source).value
           unless source_path.present? && File.exist?(source_path)
-            raise LookbookError, "Could not find source file '#{source_path}'"
+            raise Lookbook::Error, "Could not find source file '#{source_path}'"
           end
           source_path
         end

data/lib/lookbook/entities/concerns/locatable_entity.rb

@@ -1,40 +1,77 @@
 module Lookbook
-  # @api private
   module LocatableEntity
     extend ActiveSupport::Concern
 
     included do
-      attr_reader :file_path, :base_directories
-
+      # @!group Paths
+
+      # Full path to the entity file
+      #
+      # @return [Pathname] File patj
+      attr_reader :file_path
+
+      # @api private
+      attr_reader :base_directories
+
+      # Name of the entity file.
+      #
+      # Includes file extension unless the `strip_ext` argument is `true`.
+      #
+      # @param strip_ext [Boolean] Whether or not to remove the file extension
+      # @return [String] File name
       def file_name(strip_ext = false)
         basename = file_pathname.basename
         (strip_ext ? basename.to_s.split(".").first : basename).to_s
       end
 
-      def file_name_base
-        @_file_name_slug ||= file_name(true).gsub(/(_component_preview|component_preview|preview)$/, "")
-      end
-
+      # Extension of the entity file.
+      #
+      # @return [String] File extension
       def file_extension
         @_file_extension ||= file_pathname.extname
       end
 
+      # Full directory path for the entity file.
+      #
+      # @return [Pathname] Directory path
       def directory_path
         @_directory_path ||= Pathname(file_pathname.dirname)
       end
 
+      # Relative path to the entity file.
+      #
+      # Returned path is relative to the appropriate base directory
+      # (i.e. the preview directory for previews).
+      #
+      # @return [Pathname] Relative file path
       def relative_file_path
         @_relative_file_path ||= file_pathname.relative_path_from(base_directory)
       end
 
+      # Relative directory path for the entity file.
+      #
+      # Returned path is relative to the appropriate base directory
+      # (i.e. the preview directory for previews).
+      #
+      # @return [Pathname] Relative directory path
       def relative_directory_path
         @_relative_directory_path ||= directory_path.relative_path_from(base_directory)
       end
 
+      # Time that the entity file was last modified
+      #
+      # @return [Time] Time last modified
       def last_modified
         @_last_modified ||= File.mtime(file_path)
       end
 
+      # 'Virtual' path to the entity.
+      #
+      # Determines where the entity is located in heirarchical trees.
+      # Can be altered using the `@logical_path` tag.
+      #
+      # @api private
+      # @return [String] The logical path
       def logical_path
         return @_logical_path if @_logical_path
 
@@ -42,6 +79,13 @@ module Lookbook
         @_logical_path ||= PathUtils.to_path(directory, file_name_base)
       end
 
+      # @!endgroup
+
+      # @api private
+      def file_name_base
+        @_file_name_slug ||= file_name(true)
+      end
+
       alias_method :full_path, :file_path
       alias_method :rel_path, :relative_file_path
       alias_method :dir_path, :directory_path

data/lib/lookbook/entities/concerns/navigable_entity.rb

@@ -1,17 +1,27 @@
 module Lookbook
-  # @api private
   module NavigableEntity
     extend ActiveSupport::Concern
 
     included do
+      # @!group Visibility
+
+      # Whether or not the entity is hidden (i.e. hidden from navigation)
+      #
+      # @return [Boolean] true if hidden
       def hidden?
         fetch_config(:hidden, false)
       end
 
+      # Whether or not the entity is visible (i.e. present in navigation)
+      #
+      # @return [Boolean] true if visible
       def visible?
         !hidden?
       end
 
+      # @!endgroup
+
+      # @api private
       def priority
         return @_priority if @_priority
 
@@ -21,17 +31,25 @@ module Lookbook
           fetch_config(:priority, default_priority)
         end
 
-        @_priority ||= pos.to_i
+        @_priority ||= @_fallback_priority || pos.to_i
+      end
+
+      # @api private
+      def default_priority=(i)
+        @default_priority = i.to_i
       end
 
+      # @api private
       def depth
         lookup_path.split("/").size
       end
 
+      # @api private
       def default_priority
         @default_priority || 10000
       end
 
+      # @api private
       def <=>(other)
         if respond_to?(:sort_handler, true)
           sort_handler(other)

data/lib/lookbook/entities/entity.rb

@@ -1,27 +1,57 @@
 module Lookbook
   # Base entity class
   #
-  # @api private
+  # @api public
   class Entity
     include Comparable
     send(:include, Lookbook::Engine.routes.url_helpers) # YARD parsing workaround: https://github.com/lsegal/yard/issues/546
 
+    # @api private
     def initialize(lookup_path = nil)
       @lookup_path = lookup_path
     end
 
+    # @!group Identity
+
+    # Human-readable unique ID for the entity
+    #
+    # @return [String] The ID
     def id
       Utils.id(fetch_config(:id) { lookup_path.tr("/", "-") })
     end
 
+    # Parameter-safe entity name.
+    #
+    # @return [String] The name
     def name
       @_name ||= Utils.name(File.basename(@lookup_path))
     end
 
+    # Titlized name for use in navigation etc.
+    #
+    # Can be customized using the `@label` tag where supported.
+    #
+    # @return [String] The label
     def label
       @_label ||= fetch_config(:label) { name.titleize }
     end
 
+    # Entity type identifier
+    #
+    # @return [Symbol] The entity type
+    def type
+      @_type ||= self.class.name.gsub("Entity", "").demodulize.underscore.downcase.to_sym
+    end
+
+    # @!endgroup
+
+    # @!group Paths
+
+    # Canonical reference path.
+    #
+    # Used for generating URL paths and looking up entities.
+    #
+    # @return [String] The lookup path
     def lookup_path
       return @_lookup_path if @_lookup_path
 
@@ -32,23 +62,15 @@ module Lookbook
       @_lookup_path ||= PathUtils.strip_slashes(PathUtils.to_path(directory, name))
     end
 
-    def url_path
-      nil
-    end
+    alias_method :path, :lookup_path
+    deprecate path: :lookup_path, deprecator: Deprecation
 
-    def type
-      @_type ||= self.class.name.gsub("Entity", "").demodulize.underscore.downcase.to_sym
-    end
+    # @!endgroup
 
     def <=>(other)
       label <=> other.label
     end
 
-    alias_method :path, :lookup_path
-    alias_method :logical_path, :lookup_path
-
-    deprecate path: :lookup_path, deprecator: Deprecation
-
     protected
 
     def fetch_config(key, fallback = nil, &block)

data/lib/lookbook/entities/page_entity.rb

@@ -1,14 +1,18 @@
 module Lookbook
   # Represents a documentation page
   #
-  # @ignore methods
   # @api public
   class PageEntity < Entity
     include LocatableEntity
     include NavigableEntity
 
-    attr_reader :content, :sections
+    # @api private
+    attr_reader :content
 
+    # @api private
+    attr_reader :sections
+
+    # @api private
     def initialize(file_path)
       @file_path = Pathname(file_path)
       @base_directories = Engine.page_paths
@@ -18,50 +22,104 @@ module Lookbook
       @sections = []
     end
 
+    # @!group Identity
+
+    # Page title, as defined in frontmatter.
+    # Defaults to the page `label` if not provided.
+    #
+    # @return [String] The title
     def title
       @_title ||= fetch_config(:title, label)
     end
 
+    # @!endgroup
+
+    # @!group Frontmatter
+
+    # Merged data hash. Combines `data` set in frontmatter
+    # with any global default values.
+    #
+    # @return [Hash] The resolved data hash
+    def data
+      return @_data if @_data
+
+      config_data = fetch_config(:data, {})
+      @_data ||= config_data.is_a?(Hash) ? Store.new(config_data) : config_data
+    end
+
+    # @!endgroup
+
+    # @!group Predicates
+
+    # Whether the page is the default landing page.
+    #
+    # Set via the `landing` frontmatter property.
+    #
+    # @return [Boolean]
     def landing?
       @_landing ||= fetch_config(:landing, false)
     end
 
+    # Whether the page content should be rendered
+    # with the Markdown renderer.
+    #
+    # Set via the `markdown` frontmatter property.
+    #
+    # @return [Boolean]
     def markdown?
       @_markdown ||= fetch_config(:markdown) { file_path.to_s.match?(/(.*)\.md\.(.*)$/) }
     end
 
+    # Whether the page header will be shown.
+    #
+    # Set via the `header` frontmatter property.
+    #
+    # @return [Boolean]
     def header?
       @_header ||= fetch_config(:header, true)
     end
 
+    # Whether the page footer will be shown.
+    #
+    # Set via the `footer` frontmatter property.
+    #
+    # @return [Boolean]
     def footer?
       @_footer ||= fetch_config(:footer, true)
     end
 
-    def data
-      return @_data if @_data
+    # @!endgroup
 
-      config_data = fetch_config(:data, {})
-      @_data ||= config_data.is_a?(Hash) ? Store.new(config_data) : config_data
+    # @!group URLs
+
+    # The docs URL path for this page.
+    #
+    # @return [String] URL path
+    def docs_path
+      lookbook_page_path(lookup_path)
     end
 
+    alias_method :url_path, :docs_path
+
+    # @!endgroup
+
+    # @api private
     def search_terms
       label
     end
 
-    def url_path
-      lookbook_page_path(lookup_path)
-    end
-
+    # @api private
     def add_section(section)
       @sections << section
       @sections.sort_by! { |section| [section.priority, section.label] }
     end
 
+    # @api private
     def method_missing(method_name, *args, &block)
       method_name.to_s.end_with?("=") ? super : frontmatter.fetch(method_name, nil)
     end
 
+    # @api private
     def respond_to_missing?(method_name, include_private = false)
       frontmatter.key?(method_name) || super
     end

data/lib/lookbook/entities/page_section_entity.rb

@@ -1,4 +1,8 @@
 module Lookbook
+  # Represents a documentation page section.
+  #
+  # @ignore methods
+  # @api private
   class PageSectionEntity < PageEntity
     attr_accessor :parent