gitlab-lookbook 2.3.14

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

@@ -0,0 +1,57 @@
+module Lookbook
+  class PageCollection < EntityCollection
+    include HierarchicalCollection
+
+    TREE_BUILDER = PageTreeBuilder
+
+    def load(page_paths, changes = nil)
+      file_paths = PageCollection.file_paths(page_paths)
+      reload_all(file_paths) # TODO: Fix incremental reloading
+      # changes.present? ? reload_changed(file_paths, changes) : reload_all(file_paths)
+    end
+
+    def reload_all(file_paths)
+      clear_all
+      add(pages_from_paths(file_paths))
+    end
+
+    def reload_changed(file_paths, changes)
+      modified = Array(changes[:modified])
+      removed = Array(changes[:removed]) + modified
+      added = Array(changes[:added]) + modified
+
+      remove_by_file_path(removed)
+      add(pages_from_paths(added))
+    end
+
+    def remove_by_file_path(paths)
+      paths = Array(paths).map(&:to_s)
+      @entities.reject! { |page| page.file_path.to_s.in?(paths) }
+      clear_cache
+    end
+
+    def pages_from_paths(file_paths)
+      entities = file_paths.map { |path| PageCollection.entity(path) }
+      pages, sections = entities.partition { |page| page.type == :page }
+
+      page_dict = pages.index_by(&:lookup_path)
+      sections.each do |section|
+        parent = page_dict[section.lookup_path]
+        section.parent = parent
+        parent.add_section(section)
+      end
+
+      pages
+    end
+
+    def self.file_paths(directories)
+      directories.flat_map do |dir|
+        PathUtils.normalize_paths(Dir["#{dir}/**/*.html.*", "#{dir}/**/*.md.*", "#{dir}/**/*.md"].sort)
+      end
+    end
+
+    def self.entity(file_path)
+      File.basename(file_path).match?(%r{\[(.*?\w+)\]}) ? PageSectionEntity.new(file_path) : PageEntity.new(file_path)
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+module Lookbook
+  class PreviewCollection < EntityCollection
+    include HierarchicalCollection
+
+    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, 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
+
+      add(previews)
+    end
+
+    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 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 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_entity.rb

@@ -0,0 +1,60 @@
+module Lookbook
+  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)
+        else
+          src = CodeIndenter.call(code_object.source)
+          begin
+            send(:format_source, src)
+          rescue NoMethodError
+            src
+          end
+        end
+
+        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
+
+      protected
+
+      attr_reader :code_object
+
+      def source_file_path
+        @_source_path ||= if code_object.has_tag?(:source)
+          source_path = code_object.tag(:source).value
+          unless source_path.present? && File.exist?(source_path)
+            raise Lookbook::Error, "Could not find source file '#{source_path}'"
+          end
+          source_path
+        end
+      end
+    end
+  end
+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

@@ -0,0 +1,84 @@
+module Lookbook
+  # Base entity class
+  #
+  # @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
+
+      directory = fetch_config(:logical_path) do
+        dir = File.dirname(@lookup_path)
+        dir if !dir.start_with?(".")
+      end
+      @_lookup_path ||= PathUtils.strip_slashes(PathUtils.to_path(directory, name))
+    end
+
+    alias_method :path, :lookup_path
+    deprecate path: :lookup_path, deprecator: Deprecation
+
+    def search_terms
+      @_search_terms ||= lookup_path.split("/").map(&:titleize)
+    end
+
+    # @!endgroup
+
+    def <=>(other)
+      label <=> other.label
+    end
+
+    protected
+
+    def fetch_config(key, fallback = nil, &block)
+      Utils.value_or_fallback(nil, fallback, &block)
+    end
+  end
+end

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