lookbook 1.5.2 → 2.3.7

data/lib/lookbook/entities/collections/preview_collection.rb

@@ -2,40 +2,74 @@ module Lookbook
   class PreviewCollection < EntityCollection
     include HierarchicalCollection
 
-    def find_example_by_path(lookup_path)
-      examples.find_by_path(lookup_path)
+    TREE_BUILDER = PreviewTreeBuilder
+
+    def find_scenario_by_path(lookup_path)
+      scenarios.find_by_path(lookup_path)
     end
 
     def find_by_preview_class(klass)
       find { |preview| preview.preview_class.name == klass.to_s }
     end
 
-    def load(code_objects)
-      @entities = []
-      clear_cache
+    def load(code_objects, changes = nil)
+      changes.present? ? reload_changed(code_objects, changes) : reload_all(code_objects)
+    end
+
+    def reload_all(code_objects)
+      clear_all
+      previews = code_objects.map { |obj| PreviewCollection.preview_from_code_object(obj) }.compact
+      add(previews)
+    end
+
+    def reload_changed(code_objects, changes)
+      modified = Array(changes[:modified])
+      removed = Array(changes[:removed]) + modified
+      added = Array(changes[:added]) + modified
+
+      remove_by_file_path(removed)
+
+      previews = added.map do |path|
+        code_object = code_objects.find { |obj| obj if obj&.file.to_s == path.to_s }
+        PreviewCollection.preview_from_code_object(code_object) if code_object
+      end.compact
 
-      previews = Array(code_objects).map { |obj| PreviewCollection.preview_from_code_object(obj) }.compact
       add(previews)
     end
 
-    def self.preview_from_code_object(code_object)
-      klass = code_object.path.constantize
-      Preview.new(code_object) if preview_class?(klass)
-    rescue => exception
-      Lookbook.logger.error exception.to_s
-      nil
+    def remove_by_file_path(paths)
+      paths = Array(paths).map(&:to_s)
+      @entities.reject! { |preview| preview.file_path.to_s.in?(paths) }
+      clear_cache
     end
 
-    def self.preview_class?(klass)
-      if klass.ancestors.include?(ViewComponent::Preview)
-        !klass.respond_to?(:abstract_class) || klass.abstract_class != true
+    def entities
+      @_cache[:entities] ||= collect_ordered_entities(to_tree(include_hidden: true)).grep(Lookbook::PreviewEntity)
+    end
+
+    class << self
+      def preview_from_code_object(code_object)
+        klass = code_object.path.constantize
+        if preview_class?(klass)
+          preview = PreviewEntity.new(code_object)
+          preview if preview.scenarios.any?
+        end
+      rescue => exception
+        Lookbook.logger.error exception.to_s
+        nil
+      end
+
+      def preview_class?(klass)
+        if (defined?(ViewComponent) && klass.ancestors.include?(ViewComponent::Preview)) || klass.ancestors.include?(Lookbook::Preview)
+          !klass.respond_to?(:abstract_class) || klass.abstract_class != true
+        end
       end
     end
 
     protected
 
-    def examples
-      @_cache[:examples] ||= PreviewExampleCollection.new(flat_map(&:examples))
+    def scenarios
+      @_cache[:scenarios] ||= ScenarioCollection.new(flat_map(&:scenarios))
     end
   end
 end

data/lib/lookbook/entities/collections/render_target_collection.rb

@@ -0,0 +1,4 @@
+module Lookbook
+  class RenderTargetCollection < EntityCollection
+  end
+end

data/lib/lookbook/entities/collections/scenario_collection.rb

@@ -0,0 +1,4 @@
+module Lookbook
+  class ScenarioCollection < EntityCollection
+  end
+end

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

@@ -0,0 +1,84 @@
+module Lookbook
+  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
+
+      def fetch_config(key, fallback = nil, &block)
+        value = case key.to_sym
+        when :renders
+          renders_config
+        when :display_options
+          display_options_config
+        else
+          tag(key).value if has_tag?(key)
+        end
+
+        Utils.value_or_fallback(value, fallback, &block)
+      end
+
+      private
+
+      def renders_config
+        return unless has_tag?(:component) || has_tag?(:renders)
+
+        [*tags(:component), *tags(:renders)].map(&:value).compact
+      end
+
+      def display_options_config
+        return unless has_tag?(:display)
+
+        # Dynamic params set at the entity level are
+        # not (yet?) supported so filter them out.
+        display_tags = tags(:display).select do |tag|
+          !tag.value.is_a?(Hash) && !tag.value.is_a?(Array)
+        end
+
+        display_tags.map { |tag| [tag.key.to_sym, tag.value] }.to_h
+      end
+    end
+  end
+end

data/lib/lookbook/entities/concerns/{inspectable.rb → inspectable_entity.rb}

@@ -1,8 +1,13 @@
 module Lookbook
-  module Inspectable
+  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)
@@ -18,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
@@ -34,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

@@ -0,0 +1,116 @@
+module Lookbook
+  module LocatableEntity
+    extend ActiveSupport::Concern
+
+    included do
+      # @!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
+
+      # 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
+
+        logical_path_value = fetch_config(:logical_path)
+
+        @_logical_path ||= if logical_path_value
+          PathUtils.to_path(logical_path_value, lookup_path.split("/").last)
+        else
+          PathUtils.to_path(lookup_path)
+        end
+      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
+
+      deprecate full_path: :file_path, deprecator: Deprecation
+      deprecate rel_path: :relative_file_path, deprecator: Deprecation
+      deprecate dir_path: :directory_path, deprecator: Deprecation
+
+      protected
+
+      def file_pathname
+        Pathname(file_path)
+      end
+
+      def base_directory
+        return @_base_directory if @_base_directory
+
+        directories = Array(base_directories).map(&:to_s).sort_by { |path| path.split("/").size }.reverse
+        @_base_directory ||= directories.find { |dir| file_path.to_s.start_with?(dir) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Lookbook
+  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
+
+        pos = if @priority_prefixes && respond_to?(:file_name)
+          PriorityPrefixParser.call(file_name).first || fetch_config(:priority, default_priority)
+        else
+          fetch_config(:priority, default_priority)
+        end
+
+        @_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)
+        else
+          [priority, label] <=> [other.priority, other.label]
+        end
+      end
+    end
+  end
+end

data/lib/lookbook/entities/entity.rb

@@ -1,24 +1,57 @@
 module Lookbook
+  # Base entity class
+  #
+  # @api public
   class Entity
     include Comparable
-    include Lookbook::Engine.routes.url_helpers
+    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
 
@@ -29,21 +62,19 @@ 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.demodulize.underscore.downcase.to_sym
+    def search_terms
+      @_search_terms ||= lookup_path.split("/").map(&:titleize)
     end
 
+    # @!endgroup
+
     def <=>(other)
       label <=> other.label
     end
 
-    alias_method :path, :lookup_path
-    alias_method :logical_path, :lookup_path
-
     protected
 
     def fetch_config(key, fallback = nil, &block)

data/lib/lookbook/entities/page_entity.rb

@@ -0,0 +1,142 @@
+module Lookbook
+  # Represents a documentation page
+  #
+  # @api public
+  class PageEntity < Entity
+    include LocatableEntity
+    include NavigableEntity
+
+    # @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
+      @lookup_path = PathUtils.to_lookup_path(relative_file_path)
+      @frontmatter, @content = FrontmatterExtractor.call(file_contents)
+      @priority_prefixes = true
+      @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
+
+    # @!endgroup
+
+    # @!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
+      lookup_path.split("/") << label
+    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
+
+    protected
+
+    def fetch_config(key, fallback = nil, &block)
+      value = frontmatter[key]
+      Utils.value_or_fallback(value, fallback, &block)
+    end
+
+    def file_contents
+      @_file_contents ||= File.read(file_path)
+    end
+
+    def frontmatter
+      @_merged_frontmatter ||= Lookbook.config.page_options.deep_merge(@frontmatter.to_h).deep_symbolize_keys
+    end
+  end
+end

data/lib/lookbook/entities/{page_section.rb → page_section_entity.rb}

@@ -1,5 +1,9 @@
 module Lookbook
-  class PageSection < Page
+  # Represents a documentation page section.
+  #
+  # @ignore methods
+  # @api private
+  class PageSectionEntity < PageEntity
     attr_accessor :parent
 
     def initialize(file_path)